The chat API endpoints provide access to the chat objects. A chat object is created for every chat that that is made to and from Contact Center AI Platform (CCAI Platform).
The following are the chat API endpoints:
Chat object
A chat object is created for every mobile and web chat session on CCAI Platform. The following is the chat object:
{
"id": "integer",
"status": "string",
"status_text": "string",
"features": [
"string",
"string"
],
"created_at": "string",
"ends_at": "string",
"timeout_at": "string",
"agent": {
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
"virtual_agent": {
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
"all_agents": [
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
}
],
"all_virtual_agents": [
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
}
],
"lang": "string",
"menus": [
{
"id": "integer",
"name": "string"
},
{
"id": "integer",
"name": "string"
}
],
"end_user": {
"id": "integer",
"identifier": "string"
}
}
Update a chat
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| id | TRUE | Integer | The chat ID to update |
Endpoint:
Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Body:
{
"finished_by_user_id": "integer",
"chat": {
"deflection_channel": "string",
"status": "string",
"escalation_id": "integer"
}
}
Example request and responses
The following sections provide example requests to the endpoint.
Update a chat
This example demonstrates the successful update of an existing chat
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| id | Integer | (Required) |
Body:
{
"finished_by_user_id": "integer",
"chat": {
"deflection_channel": "string",
"status": "finished",
"escalation_id": "integer"
}
}
Response
{
"id": "integer",
"status": "string",
"status_text": "string",
"features": [
"string",
"string"
],
"created_at": "string",
"ends_at": "string",
"timeout_at": "string",
"agent": {
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
"virtual_agent": {
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
"all_agents": [
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
}
],
"all_virtual_agents": [
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
}
],
"lang": "string",
"menus": [
{
"id": "integer",
"name": "string"
},
{
"id": "integer",
"name": "string"
}
],
"end_user": {
"id": "integer",
"identifier": "string"
}
}
Status Code: 200
Resume a dismissed chat
If a chat has been dismissed for inactivity, an end user may resume the same
chat. Chat status must be dismissed or va_dismissed.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| id | TRUE | Integer | The chat ID to resume |
Endpoint:
Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/resume
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Example request and responses
The following sections provide example requests to the endpoint.
Successful chat resume
This example demonstrates a successful request to resume an existing chat.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| id | Integer | (Required) |
Response
{
"id": "integer",
"status": "string",
"status_text": "string",
"features": [
"string",
"string"
],
"created_at": "string",
"ends_at": "string",
"timeout_at": "string",
"agent": {
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
"virtual_agent": {
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
"all_agents": [
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
}
],
"all_virtual_agents": [
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
}
],
"lang": "string",
"menus": [
{
"id": "integer",
"name": "string"
},
{
"id": "integer",
"name": "string"
}
],
"end_user": {
"id": "integer",
"identifier": "string"
}
}
Status Code: 200
Send a message in a chat
This method provides the ability to send a message in an existing chat session.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| id | TRUE | Integer | The chat ID that the message should sent in. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/message
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"from_user_id": integer,
"message": {
"type": "string",
"content": : "string"
}
}
}
Example request and responses
The following sections provide example requests to the endpoint.
Successful message send
This example demonstrates a successful submission of a message to an existing chat session.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| id | Integer | (Required) |
Body:
{
"from_user_id": integer,
"message": {
"type": "string",
"content": : "string"
}
}
}
Response
{
}
Status Code: 200
Escalate virtual agent chat
Escalate a chat from a virtual agent to a human agent.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID to escalate. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/escalations
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Body:
{
"reason": "string",
"force_escalate": "boolean"
}
Example request and responses
The following sections provide example requests to the endpoint.
Successful chat escalation
This example demonstrates the request to escalate an existing chat to human agent.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Body:
{
"reason": "string",
"force_escalate": "boolean"
}
Response
{
"id": "integer",
"chat_id": "integer",
"status": "string"
}
Status Code: 200
Update escalation
Used only for selecting the deflection channel.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID to update the deflection menu ID. |
| id | TRUE | Integer | The required menu ID. |
Endpoint:
Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/escalations/:id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"deflection_channel": "string"
}
Example request and responses
The following sections provide example requests to the endpoint.
Successful escalation update
This example demonstrates a successful update of the escalation channel.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
| id | Integer | (Required) |
Body:
{
"deflection_channel": "string"
}
Response
{
"id": "integer",
"chat_id": "integer",
"status": "string"
}
Status Code: 200
Add uploaded photo to the chat
Add a photo that has been uploaded to media storage to a chat
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID to add the photo to. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/photos
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Body:
{
"photo": [
{
"s3_path": "string",
"photo_type": "string"
},
{
"s3_path": "string",
"photo_type": "string"
}
]
}
Example request and responses
The following sections provide example requests to the endpoint.
Successful addition of a photo to chat
The following example demonstrates the addition of a photo that has been uploaded to a media storage to an existing chat conversation.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Body:
{
"photo": [
{
"s3_path": "string",
"photo_type": "string"
},
{
"s3_path": "string",
"photo_type": "string"
}
]
}
Response
{
"url": "string",
"media_id": "integer"
}
Status Code: 200
Get all photos from the chat
Gets media ID and storage URL for all photos attached to the chat.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID to get the media information. |
Endpoint:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/photos
Headers:
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Example request and responses
The following sections provide example requests to the endpoint.
Successful retrieval of chat photo information for a chat
This example demonstrates a successful call to the API to get the photo information for an existing chat session.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Response
[
{
"url": "string",
"media_id": "integer"
},
{
"url": "string",
"media_id": "integer"
}
]
Status Code: 200
Get pre-signed photo upload URL
Used for getting a pre signed upload URL for photos.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID that will be associated with the pre signed photo URL. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/photos/upload
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Example request and responses
The following sections provide example requests to the endpoint.
Successful retrieval of signed URL for upload
The following is an example of a successful request with retrieval of a signed URL for photo upload.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Response
{
"url": "string",
"fields": {
"key": "string",
"success_action_status": "string",
"Content-Type": "string",
"Cache-Control": "string",
"acl": "string",
"policy": "string",
"x-amz-credential": "string",
"x-amz-algorithm": "string",
"x-amz-date": "string",
"x-amz-security-token": "string",
"x-amz-signature": "string",
"x-goog-algorithm": "string",
"x-goog-credential": "string",
"x-goog-date": "string",
"x-goog-signature": "string"
}
}
Status Code: 200
Add uploaded video to the chat
Add a video that has been uploaded to media storage to a chat.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID that video should be associated with. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/videos
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Body:
{
"video": {
"s3_path": "string",
"gcs_path": "string"
}
}
Example request and responses
The following sections provide example requests to the endpoint.
Successful upload of a video to a chat session
This example demonstrates the successful upload of a video to a chat session.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Body:
{
"photo": [
{
"s3_path": "string",
"photo_type": "string"
},
{
"s3_path": "string",
"photo_type": "string"
}
]
}
Response
Body
{
"url": "string",
"media_id": "integer"
}
Status Code: 200
Get all videos from the chat
Retrieves media ID and storage URL for all videos attached to the chat.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID for which the video URLs will be retrieved. |
Endpoint:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/videos
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Example request and responses
The following sections provide example requests to the endpoint.
Retrieve all video URL for a chat
This example demonstrates the retrieval of all video URL for an existing chat.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Response
[
{
"url": "string",
"media_id": "integer"
},
{
"url": "string",
"media_id": "integer"
}
]
Status Code: 200
Get pre signed video upload URL
Used for getting a pre signed upload URL for videos.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| chat_id | TRUE | Integer | The required chat ID that will be associated with the pre signed video URL. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/videos/upload
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Example request and responses
The following sections provide example requests to the endpoint.
Successful retrieval of signed URL for video upload
The following is an example of a successful request with retrieval of a signed URL for video upload.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Response
{
"url": "string",
"fields": {
"key": "string",
"success_action_status": "string",
"Content-Type": "string",
"Cache-Control": "string",
"acl": "string",
"policy": "string",
"x-amz-credential": "string",
"x-amz-algorithm": "string",
"x-amz-date": "string",
"x-amz-security-token": "string",
"x-amz-signature": "string",
"x-goog-algorithm": "string",
"x-goog-credential": "string",
"x-goog-date": "string",
"x-goog-signature": "string"
}
}
Status Code: 200
Create chat
Start a new chat session.
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Body:
{
"chat": {
"menu_id": "integer",
"end_user_id": "integer",
"lang": "string",
"email": "string",
"context": "object",
"transcript": "object"
}
}
Example request and responses
The following sections provide example requests to the endpoint.
Create a new chat
The following example successfully creates a new chat.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-type | application/json | |
| Accept | application/json |
Body:
{
"id": "integer",
"status": "string",
"status_text": "string",
"features": [
"string",
"string"
],
"created_at": "string",
"ends_at": "string",
"timeout_at": "string",
"agent": {
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
"virtual_agent": {
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
"all_agents": [
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
}
],
"all_virtual_agents": [
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
}
],
"lang": "string",
"menus": [
{
"id": "integer",
"name": "string"
},
{
"id": "integer",
"name": "string"
}
],
"end_user": {
"id": "integer",
"identifier": "string"
}
}
Response
{
"url": "string",
"fields": {
"key": "string",
"success_action_status": "string",
"Content-Type": "string",
"Cache-Control": "string",
"acl": "string",
"policy": "string",
"x-amz-credential": "string",
"x-amz-algorithm": "string",
"x-amz-date": "string",
"x-amz-security-token": "string",
"x-amz-signature": "string",
"x-goog-algorithm": "string",
"x-goog-credential": "string",
"x-goog-date": "string",
"x-goog-signature": "string"
}
}
Status Code: 200
Returns a chat by ID
This method returns the chat object for a given chat ID.
Endpoint:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Example request and responses
The following sections provide example requests to the endpoint.
Retrieve a chat successfully
The following example demonstrates the successful request for an existing chat ID.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-type | application/json | |
| Accept | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| chat_id | Integer | (Required) |
Response
{
"id": "integer",
"status": "string",
"status_text": "string",
"features": [
"string",
"string"
],
"created_at": "string",
"ends_at": "string",
"timeout_at": "string",
"agent": {
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
"virtual_agent": {
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
"all_agents": [
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"first_name": "string",
"avatar_url": "string",
"status": "string"
}
],
"all_virtual_agents": [
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
},
{
"id": "integer",
"name": "string",
"avatar_url": "string",
"status": "string"
}
],
"lang": "string",
"menus": [
{
"id": "integer",
"name": "string"
},
{
"id": "integer",
"name": "string"
}
],
"end_user": {
"id": "integer",
"identifier": "string"
}
}
Status Code: 200
Get reserved data attributes during a chat
Endpoint
Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag
Example request and responses
This section contains an example request and response for the endpoint.
Success
This example shows a successful call.
Request
Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
URL variables
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
Response
{
"verified_customer": "boolean",
"bad_actor": "boolean",
"repeat_customer": "boolean"
}
Status code 0
Update reserved data attributes during a chat
Endpoint
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag
URL variables
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
Body
{
"verified_customer": "boolean",
"bad_actor": "boolean",
"repeat_customers": "boolean"
}