Chat 平台 API 端点

聊天平台 API 端点提供对聊天对象的访问权限。每次与 Contact Center AI 平台 (CCAI Platform) 进行聊天时，系统都会创建一个聊天对象。

以下是聊天平台 API 端点：

更新聊天内容
在聊天中发送消息
升级虚拟客服聊天
更新升级
将上传的照片添加到对话中
从对话中提取所有照片
获取预签名照片上传网址
将上传的视频添加到对话中
从聊天中提取所有视频
获取预签名的视频上传网址
创建对话
返回聊天 ID
在对话期间获取预留的数据属性
在聊天期间更新预留的数据属性
在聊天中发送自定义数据
在聊天会话期间更新最终用户

Chat 对象

在 CCAI 平台上，系统会为每个移动和 Web 聊天会话创建一个聊天对象。以下是聊天对象：

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

更新对话

参数	必需	数据类型	定义
id	TRUE	整数	要更新的聊天 ID

端点：

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id

标头：

键	值	说明
Content-Type	application/json
接受	application/json

正文：

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "string",
        "escalation_id": "integer"
    }
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

更新对话

此示例演示了如何成功更新现有聊天

请求

标头：

键	值	说明
Content-Type	application/json
接受	application/json

查询：

键	值	说明
id	整数	（必填）

正文：

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "finished",
        "escalation_id": "integer"
    }
}

响应

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

状态代码： 200

在聊天中发送消息

此方法可用于在现有聊天会话中发送消息。

参数	必需	数据类型	定义
id	TRUE	整数	应在其中发送消息的聊天 ID。

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/message

标头：

键	值	说明
Content-Type	application/json

正文：

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": "string"
            }
    }
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功发送消息

此示例演示了如何成功向现有聊天会话提交消息。

请求

标头：

键	值	说明
Content-Type	application/json
接受	application/json

查询：

键	值	说明
id	整数	（必填）

正文：

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": : "string"
            }
    }
}

响应

{
}

状态代码： 200

升级虚拟客服聊天

将聊天从虚拟客服升级到人工客服。

参数	必需	数据类型	定义
chat_id	TRUE	整数	升级所需的聊天 ID。

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/escalations

标头：

键	值	说明
Content-Type	application/json
接受	application/json

正文：

