All APIs will be designed with the spirit of the DI API Guidelines in mind.
- GET /v1/status/{product}
- GET /v1/product/{product}/config
- GET /v1/product/{product}/loader
- GET /v1/product/{product}/status
- GET /v1/client/configuration
- POST /v1/start
- POST /v1/hello
- PUT /v1/trigger
- PUT /v1/trigger/multiple
- PUT /v1/talk
- GET /v1/listen
- PUT /v1/feedback/message/{id}
- POST /v1/goodbye
- GET /v1/ping
- POST /v1/logging/{level}
For most API endpoints, request/response body encryption will be applied. The documentation below describes the unencrypted format.
See Payload Encryption for more details.
GET /v1/status/{product}
Retrieves the status of the given product. This endpoint is not encrypted.
Deprecated. Use GET /v1/product/{product}/status instead.
Path Parameters
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
product | String | yes | 2.0 | The product's key |
Response Body
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
product | String | yes | 2.0 | The sanitized version of the product key |
enabled | Boolean | yes | 2.0 | True if the chatbot is enabled for this product, false otherwise |
healthy | Boolean | yes | 2.0 | True if the chatbot is healthy for this product, false otherwise Currently always true until actual health checks implemented. |
GET /v1/product/{product}/config
Returns the client configuration for a given product.
Path Parameters
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
product | String | yes | 2.0 | The product's key |
Response Body
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
enabled | Boolean | yes | 2.0 | True if the product is enabled, false otherwise. |
docked | Boolean | yes | 2.0 | True if the client is running in docked mode, false otherwise. |
opened | Boolean | yes | 2.0 | True if the client is to be open by default, false otherwise. |
customLauncherSelector | String | no | 2.0 | The CSS selector to identify the element that opens the client. |
hideDefaultLauncher | Boolean | yes | 2.0 | True if the client is to hide the default launcher, false to keep it visible. |
horizontalPosition | Enumeration | yes | 2.0 | left to position the client on the left side, right to position it on the right. |
verticalPosition | Enumeration | yes | 2.0 | top to position the client on the top of the page, bottom to position it on the bottom. |
playNotificationAudio | Boolean | yes | 2.0 | True to play notification audio, false otherwise. |
useNotificationAPI | Boolean | yes | 2.0 | True to make use of the browser's Notifications API, false otherwise. |
pollingInterval | Integer | yes | 2.0 | The number of milliseconds between calls to GET /v1/listen. |
product | String | yes | 2.0 | The product key. This is a copy of the product path parameter. |
themeName | String | no | 2.0 | If not null, specifies a theme other than the product's default theme. |
locales | String[] | yes | 2.0 | The locales supported by the product. |
modules | Map<String,Module> | yes | 2.0 | The modules enabled for this client. |
modules[chatbot] | ChatbotModule | yes | 2.0 | Configuration of Chatbot integration. |
modules[zendeskChat] | ZendeskChatModule | no | 2.0 | Configuration of Zendesk Chat integration. |
modules[popupChat] | PopupChatModule | no | 2.3 | Configuration of the Popup Chat integration. |
plugins | Map<String,Plugin> | no | 2.0 | The plugins enabled for this client. |
plugins[cto] | CTOPlugin | no | 2.0 | CTO/Omniture tracking plugin configuration. |
plugins[oneid] | OneIDPlugin | no | 2.0 |
GET /v1/product/{product}/loader
Redirects to the configured loader script for the specified product. This endpoint may be used as the src attribute of a <script></script> element. This endpoint is not encrypted.
Path Parameters
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
product | String | yes | 2.0 | The product's key |
Query Parameters
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
v | String | no | 2.0 | An alternate version of the client to load. This is for testing purposes. |
Response
The server will respond with HTTP 307 - Temporary Redirect. The redirect URL will be to the JavaScript file used to load the chatbot client.
GET /v1/product/{product}/status
Provides the current status of the given product
Path Parameters
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
product | String | yes | 2.0 | The product's key |
Response Body
| Name | Type | Required | Since | Description |
|---|---|---|---|---|
product | String | yes | 2.0 | The product's key |
enabled | Boolean | yes | 2.0 | True if the product is enabled, false otherwise |
healthy | Boolean | yes | 2.0 | True if the product systems are healthy, false otherwise |
GET /v1/client/configuration
Retrieves client configuration details. This endpoint is not encrypted.
Request
No path or query parameters are expected.
Response
The response body will contain a JSON object with the following properties
| Field | Type | Required | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
maximumMessageLength | Integer | yes | 2.0 | A positive integer indicating the maximum number of characters in a guest-supplied message. |
publicKey | String | yes | 2.0 | The server's public key. Used to securely exchange data with the server (eg: randomly generated symmetric encryption key to encrypt traffic). Deprecated. Use publicKeyEncryption.publicKey instead. |
pollFrequency | Integer | yes | 2.0 | The frequency the client can poll /v1/listen, in milliseconds. |
publicKeyEncryption.algorithm | String | yes | 2.0 | The encryption algorithm to employ |
publicKeyEncryption.publicKey | String | yes | 2.0 | The server's public key. Used to securely exchange data with the server (eg: randomly generated symmetric encryption key to encrypt traffic). |
publicKeyEncryption.version | String | yes | 2.0 | The version identifier of the encryption configuration in use. |
POST /v1/start
Initializes a session with the chatbot.
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
encryptionKey | String | Yes | 2.0 | A randomly generated encryption key (AES-256) that is encrypted with the public key from GET /v1/client/configuration and then Base64 encoded. |
visitorId | String | No | 2.0 | A unique ID for tracking the visitor over multiple chat sessions. Usually generated by CTO on the client side. |
siteCode | String | Yes | 2.0 | The site that is invoking the chatbot. |
pageName | String | Yes | 2.0 | The name of the page that is invoking the chatbot. |
Response Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
chatId | String | yes | 2.0 | The unique identifier of the chat. |
POST /v1/hello
Initializes a session with the chatbot, triggering a welcome message from the chatbot.
This is the same as calling /v1/start and then /v1/trigger with the WELCOME trigger value.
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
encryptionKey | String | Yes | 2.0 | A randomly generated encryption key (AES-256) that is encrypted with the public key from GET /v1/client/configuration and then Base64 encoded. |
visitorId | String | No | 2.0 | A unique ID for tracking the visitor over multiple chat sessions. Usually generated by CTO on the client side. |
siteCode | String | Yes | 2.0 | The site that is invoking the chatbot. |
pageName | String | Yes | 2.0 | The name of the page that is invoking the chatbot. |
Response Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
chatId | String | yes | 2.0 | The unique identifier of the chat. |
PUT /v1/trigger
Triggers an action on the chatbot without sending a message. The trigger may or may not result in a new message being appended to the queue.
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
trigger | Enum(Trigger) | yes | 2.0 | The specific trigger to invoke. The constant is case-sensitive. |
parameters | Map | no | 2.0 | A free-form key/value mapping of parameters to send as part of the trigger. |
Response Body
The expected response is an HTTP 202 (Accepted)
| Field | Type | Required | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
PUT /v1/trigger/multiple
Triggers multiple actions on the chatbot without sending a message. The triggers may or may not result in new messages being appended to the queue. Available since 2.7.0.
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
triggers | Object[] | yes | 2.7.0 | The specific triggers to invoke. The constant is case-sensitive. |
triggers[i].trigger | Enum(Trigger) | yes | 2.7.0 | The name of the trigger to invoke. The constant is case-sensitive. |
triggers[i].parameters | Map | no | 2.7.0 | A free-form key/value mapping of parameters to send as part of the trigger. |
Response Body
The expected response is an HTTP 202 (Accepted)
| Field | Type | Required | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
PUT /v1/talk
Sends guest input to the chatbot. This endpoint is expected to return immediately with an HTTP 202 (Accepted) response as the chatbot system will process the input asynchronously. The client is expected to poll the GET /chatbot/v1/listen endpoint for the chatbot response.
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
text | String | yes | 2.0 | The text the guest is submitting to the chatbot |
Response Body
The expected response is an HTTP 202 (Accepted) as the input submitted by the
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
GET /v1/listen
Gets responses from the chatbot.
Request
No path or query parameters are expected.
Response Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
messages | Array(Message) | no | 2.0 | Text that can be used as clickable/tapable quick-replies |
PUT /v1/feedback/message/{id}
Provides feedback on Chatbot generated messages.
Path Parameters
| Parameter | Type | Required? | Since | Description |
|---|---|---|---|---|
id | String | yes | 2.0 | The ID of the message to provide feedback on. Corresponds to the Message.id field returned by GET /v1/listen endpoint. |
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
helpful | boolean | no | 2.0 | If true, flags the message as helpful. If false, flags the message as unhelpful, and if null, removes the helpful flag. |
Response Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
POST /v1/goodbye
Terminates the current session with the chatbot.
Request
No body, path, or query parameters are expected.
Response Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
error | Object(Error) | no | 2.0 | If set, indicates an error occurred. Implies a HTTP 4xx/5xx status. |
GET /v1/ping
A minimal endpoint to determine if the servlet is running and to get baseline latency. This endpoint returns an HTTP/204 (No Content) if the servlet is running. The response is undefined if there is an error, but it is presumable that a HTTP 4xx/5xx status will be returned, possibly containing a standard Error object. This endpoint is not encrypted.
Request
No path or query parameters are expected.
Response Body
No response body is returned.
POST /v1/logging/{level}
Logs a message at the given log level. The endpoint returns an HTTP/204 (No Content) if the log is accepted and written. The response is undefined if there is an error, but it is presumable that a HTTP 4xx/5xx status will be returned, possibly containing a standard Error object. This endpoint is not encrypted.
Path Parameters
| Parameter | Type | Required? | Since | Description |
|---|---|---|---|---|
level | String | yes | 2.3 | The level to log at. Must be one of ERROR, WARN, INFO, DEBUG, TRACE. |
Request Body
| Field | Type | Required? | Since | Description |
|---|---|---|---|---|
visitorId | String | yes | 2.3 | The cross-session visitor ID |
sessionId | String | no | 2.3 | The chat session id |
timestamp | String | yes | 2.3 | The ISO_8601 date/time timestamp of the log entry, formatted as YYYY-mm-ddTHH:MM:SS.SSSZ (eg: 2022-03-3T17:17:39.123Z) |
message | String | no | 2.3 | The optional message to log |
agent | String | yes | 2.3 | The browser's user agent string |
locale | String | yes | 2.3 | The locale the client is operating in, as a ISO 639 language code with an optional ISO 3166-1 alpha-2 country code (eg: en, en-CA, es-MX) |
version | String | yes | 2.3 | The client version |
event | String | no | 2.3 | The event to log |
latency | number | no | 2.3 | The number of milliseconds of latency of the event logged |
Response Body
No response body is returned.