Download OpenAPI specification:Download
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
Engage /
Chatvisor
at
Settings > Developer tools > API keys
.
Authorization: Bearer myaccesstoken
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.
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"
}
This hook is triggered at any change of the customer status. It receives a Conversation
object like the WebHook for new conversations.
Triggered when a new message arrived from a customer.
For the message format see Message
Customers are accounts that interacted with your tenant through a channel and can send and received message
Create a new customer.
id | string The unique identifier |
string E-Mail address | |
firstName | string First name |
lastName | string Last name |
gender | string Enum: "female" "other" "male" "none" The gender |
externalId | string Your ID within your organization |
assignedUser | string Assigned user |
{- "id": "5c593c728b02502bc3f8ffe1",
- "email": "john.doe@example.com",
- "firstName": "John",
- "lastName": "Doe",
- "gender": "MALE",
- "externalId": "12345",
- "assignedUser": "testuser@chatvisor.com"
}
Get agent metrics splitted by conversation
From Date (unix timestamp in milliseconds) | integer <int64> |
To Date (unix timestamp in milliseconds) | integer <int64> |
grouping | string Enum: "TODAY" "TODAY_BY_MINUTE" "LAST_7_DAYS" "LAST_MONTH" "LAST_YEAR" "CUSTOM" "ALL" |
"Select the date range where you want to query"
Get data based on the filters you provided.
Array of objects (ChatReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once."
}
], - "dateFilter": "Select the date range where you want to query"
}
Get conversations with measured metrics included.
From Date (unix timestamp in milliseconds) | integer <int64> |
To Date (unix timestamp in milliseconds) | integer <int64> |
grouping | string Enum: "TODAY" "TODAY_BY_MINUTE" "LAST_7_DAYS" "LAST_MONTH" "LAST_YEAR" "CUSTOM" "ALL" |
"Select the date range where you want to query"
resourceName | string name filter |
sessionId | string sessionId filter |
visitId | string visitId filter |
visitorIds | Array of strings unique visitorId filter |
externalIds | Array of strings unique externalId filter |
statusCode | integer <int32> statuscode filter |
type | string Type filter |
object (BooleanArrayFilterString) Tags filter | |
object (DateFilterAPIDTO) Date filter | |
groupBy | string Enum: "RESOURCE_NAME" "SESSION_ID" "VISIT_ID" "VISITOR_ID" "EXTERNAL_ID" "TYPE" "PATH" "URL" "STATUS_CODE" GroupBy property |
path | string Path filter |
url | string Url filter |
object (Criteria) |
{- "resourceName": "Filters the resources for name",
- "sessionId": "Filters the resources for a specific session",
- "visitId": "Filters the resources for a specific visit",
- "visitorIds": "Filters the resources for a specific visitor",
- "externalIds": "Filters the resources for a visitor with Id set through js api 'CV.user.tag()'",
- "statusCode": 0,
- "type": "Filters the resources for types",
- "tags": "Filters the CoBrowsing sessions for tags",
- "dateFilter": "Select the date range where you want to query",
- "groupBy": "groups the resources by the property and averages resources with the same name in their groups",
- "path": "Filters the resources for a website path",
- "url": "Filters the resources for a website url",
- "criteria": {
- "key": "string",
- "criteriaObject": {
- "empty": true,
- "property1": { },
- "property2": { }
}
}
}
name | string Default: "Name of the opening hours" |
id | string Unique id of the opening hours |
timezoneOffset | integer <int32> Timezone offset |
Array of objects (OpeningHourConditionDTO) | |
Array of objects (OpeningHourHolidayDTO) |
{- "name": "Name of the opening hours",
- "id": "string",
- "timezoneOffset": 1,
- "conditions": [
- {
- "type": "WEEKDAY",
- "weekday": "EVERYDAY",
- "startHours": {
- "hour": 0,
- "minute": 0
}, - "endHours": {
- "hour": 0,
- "minute": 0
}
}
], - "holidays": [
- {
- "fromDate": "2019-08-24T14:15:22Z",
- "toDate": "2019-08-24T14:15:22Z",
- "from": {
- "year": 0,
- "month": 0,
- "day": 0
}, - "to": {
- "year": 0,
- "month": 0,
- "day": 0
}, - "name": "string",
- "countryCode": "string",
- "fixedDate": true,
- "imported": true
}
]
}
Get data based on the filters you provided.
Array of objects (CoBrowseReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once.",
- "tags": "Filters the CoBrowsing sessions for tags"
}
], - "dateFilter": "Select the date range where you want to query"
}
Get data based on the filters you provided.
Array of objects (CoBrowseReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once.",
- "tags": "Filters the CoBrowsing sessions for tags"
}
], - "dateFilter": "Select the date range where you want to query"
}
If the id already exists, it will be overridden.
message | string Text of the system message. |
id | string ID of the system message. |
language | string Language of the system message. |
{- "message": "Hello world",
- "id": "helloworld",
- "language": "en"
}
externalId | string Unique external identifier of the user |
email required | string E-Mail address of the user |
displayName | string Displayname of the user |
description | string Description of the user |
roleId | string Role assigned to user (If the user is an admin, the static constant "ADMIN" is set) |
password | string Password of the user |
tags | Array of strings unique Tags assigned to user |
mcoEnabled | boolean Enables or disables MCO-Integration |
admin | boolean |
{- "externalId": "5c593c728b02502bc3f8ffe1",
- "email": "john.doe@example.com",
- "displayName": "Stephen Brown",
- "description": "Responsible for usecase X",
- "roleId": "5c593c728b02502bc3f8ffe1",
- "password": "Password123",
- "tags": [
- "Support"
], - "mcoEnabled": true,
- "admin": true
}
Get data based on the filters you provided.
Array of objects (AgentReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once."
}
], - "dateFilter": "Select the date range where you want to query"
}
Get times how long the agents where logged in.
From Date (unix timestamp in milliseconds) | integer <int64> |
To Date (unix timestamp in milliseconds) | integer <int64> |
grouping | string Enum: "TODAY" "TODAY_BY_MINUTE" "LAST_7_DAYS" "LAST_MONTH" "LAST_YEAR" "CUSTOM" "ALL" |
"Select the date range where you want to query"
Get times how long the agents where online.
From Date (unix timestamp in milliseconds) | integer <int64> |
To Date (unix timestamp in milliseconds) | integer <int64> |
grouping | string Enum: "TODAY" "TODAY_BY_MINUTE" "LAST_7_DAYS" "LAST_MONTH" "LAST_YEAR" "CUSTOM" "ALL" |
"Select the date range where you want to query"
Recorded website visitor sessions. A session includes the whole path until the visitor closes the browser.
object (Pageable) | |
object (SessionFilter) A tags filter for sessions |
{- "pageable": {
- "pageNumber": 0,
- "pageSize": 0,
- "paged": true,
- "unpaged": true,
- "sort": {
- "sorted": true,
- "unsorted": true,
- "empty": true
}, - "offset": 0
}, - "tagFilter": {
- "tagsFilter": [
- "string"
]
}
}
Get data based on the filters you provided.
Array of objects (RuleReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "ruleIds": [
- "string"
]
}
], - "dateFilter": "Select the date range where you want to query"
}
Get data based on the filters you provided.
Array of objects (MessageReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once."
}
], - "dateFilter": "Select the date range where you want to query"
}
sessionId filter | string |
visitorId filter | Array of strings unique |
externalId filter | Array of strings unique |
object (DateFilterAPIDTO) Date filter | |
object (BooleanArrayFilterString) Tags filter | |
Path filter | string |
Url filter | string |
fileName | string filename filter |
object (Criteria) |
{- "sessionId filter": "Filters for a specific session",
- "visitorId filter": "Filters for a specific visitor",
- "externalId filter": "Filters for a visitor with Id set through API",
- "dateFilter": "Select the date range where you want to query",
- "Tags filter": "Filters the CoBrowsing sessions for tags",
- "Path filter": "Filters the resources for a website path",
- "Url filter": "Filters the resources for a website url",
- "fileName": "Filters the errors for a file",
- "criteria": {
- "key": "string",
- "criteriaObject": {
- "empty": true,
- "property1": { },
- "property2": { }
}
}
}
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
Get data based on the filters you provided.
Array of objects (SessionReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once."
}
], - "dateFilter": "Select the date range where you want to query"
}
Generates two Universal CoBrowsing links with a random session id. One for the host and one for the user(s) to join the session.
url required | string The url the Universal CoBrowsing session should start with |
userEmail | string The email of the tenant user, which hosts this session |
id | string The unique identifier |
name | string The name |
members | Array of strings Team members (The ids of the team member users) |
tags | Array of strings unique Tags of the team |
{- "id": "5c593c728b02502bc3f8ffe1",
- "name": "Product X experts",
- "members": [
- "string"
], - "tags": [
- "string"
]
}
Get data based on the filters you provided.
Array of objects (SessionMetricReasonReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once."
}
], - "dateFilter": "Select the date range where you want to query"
}
Get data based on the filters you provided.
Array of objects (VisitReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once.",
- "tags": "Filters the CoBrowsing sessions for tags",
- "visitorIds": "Filters the visits for visitorIds",
- "externalIds": "Filters the visits for Id´s set through the JS API",
- "baseUrl": "Filters the visits for URLs that start with given base"
}
], - "dateFilter": "Select the date range where you want to query"
}
Get data based on the filters you provided.
Array of objects (VisitReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once.",
- "tags": "Filters the CoBrowsing sessions for tags",
- "visitorIds": "Filters the visits for visitorIds",
- "externalIds": "Filters the visits for Id´s set through the JS API",
- "baseUrl": "Filters the visits for URLs that start with given base"
}
], - "dateFilter": "Select the date range where you want to query"
}
Get data based on the filters you provided.
Array of objects (ConferenceReportMetricFilterEntryAPIDTO) Metric filters | |
object (DateFilterAPIDTO) Date filter |
{- "metrics": [
- {
- "metricName": "Choose the metric",
- "groupBy": "When group is set, only one metric should be queried at once."
}
], - "dateFilter": "Select the date range where you want to query"
}
id | string |
name | string |
watchdogType | string Enum: "JAVASCRIPT_ERROR" "MESSAGE_RECEIVED" "CUSTOMER_ASSIGNED" "FORM_SUBMISSION" "SETTING_CHANGED" |
Array of objects (WatchdogReceiver) |
{- "id": "string",
- "name": "string",
- "watchdogType": "JAVASCRIPT_ERROR",
- "receivers": [
- "Defined SLA receivers if no target is matched"
]
}
Create a rule.
name | string Name of the routing rule. |
Array of HAS_ID (object) or HasTagRuleConditionAPIDTO (object) or NoAnswerRuleConditionAPIDTO (object) or OpeningHourRuleConditionAPIDTO (object) or UrlRoutingRuleConditionAPIDTO (object) The conditions when the rule should match. | |
types | Array of strings unique Items Enum: "CHAT" "CALL" For which type the rule should be applied. |
elseRules | Array of objects (RoutingRule) Fallback rules when the actual rule does not match. |
Array of QueueRoutingAction (object) or RoutingToRoutingAction (object) or SendFlowRoutingAction (object) or SystemMessageRoutingAction (object) Actions which should be triggered for the rule. |
{- "name": "string",
- "conditions": [
- {
- "type": "URL"
}
], - "types": [
- "CHAT"
], - "elseRules": [
- { }
], - "actions": [
- {
- "type": "ROUTING_TO"
}
]
}
Manage and list your tenants. For authentication please use the private user key what you can generate at Settings/API
The request body is used as the message text.
customerId required | string The id of the customer |
isExternalId required | boolean The id is an external id |
message | string Text message |
type required | string Enum: "MESSAGE" "AUDIO" "VIDEO" "FILE" "CARD" Type of message |
url | string URL to file |
buttonLink | string Link of button |
buttonText | string Text of button |
{- "message": "string",
- "type": "MESSAGE",
- "url": "string",
- "buttonLink": "string",
- "buttonText": "string"
}
Create a rule.
name | string Name of the routing rule. |
Array of HAS_ID (object) or HasTagRuleConditionAPIDTO (object) or NoAnswerRuleConditionAPIDTO (object) or OpeningHourRuleConditionAPIDTO (object) or UrlRoutingRuleConditionAPIDTO (object) The conditions when the rule should match. | |
object (SLATrigger) Default: "Defined SLA response times" | |
Array of objects (WatchdogReceiver) Default: "Defined SLA receivers if no target is matched" | |
watchdogEnabled | boolean |
{- "name": "string",
- "conditions": [
- {
- "type": "URL"
}
], - "trigger": "Defined SLA response times",
- "receivers": "Defined SLA receivers if no target is matched",
- "watchdogEnabled": true
}
Create an appointment.
title required | string Title |
description | string Description |
durationInMinutes | integer <int32> Duration |
date | string <date-time> Date of the appointment |
timezoneId | string TimezoneID |
record | boolean If appointment is automatically recorded |
owner | string Owner of the appointment |
password | string Password of the appointment |
attendees | Array of strings unique Attendee e-mails |
sendInviteEmail | boolean Send invite emails to all attendees |
customerId | string CustomerId of the appointment |
valid | boolean If appointment is valid (default = true) |
validAfter | integer <int32> Valid for X hours after the appointment |
validBefore | integer <int32> Valid for X hours before the appointment |
validType | string Enum: "HOURS" "APPOINTMENT" How long the appointment link should be valid |
object Custom properties for the appointment | |
object (AppointmentAPIPermissions) Permissions for the specific conference |
{- "title": "Testappointment",
- "description": "Testdescription",
- "durationInMinutes": 30,
- "date": "2019-08-24T14:15:22Z",
- "timezoneId": "Europe/Vienna",
- "record": false,
- "owner": "test@test.com",
- "password": "testpassword",
- "attendees": "[ test@test.com, test1@test.com ]",
- "sendInviteEmail": true,
- "customerId": "13245",
- "valid": true,
- "validAfter": 13245,
- "validBefore": 13245,
- "validType": "HOURS",
- "customProperties": {
- "property1": "propertyvalue"
}, - "permissions": {
- "enableWaitingRoom": true
}
}
Update an appointment.
appointmentId required | string Example: 5c593c9c8b02502bc3f8ffe3 The identifier of the appointment to update |
title required | string Title |
description | string Description |
durationInMinutes | integer <int32> Duration |
date | string <date-time> Date of the appointment |
timezoneId | string TimezoneID |
record | boolean If appointment is automatically recorded |
owner | string Owner of the appointment |
password | string Password of the appointment |
attendees | Array of strings unique Attendee e-mails |
sendInviteEmail | boolean Send invite emails to all attendees |
customerId | string CustomerId of the appointment |
valid | boolean If appointment is valid (default = true) |
validAfter | integer <int32> Valid for X hours after the appointment |
validBefore | integer <int32> Valid for X hours before the appointment |
validType | string Enum: "HOURS" "APPOINTMENT" How long the appointment link should be valid |
object Custom properties for the appointment | |
object (AppointmentAPIPermissions) Permissions for the specific conference |
{- "title": "Testappointment",
- "description": "Testdescription",
- "durationInMinutes": 30,
- "date": "2019-08-24T14:15:22Z",
- "timezoneId": "Europe/Vienna",
- "record": false,
- "owner": "test@test.com",
- "password": "testpassword",
- "attendees": "[ test@test.com, test1@test.com ]",
- "sendInviteEmail": true,
- "customerId": "13245",
- "valid": true,
- "validAfter": 13245,
- "validBefore": 13245,
- "validType": "HOURS",
- "customProperties": {
- "property1": "propertyvalue"
}, - "permissions": {
- "enableWaitingRoom": true
}
}
Update appointment properties.
appointmentId required | string Example: 5c593c9c8b02502bc3f8ffe3 The identifier of the appointment to update |
record | boolean If appointment is automatically recorded |
{- "record": false
}
Generate a public link by session id (with user, who is automatically logged in) which joins a LiveView session
sessionId required | string The sessionId of the session |
email required | string The email of the user |
language | string Desired UI language (Default: en, Available: en,de,jp,uk,ru) |