Chatvisor API (v1)

Download OpenAPI specification:Download

Authentication

The API uses a token based authentication mechanism. A client sends a token as an URL parameter or as a Bearer Token with every request in order to authenticate itself. Tokens can be created by any admin user in the Backend Settings at Settings > API > Keys.

Example: URL Parameter

https://app.chatvisor.com/rest/v1/example?access_token=myaccesstoken

Example: Bearer Token

Authorization: Bearer myaccesstoken

token

Security scheme type: API Key
query parameter name: access_token

Bearer_Token

Security scheme type: API Key
header parameter name: Authorization

WebHooks

In order to deliver real-time information about customer interactions, a web hook mechanism is used. REST endpoints configured by the admin user are notified by a HTTP POST request of certain events.

New conversation

This WebHook is triggered if a new customer is created or a existing customer changes from the state "DONE" to "UNREAD". It sends a Conversation object as defined below:

{
  "customerId": "string",
  "status": "UNREAD | DONE | UNRESOLVED",
  "lastMessage": {
    "test": "string"
  },
  "url": "string"
}

Status change

This hook is triggered at any change of the customer status. It receives a Conversation object like the WebHook for new conversations.

New message

Triggered when a new message arrived from a customer.

For the message format see Message

New subscriber

Triggered when a customer subscribes to a category.

For the message format see Customer

Customer

Customers are accounts that interacted with your tenant through a channel and can send and received message

List all customers

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>
unused
string

unused

Responses

200

OK

401

Authentication failed

get /rest/v1/customer
https://api.chatvisor.com/rest/v1/customer

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Retrieve a customer

Authorizations:
Bearer_Token (global) token (global)
path Parameters
customerId
required
string

The id of the customer to retrieve

Responses

200

OK

401

Authentication failed

404

Customer not found

get /rest/v1/customer/{customerId}
https://api.chatvisor.com/rest/v1/customer/{customerId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "additionalInformation":
    {
    },
  • "assignedTeam": "string",
  • "assignedUser": "string",
  • "firstName": "John",
  • "gender": "male",
  • "id": "5c593c728b02502bc3f8ffe1",
  • "lastName": "Doe",
  • "locale": "en",
  • "status": "DONE",
  • "subscriptions": "5c593c728b02502bc3f8ffe1, 5c593c728b02502bc3f8ffe2",
  • "tags": "interested, Product 1000"
}

Assign customer

Assign the customer to a user or to a team. Team and user are mutually exclusive

Authorizations:
Bearer_Token (global) token (global)
path Parameters
customerId
required
string

The id of the customer

query Parameters
teamId
string

The id of the team

userId
string

The id of the user

Responses

200

OK

404

Customer not found

post /rest/v1/customer/{customerId}/assign
https://api.chatvisor.com/rest/v1/customer/{customerId}/assign

Set status

Set the status of a customer manually.

Authorizations:
Bearer_Token (global) token (global)
path Parameters
customerId
required
string

The id of the customer

Request Body schema: application/json
string
Enum:"UNREAD" "DONE" "UNRESOLVED" "MY"

Responses

200

OK

404

Customer not found

post /rest/v1/customer/{customerId}/status
https://api.chatvisor.com/rest/v1/customer/{customerId}/status

Request samples

application/json
Copy
Expand all Collapse all
"UNREAD"

Subscribe to category

Subscribe a customer to a category as defined in the Category API resource

Authorizations:
Bearer_Token (global) token (global)
path Parameters
customerId
required
string

The id of the customer to subscribe

query Parameters
categoryId
required
string

The id of the category to subscribe the customer to

Responses

200

OK

404

Customer not found

post /rest/v1/customer/{customerId}/subscription
https://api.chatvisor.com/rest/v1/customer/{customerId}/subscription

Unsubscribe from category

Authorizations:
Bearer_Token (global) token (global)
path Parameters
customerId
required
string

The id of the customer to unsubscribe

query Parameters
categoryId
required
string

