Chat endpoints

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:

• Update a chat

• Resume a dismissed chat

• Send a message in a chat

• Escalate virtual agent chat

• Update escalation

• Add uploaded photo to the chat

• Get all photos from the chat

• Set pre signed photo upload URL

• Add uploaded video to the chat

• Get all videos from the chat

• Get pre signed video upload URL

• Create chat

• Returns a chat ID

• Get reserved data attributes during a chat

• Update reserved data attributes during a chat

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"
}