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