The id of the category to subscribe the customer from

Responses

200

OK

404

Customer not found

delete /rest/v1/customer/{customerId}/subscription
https://api.chatvisor.com/rest/v1/customer/{customerId}/subscription

Role

Manage roles of users

List all defined roles

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/role
https://api.chatvisor.com/rest/v1/role

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Retrieve a role

Authorizations:
Bearer_Token (global) token (global)
Request Body schema: application/json
string

Responses

200

OK

401

Authentication failed

get /rest/v1/role/{roleId}
https://api.chatvisor.com/rest/v1/role/{roleId}

Request samples

application/json
Copy
Expand all Collapse all
"string"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5c593c728b02502bc3f8ffe1",
  • "name": "Manager",
  • "permissions":
    [
    ]
}

Delete a role

Authorizations:
Bearer_Token (global) token (global)
path Parameters
roleId
required
string

The id of the role to delete

Responses

200

OK

404

Role not found

delete /rest/v1/role/{roleId}
https://api.chatvisor.com/rest/v1/role/{roleId}

Team

Teams are group of users that a user can be assigned to

List all teams

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>
unused
string

unused

Responses

200

OK

401

Authentication failed

get /rest/v1/team
https://api.chatvisor.com/rest/v1/team

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Create a team

Authorizations:
Bearer_Token (global) token (global)
Request Body schema: application/json
id
string

The unique identifier

members
Array of string

Team members (The ids of the team member users)

name
string

The name

Responses

200

OK

post /rest/v1/team
https://api.chatvisor.com/rest/v1/team

Request samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5c593c728b02502bc3f8ffe1",
  • "members":
    [
    ],
  • "name": "Product X experts"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5c593c728b02502bc3f8ffe1",
  • "members":
    [
    ],
  • "name": "Product X experts"
}

Retrieve a team

Authorizations:
Bearer_Token (global) token (global)
path Parameters
teamId
required
string

The id of the team to retrieve

Responses

200

OK

401

Authentication failed

404

Team not found

get /rest/v1/team/{teamId}
https://api.chatvisor.com/rest/v1/team/{teamId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5c593c728b02502bc3f8ffe1",
  • "members":
    [
    ],
  • "name": "Product X experts"
}

Delete a team

Authorizations:
Bearer_Token (global) token (global)
path Parameters
teamId
required
string

The id of the team to delete

Responses

200

OK

404

Team not found

delete /rest/v1/team/{teamId}
https://api.chatvisor.com/rest/v1/team/{teamId}

Add user

Adds a user to an existing team

Authorizations:
Bearer_Token (global) token (global)
path Parameters
teamId
required
string

The id of the team

query Parameters
userId
required
string

The id of the user to add

Responses

200

OK

404

Team not found

post /rest/v1/team/{teamId}/add
https://api.chatvisor.com/rest/v1/team/{teamId}/add

User

Manage users of your tenant

List all users

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/user
https://api.chatvisor.com/rest/v1/user

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Create a new user

Authorizations:
Bearer_Token (global) token (global)
Request Body schema: application/json
email
string

E-Mail address of the user

roleId
string

Role assigned to user (If the user if a admin, the static constant "ADMIN" is set)

Responses

200

OK

post /rest/v1/user
https://api.chatvisor.com/rest/v1/user

Request samples

application/json
Copy
Expand all Collapse all
{
  • "email": "john.doe@example.com",
  • "roleId": "5c593c728b02502bc3f8ffe1"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "email": "john.doe@example.com",
  • "id": "5c593c728b02502bc3f8ffe1",
  • "roleId": "5c593c728b02502bc3f8ffe1"
}

Retrieve a user

Authorizations:
Bearer_Token (global) token (global)
path Parameters
userId
required
string

The unique identifier of the user

Responses

200

OK

401

Authentication failed

get /rest/v1/user/{userId}
https://api.chatvisor.com/rest/v1/user/{userId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "email": "john.doe@example.com",
  • "id": "5c593c728b02502bc3f8ffe1",
  • "roleId": "5c593c728b02502bc3f8ffe1"
}