{
    "reason": "string",
    "force_escalate": "boolean"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功升级聊天

此示例演示了将现有对话升级到人工客服的请求。

请求

标头：

键	值	说明
Content-Type	application/json
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

正文：

{
    "reason": "by_end_user_ask",
    "force_escalate": true
}

响应

{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

状态代码： 200

更新升级

仅用于选择偏转通道。

参数	必需	数据类型	定义
chat_id	TRUE	整数	更新分流菜单 ID 所需的聊天 ID。
id	TRUE	整数	必需的菜单 ID。

端点：

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/escalations/:id

标头：

键	值	说明
Content-Type	application/json

正文：

{
    "deflection_channel": "string"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功更新升级

此示例演示了如何成功更新升级渠道。

请求

标头：

键	值	说明
Content-Type	application/json
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）
id	整数	（必填）

正文：

{
    "deflection_channel": "string"
}

响应

{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

状态代码： 200

将上传的照片添加到对话中

将已上传到媒体存储空间的照片添加到聊天会话

参数	必需	数据类型	定义
chat_id	TRUE	整数	用于添加照片的必需聊天 ID。

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/photos

标头：

键	值	说明
Content-Type	application/json
接受	application/json

正文：

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功将照片添加到对话

以下示例展示了如何将已上传到媒体存储空间的照片添加到现有聊天对话中。

请求

标头：

键	值	说明
Content-Type	application/json
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

正文：

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

响应

{
    "url": "string",
    "media_id": "integer"
}

状态代码： 200

提取对话中的所有照片

获取聊天中附加的所有照片的媒体 ID 和存储网址。

参数	必需	数据类型	定义
chat_id	TRUE	整数	获取媒体信息所需的聊天 ID。

端点：

Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/photos

标头：

键	值	说明
接受	application/json

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功检索到某个聊天的聊天照片信息

此示例演示了如何成功调用 API 来获取现有聊天会话的照片信息。

请求

标头：

键	值	说明
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

响应

[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

状态代码： 200

获取预签名照片上传网址

用于获取照片的预签名上传网址。

参数	必需	数据类型	定义
chat_id	TRUE	整数	将与预签名照片网址相关联的必需聊天 ID。

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/photos/upload

标头：

键	值	说明
Content-Type	application/json
接受	application/json

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功检索到用于上传的签名网址

以下示例展示了成功请求并检索到用于上传照片的签名网址。

请求

标头：

键	值	说明
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

响应

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

状态代码： 200

将上传的视频添加到对话中

将已上传到媒体存储空间的视频添加到对话中。

参数	必需	数据类型	定义
chat_id	TRUE	整数	视频应关联到的必需聊天 ID。

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/videos

标头：

键	值	说明
Content-Type	application/json
接受	application/json

正文：

{
    "video": {
        "s3_path": "string",
        "gcs_path": "string"
    }
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功将视频上传到聊天会话

此示例演示了如何成功将视频上传到聊天会话。

请求

标头：

键	值	说明
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

正文：

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

响应

Body
{
    "url": "string",
    "media_id": "integer"
}

状态代码： 200

从聊天中提取所有视频

获取附加到相应聊天会话的所有视频的媒体 ID 和存储网址。

参数	必需	数据类型	定义
chat_id	TRUE	整数	将检索视频网址的必需聊天 ID。

端点：

Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/videos

标头：

键	值	说明
Content-Type	application/json
接受	application/json

请求和响应示例

以下部分提供了向端点发送的请求示例。

检索相应对话的所有视频网址

此示例演示了如何检索现有聊天会话的所有视频网址。

请求

标头：

键	值	说明
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

响应

[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

状态代码： 200

获取预签名视频上传网址

用于获取视频的预签名上传网址。

参数	必需	数据类型	定义
chat_id	TRUE	整数	将与预签名视频网址关联的必需聊天 ID。

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:chat_id/videos/upload

标头：

键	值	说明
Content-Type	application/json
接受	application/json

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功检索到用于视频上传的签名网址

以下示例展示了成功请求并检索到用于视频上传的签名网址。

请求

标头：

键	值	说明
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

响应

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

状态代码： 200

创建聊天

开始新的聊天会话。

示例请求

方法：POST

网址：https://{subdomain}.{domain}/apps/api/v1/chats

标头

键	值	说明
Content-Type	application/json
接受	application/json

正文

{
    "chat": {
        "menu_id": "integer",
        "end_user_id": "integer",
        "lang": "string",
        "email": "string",
        "context": "object",
        "transcript": "object"
    },
    "end_user": {
        "phone": "string"
    }
}

背景信息：

context 对象包含 value 对象，后者会将元数据传递给聊天对话。您可以将 context 对象作为无符号数据形参传递给虚拟代理。请参阅以下示例：

{
    "context": {
        {"value":
            {"foo": "bar",
             "key": "value"}
        }
    }
}

在此示例中，传入字段的未签名数据形参值为 context，目标字段可设置为 context。这样一来，您就可以使用 $session.params.context.foo 或 $session.params.context.key 了。

示例响应

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

按 ID 返回聊天

此方法会返回指定聊天 ID 对应的聊天对象。

端点：

Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id

标头：

键	值	说明
Content-Type	application/json
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

请求和响应示例

以下部分提供了向端点发送的请求示例。

成功检索聊天记录

以下示例展示了针对现有聊天 ID 的成功请求。

请求

标头：

键	值	说明
Content-type	application/json
接受	application/json

查询：

键	值	说明
chat_id	整数	（必填）

响应

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

状态代码： 200

在聊天期间获取预留的数据属性

端点

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

请求和响应示例

本部分包含该端点的请求和响应示例。

成功

此示例展示了成功通话。

请求

标头

键	值	说明
接受	application/json

网址变量

键	值	说明
id	整数	（必填）

响应

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

状态代码 0

在聊天期间更新预留的数据属性

端点

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

网址变量

键	值	说明
id	整数	（必填）

Body

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

在聊天中发送自定义数据

在聊天中发送自定义数据。

示例请求

方法：POST

网址：https//{subdomain}.{domain}/apps/api/v1/chats/:id/custom_data

标头

键	值	说明
Content-Type	application/json

网址变量

键	值	说明
id		（必需）

示例响应

// Use unsecured parameter
{
"signed": false,
"data": {
// Start customer_flag fields
"reserved_verified_customer": {
"label": "LABEL 1",
"value": true
},
"reserved_bad_actor": {
"label": "LABEL 2",
"value": false
},
"reserved_repeat_customer": {
"label": "LABEL 3",
"value": true
},
// End customer_flag fields
"field1": {
"label": "LABEL 4",
"value": "dummy1"
},
"field2": {
"label": "LABEL 5",
"value": "dummy2"
}
}
}
// Use secured parameter
// {
// "signed": true,
// "signed_data": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21fZGF0YSI6eyJyZXNlcnZlZF92ZXJpZmllZF9jdXN0b21lciI6eyJ2YWx1ZSI6ZmFsc2V9LCJyZXNlcnZlZF9iYWRfYWN0b3IiOnsidmFsdWUiOnRydWV9LCJyZXNlcnZlZF9yZXBlYXRfY3VzdG9tZXIiOnsidmFsdWUiOmZhbHNlfSwiZmllbGQxIjp7InZhbHVlIjoiZHVtbXkxMTEifSwiZmllbGQyIjp7InZhbHVlIjoiZHVtbXkyMjIifX0sImV4cCI6MTcyOTY4MzU5MywiaWF0IjoxNzI5Njc5OTkzfQ.BMskgKTM3DbgrMLWjI46ZJ1K73H25JRd16SgHK0A1Ts"
// }
// ======================= How to create &lt;signed_data&gt; =======================
// payload = {
// "custom_data": {
// // Start customer_flag fields
// "reserved_verified_customer": {
// "label": "LABEL 1",
// "value": true
// },
// "reserved_bad_actor": {
// "label": "LABEL 2",
// "value": false
// },
// "reserved_repeat_customer": {
// "label": "LABEL 3",
// "value": true
// },
// // End customer_flag fields
// "field1": {
// "label": "LABEL 4",
// "value": "dummy1"
// },
// "field2": {
// "label": "LABEL 5",
// "value": "dummy2"
// }
// },
// "exp": 1734567890, // expiration timestamp
// "iat": 1734560000 // issue timestamp
// }
// signed_data = JWT.encode(payload, 'Company secret', 'HS256')
// ======================= End how to create &lt;signed_data&gt; =======================

在聊天会话进行期间更新最终用户

更新与当前活跃聊天会话关联的最终用户。此外，它还会更新与 CRM 支持请求相关联的联系信息。 _Identifier 是必需的，而 name、email 和 phone 是可选的。

示例请求

方法：POST

网址：https//{subdomain}.{domain}/apps/api/v1/chats/:chat_id/end-user

标头

键	值	说明
Content-Type	application/json

网址变量

键	值	说明
chat_id

正文

{
    "identifier": "string",
    "name": "string",
    "email": "string",
    "phone": "string"
}

示例响应

{
    "message": "accepted"
}

Chat 平台 API 端点 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Chat 对象

更新对话

请求和响应示例

更新对话

请求

响应

在聊天中发送消息

请求和响应示例

成功发送消息

请求

响应

升级虚拟客服聊天

请求和响应示例

成功升级聊天

请求

响应

更新升级

请求和响应示例

成功更新升级

请求

响应

将上传的照片添加到对话中

请求和响应示例

成功将照片添加到对话

请求

响应

提取对话中的所有照片

请求和响应示例

成功检索到某个聊天的聊天照片信息

请求

响应

获取预签名照片上传网址

请求和响应示例

成功检索到用于上传的签名网址

请求

响应

将上传的视频添加到对话中

请求和响应示例

成功将视频上传到聊天会话

请求

响应

从聊天中提取所有视频

请求和响应示例

检索相应对话的所有视频网址

请求

响应

获取预签名视频上传网址

请求和响应示例

成功检索到用于视频上传的签名网址

请求

响应

创建聊天

示例请求

标头

正文

示例响应

按 ID 返回聊天

请求和响应示例

成功检索聊天记录

请求

响应

在聊天期间获取预留的数据属性

请求和响应示例

成功

请求

响应

在聊天期间更新预留的数据属性

在聊天中发送自定义数据

示例请求

标头

网址变量

示例响应

在聊天会话进行期间更新最终用户

示例请求

标头

网址变量

正文

示例响应

Chat 平台 API 端点