Delete a user

Authorizations:
Bearer_Token (global) token (global)
path Parameters
userId
required
string

The id of the user to delete

Responses

200

OK

404

User not found

delete /rest/v1/user/{userId}
https://api.chatvisor.com/rest/v1/user/{userId}

Assign a user to a role

Adds a user to an existing role

Authorizations:
Bearer_Token (global) token (global)
path Parameters
userId
required
string

The id of the user to assign

query Parameters
roleId
string

The identifier of the role that should be assigned to the user

Responses

200

OK

404

User not found

post /rest/v1/user/{userId}/assign
https://api.chatvisor.com/rest/v1/user/{userId}/assign

Activity

View information about user activity in backend. These are log events of certain parts of the application, for instance when a user sends a message or calls a customer

Call

Events that happen when a user calls a customer

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/activity/call
https://api.chatvisor.com/rest/v1/activity/call

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

LiveChat

Message send events

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/activity/livechat
https://api.chatvisor.com/rest/v1/activity/livechat

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

LiveView

Events for Cobrowsing (e.g. a session is started)

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/activity/liveview
https://api.chatvisor.com/rest/v1/activity/liveview

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Status

Changes in the status of a customer (e.g. user sets the customer status to DONE)

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/activity/status
https://api.chatvisor.com/rest/v1/activity/status

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Statistics

Statistics API Resource

LiveChat

Retrieves statistics about LiveChat conversations

Authorizations:
Bearer_Token (global) token (global)
query Parameters
from
integer <int64>
Example: 1553593383000

Start timestamp (UNIX timestamp with milliseconds)

to
integer <int64>
Example: 1553593383000

End timestamp (UNIX timestamp with milliseconds)

Responses

200

OK

401

Authentication failed

get /rest/v1/statistic/livechat
https://api.chatvisor.com/rest/v1/statistic/livechat

Response samples

application/json
Copy
Expand all Collapse all
{
  • "averageChatDuration": 22,
  • "numberOfChats": 10,
  • "startUrls":
    {
    }
}

LiveView

Retrieves statistics about LiveView sessions

Authorizations:
Bearer_Token (global) token (global)
query Parameters
from
integer <int64>
Example: 1553593383000

Start timestamp (UNIX timestamp with milliseconds)

to
integer <int64>
Example: 1553593383000

End timestamp (UNIX timestamp with milliseconds)

Responses

200

OK

401

Authentication failed

get /rest/v1/statistic/liveview
https://api.chatvisor.com/rest/v1/statistic/liveview

Response samples

application/json
Copy
Expand all Collapse all
{
  • "browsers":
    {
    },
  • "devices":
    {
    },
  • "numberOfSessions": 5
}

Article

Articles are messages that can contain text, images and buttons and can be sent to customers in a category.

List all articles

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/article
https://api.chatvisor.com/rest/v1/article

Response samples

application/json
Copy
Expand all Collapse all
{}

Create an article

To upload an image use the upload field.

Authorizations:
Bearer_Token (global) token (global)
Request Body schema: application/json
name
string

The name (title)

description
string

The description

price
number <double>

The price value

categoryId
string

The unique category id

url
string

The url

upload
object (EmbeddedImage)

Responses

200

OK

post /rest/v1/article
https://api.chatvisor.com/rest/v1/article

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "This is my article",
  • "description": "This article contains stories about messenger marketing",
  • "price": 9.99,
  • "categoryId": "5c593c418b02502bc3f8ffde",
  • "upload":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{}

Retrieve an article

Authorizations:
Bearer_Token (global) token (global)
path Parameters
articleId
required
string
Example: "5c593c9c8b02502bc3f8ffe3"

The identifier of the article to retrieve

Responses

200

OK

401

Authentication failed

404

Article not found

get /rest/v1/article/{articleId}
https://api.chatvisor.com/rest/v1/article/{articleId}

Response samples

application/json
Copy
Expand all Collapse all
{}

Delete an article

Authorizations:
Bearer_Token (global) token (global)
path Parameters
articleId
required
string
Example: "5c593c9c8b02502bc3f8ffe3"

The identifier of the article to delete

Responses

200

The article was deleted

404

Article not found

delete /rest/v1/article/{articleId}
https://api.chatvisor.com/rest/v1/article/{articleId}

Message

Manage chat messages to and from customers including sending new messages

List all messages

Authorizations:
Bearer_Token (global) token (global)
query Parameters
customerId
string

The id of the customer to filter the message

offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/message
https://api.chatvisor.com/rest/v1/message

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Send a message

The request body is used as the message text.

Authorizations:
Bearer_Token (global) token (global)
path Parameters
customerId
required
string

The id of the customer

Request Body schema: application/json
string

Responses

200

Message was sent successfully

400

Message format cannot be accepted

post /rest/v1/message/{customerId}
https://api.chatvisor.com/rest/v1/message/{customerId}

Request samples

application/json
Copy
Expand all Collapse all
"string"

Broadcast

Broadcasts are planned messages to certain subscribers

List all broadcasts

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/broadcast
https://api.chatvisor.com/rest/v1/broadcast

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Retrieve all statistics

Retrieves statistics for all broadcasts as a list

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>

Responses

200

OK

401

Authentication failed

get /rest/v1/broadcast/statistics
https://api.chatvisor.com/rest/v1/broadcast/statistics

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Retrieve a broadcast

Authorizations:
Bearer_Token (global) token (global)
path Parameters
broadcastId
required
string

Identifier of the broadcast

Responses

200

OK

401

Authentication failed

get /rest/v1/broadcast/{broadcastId}
https://api.chatvisor.com/rest/v1/broadcast/{broadcastId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5c593c728b02502bc3f8ffe1",
  • "name": "My broadcast",
  • "notification": "PUSH",
  • "referenceId": "PENDING",
  • "scheduling":
    {
    },
  • "sendType": "STANDARD",
  • "status": "PENDING",
  • "targetFilter":
    [
    ],
  • "type": "DIRECT"
}

Retrieve statistics

Authorizations:
Bearer_Token (global) token (global)
path Parameters
broadcastId
required
string

Identifier of the broadcast

Responses

200

OK

401

Authentication failed

404

Broadcast not found

get /rest/v1/broadcast/{broadcastId}/statistics
https://api.chatvisor.com/rest/v1/broadcast/{broadcastId}/statistics

Response samples

application/json
Copy
Expand all Collapse all
{
  • "clickCount": 180,
  • "id": "5c593c728b02502bc3f8ffe1",
  • "reachedCount": 300,
  • "readCount": 200,
  • "redirectClickCount": 175
}

Stop

Stop a running broadcast. No messages will be sent until the broadcast is started again

Authorizations:
Bearer_Token (global) token (global)
path Parameters
referenceId
required
string

Reference to a running broadcast

Responses

200

OK

401

Authentication failed

get /rest/v1/broadcast/{referenceId}/stop
https://api.chatvisor.com/rest/v1/broadcast/{referenceId}/stop

Category

Categories are message channels (e.g. "News", "Special offers", …) that customers can subscribe to

List all categories

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>
unused
string

unused

Responses

200

OK

401

Authentication failed

get /rest/v1/category
https://api.chatvisor.com/rest/v1/category

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Retrieve a category

Authorizations:
Bearer_Token (global) token (global)
path Parameters
categoryId
required
string

The id of the category to retrieve

Responses

200

OK

401

Authentication failed

404

Category not found

get /rest/v1/category/{categoryId}
https://api.chatvisor.com/rest/v1/category/{categoryId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "description": "Contains articles about new products",
  • "id": "5c593c728b02502bc3f8ffe1",
  • "name": "Product updates",
  • "parentCategoryId": "5c593c728b02502bc3f8ffe2"
}

Delete a category

Authorizations:
Bearer_Token (global) token (global)
path Parameters
categoryId
required
string

The id of the category to delete

Responses

200

OK

404

Article not found

delete /rest/v1/category/{categoryId}
https://api.chatvisor.com/rest/v1/category/{categoryId}

Conversation

All live chat conversations and their duration.

List conversations

List all conversations with the given filter

Authorizations:
Bearer_Token (global) token (global)
query Parameters
from
integer <int64>
Example: 1553593383000

Start timestamp (UNIX timestamp with milliseconds)

to
integer <int64>
Example: 1553593383000

End timestamp (UNIX timestamp with milliseconds)

Responses

200

OK

401

Authentication failed

get /rest/v1/conversation
https://api.chatvisor.com/rest/v1/conversation

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

LiveView by session id

Generate a public link by session id which joins a LiveView session

Authorizations:
Bearer_Token (global) token (global)
path Parameters
sessionId
required
string

The sessionId of the session

Responses

200

OK

401

Authentication failed

get /rest/v1/publiclink/liveview/bySessionId/{sessionId}
https://api.chatvisor.com/rest/v1/publiclink/liveview/bySessionId/{sessionId}

Response samples

application/json
Copy
Expand all Collapse all
"string"

LiveView by share id

Generate a public link by share id which joins a LiveView session

Authorizations:
Bearer_Token (global) token (global)
path Parameters
shareId
required
string

The shareId of the session

Responses

200

OK

401

Authentication failed

get /rest/v1/publiclink/liveview/byShareId/{shareId}
https://api.chatvisor.com/rest/v1/publiclink/liveview/byShareId/{shareId}

Response samples

application/json
Copy
Expand all Collapse all
"string"

Session

Recorded website visitor sessions. A session includes the whole path until the visitor closes the browser.

List all sessions

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>
unused
string

unused

Responses

200

OK

401

Authentication failed

get /rest/v1/session
https://api.chatvisor.com/rest/v1/session

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Find sessions with a filter

Authorizations:
Bearer_Token (global) token (global)
query Parameters
offset
integer <int32>
pageNumber
integer <int32>
pageSize
integer <int32>
Request Body schema: application/json
browser
Array of string
countries
Array of string
duration
integer <int32>
fromDate
string <date-time>
interactions
integer <int32>
labels
Array of string
os
Array of string
pattern
string
toDate
string <date-time>
userActivityDuration
integer <int32>
wtf
integer <int32>

Responses

200

OK

post /rest/v1/session
https://api.chatvisor.com/rest/v1/session

Request samples

application/json
Copy
Expand all Collapse all
{
  • "browser":
    [
    ],
  • "countries":
    [
    ],
  • "duration": 0,
  • "fromDate": "2019-04-17T06:09:29Z",
  • "interactions": 0,
  • "labels":
    [
    ],
  • "os":
    [
    ],
  • "pattern": "string",
  • "toDate": "2019-04-17T06:09:29Z",
  • "userActivityDuration": 0,
  • "wtf": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "results":
    [
    ]
}

Retrieve a session

Authorizations:
Bearer_Token (global) token (global)
path Parameters
sessionId
required
string

The id of the session to retrieve

Responses

200

OK

401

Authentication failed

404

Session not found

get /rest/v1/session/{sessionId}
https://api.chatvisor.com/rest/v1/session/{sessionId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "analytics":
    {
    },
  • "id": "5c593c728b02502bc3f8ffe1",
  • "location":
    {
    },
  • "startDomain": "https://example.com",
  • "startPath": "/index",
  • "tags":
    [
    ],
  • "userAgentInfo":
    {
    },
  • "visitorId": "5c593c728b02502bc3f8ffe1"
}

Delete a session

Authorizations:
Bearer_Token (global) token (global)
path Parameters
sessionId
required
string

The id of the session to delete

Responses

200

OK

404

Session not found

delete /rest/v1/session/{sessionId}
https://api.chatvisor.com/rest/v1/session/{sessionId}