人工服务
人工服务
当开发者选择Webhook 作为人工服务接入方式时，首先需要在自己的服务器环境构建一个 Webhook 服务，开发者需要按规范提供以下3个接口用于接收人工服务请求、接收用户消息和人工客服回复消息。GPTBots 同时提供了2个接口用于接收客服回复消息和对话关闭指令。
注意事项：
- 开发者应确保 Webhook 服务正常可用，否则会影响人工服务的正常使用。
- 若发起人工服务后显示“正忙”，代表开发者的 Webhook 服务异常。
- 若发起人工服务后显示“正在连接”，代表开发者的 Webhook 服务正常。
- 当成功发起人工服务请求后，
- 开发者需要及时调用回复用户消息接口(https://api.gptbots.ai/v1/human/message/receive)回复用户1条消息，方可成功建立对话连接。
- 开发者若未回复用户消息，超过所设置的等待超时时长（默认60S）后，人工对话会自动结束。
接收人工服务对话请求通知
当终端用户发起人工服务请求时，GPTBots将该请求透传给开发者的 Webhook 服务，开发者接口服务返回200则代表创建人工服务成功。
请求方式
POST
调用地址
https://your_domain/conversation/establish
请求示例
curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \
-H "Content-Type: application/json" \
-d '{
"body": [
{
"text": "human service",
"message_type": "QUESTION"
},
{
"text": "content",
"message_type": "ANSWER"
},
{
"text": "content",
"files": {
"content_type":"Image",
"url":"http://gptbots.ai/example.jpg"
},
"message_type": "QUESTION"
}
],
"timestamp": 1742265090895,
"email": "bob@gmail.com",
"conversation_id": "67d8db020fa31d1ef64f53dg",
"bot_id": "665d88b03ce2b13cf2d573454",
"user_info": {
"phone": null,
"email": "bob@gmail.com",
"user_id": "KDslas",
"anonymous_id": "652face5184b30540a6ea7fe"
}
}'
curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \
-H "Content-Type: application/json" \
-d '{
"body": [
{
"text": "human service",
"message_type": "QUESTION"
},
{
"text": "content",
"message_type": "ANSWER"
},
{
"text": "content",
"files": {
"content_type":"Image",
"url":"http://gptbots.ai/example.jpg"
},
"message_type": "QUESTION"
}
],
"timestamp": 1742265090895,
"email": "bob@gmail.com",
"conversation_id": "67d8db020fa31d1ef64f53dg",
"bot_id": "665d88b03ce2b13cf2d573454",
"user_info": {
"phone": null,
"email": "bob@gmail.com",
"user_id": "KDslas",
"anonymous_id": "652face5184b30540a6ea7fe"
}
}'
此代码块在浮窗中显示
注意：该请求体中的
conversation_id仅用于标识人工服务对话场景的惟一ID，区别于 创建对话ID 为Agent对话场景所生成的惟一ID。
请求头
| 字段 | 类型 | 描述 |
|---|---|---|
| Content-Type | application/json | 数据类型，取值为 application/json。 |
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| conversation_id | string | 人工客服场景的会话id（区别与Agent对话场景的会话id），在客服回复接口需要透传给GPTBots |
| timestamp | long | 时间戳 |
| string | 用户邮箱，部分人工服务系统必须提供邮箱方可正常提供服务 | |
| bot_id | string | Agent（原 bot）的id |
| body | list<Object> | 消息体 |
| message_type | string | 消息类型，QUESTION/ANSWER |
| text | string | 客户发起人工客服的问题以及上下文 |
| files | list<Object> | 文件信息 |
| content_type | string | 文件类型 |
| url | string | 文件url |
| user_info | object | 用户信息 |
| user_info.phone | string | 用户的手机号码，目前只在whatsapp转人工客服的时候有值 |
| user_info.email | string | 用户的邮箱，在用户输入邮箱时有值 |
| user_info.user_id | string | 用户ID。企业开发者自定义的用户身份唯一标识ID，由开发者自行为某个匿名 ID设置 UserId |
| user_info.anonymous_id | string | 匿名 ID。用户在非 API 的渠道平台与 Agent 发起对话时，系统会根据用户所在的渠道平台，为用户生成包含所在渠道平台信息的匿名 ID |
- 通过 iframe/Share/Bubble Widget 方式发起人工服务时，用户必须填写用户邮箱.也同时允许开发者自定义用户邮箱从而避免用户填写邮箱。
- 通过 WhatsApp/Telegram/livechat 等三方平台请求人工服务时，默认使用 support@gptbots.ai作为用户邮箱，其中livechat支持开发者自定义用户邮箱。
- 通过 API 请求人工服务时，允许 email 字段为空，为空时默认使用 support@gptbots.ai 作为用户邮箱。
响应
| 参数 | 类型 | 说明 |
|---|---|---|
| code | int | 响应码 |
| message | string | 详情 |
聊天接口
通过创建的conversation_id，将用户的消息发送给人工客服。
请求方式
POST
调用地址
请求示例
{
"conversation_id": "conv_xxx",
"message_id": "msg_abc124",
"create_time": 1750000005000,
"agent_id": "bot_xxx",
"body": "这是我的订单截图",
"timestamp": 1750000005200,
"files": [
{
"content_type": "Image",
"url": "https://files.gptbots.ai/xxx/order.png",
"name": "order.png",
"format": "png"
}
]
}
{
"conversation_id": "conv_xxx",
"message_id": "msg_abc124",
"create_time": 1750000005000,
"agent_id": "bot_xxx",
"body": "这是我的订单截图",
"timestamp": 1750000005200,
"files": [
{
"content_type": "Image",
"url": "https://files.gptbots.ai/xxx/order.png",
"name": "order.png",
"format": "png"
}
]
}
此代码块在浮窗中显示
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| conversation_id | string | 对话ID，在客服回复接口需要透传给 GPTBots |
| timestamp | long | 时间戳 |
| body | string | 用户的消息文本内容 |
| message_id | string | 用户该条消息的 ID |
| create_time | long | 用户该条消息的创建时间（毫秒） |
| agent_id | string | 智能体（Agent/Bot）ID |
| files | array | 用户随消息上传的附件列表；无附件时不传或为空 |
| content_type | string | 内容类型枚举：Image / Audio / Video / Document / File / Text 等 |
| url | string | 附件可下载地址（GPTBots 侧可访问，开发者需自行下载/转存） |
| name | string | 文件名（含扩展名），与「获取对话明细」API 一致 |
| format | string | 文件格式/扩展名，与「获取对话明细」API 一致 |
响应
| 参数 | 类型 | 说明 |
|---|---|---|
| code | int | 响应码 |
| message | string | 详情 |
关闭会话接口
用户对话超时或者 Agent 用户主动关闭对话时，调用此接口关闭会话
请求方式
POST
调用地址
https://your_domain/conversation/close
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| conversation_id | string | 对话ID，在客服回复接口需要透传给 GPTBots |
| timestamp | long | 时间戳 |
| type | string | 关闭的类型、TIMEOUT（超时关闭）/ USER_CLOSED(用户主动关闭) |
响应
| 参数 | 类型 | 说明 |
|---|---|---|
| code | int | 响应码， |
| message | string | 详情 |
回复用户消息
开发者选择webhook作为人工服务接入方式时，GPTBots 提供用于回复用户消息的接口，可将人工客服所发送的消息内容发送给用户。
请求方式
POST
调用地址
https://api.gptbots.ai/v1/human/message/receive
请求示例
{
"conversation_id": "conv_xxx",
"timestamp": 1750000000000,
"body": "这是您要的发票",
"files": [
{ "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
{ "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
]
}
{
"conversation_id": "conv_xxx",
"timestamp": 1750000000000,
"body": "这是您要的发票",
"files": [
{ "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
{ "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
]
}
此代码块在浮窗中显示
请求参数
| 参数 | 类型 | 说明 | required |
|---|---|---|---|
| conversation_id | string | 对话ID，在对话创建接口和聊天接口有传，透传即可 | true |
| timestamp | long | 时间戳 | true |
| body | string | 用户的消息文本内容 | |
| files | array | 用户随消息上传的附件列表；无附件时不传或为空 | 新增 |
| content_type | string | 内容类型枚举：Image / Audio / Video / Document / File / Text 等 |
|
| url | string | 附件可下载地址（GPTBots 侧可访问，开发者需自行下载/转存） | |
| name | string | 文件名（含扩展名），与「获取对话明细」API 一致 | |
| format | string | 文件格式/扩展名，与「获取对话明细」API 一致 |
响应
| 参数 | 类型 | 说明 |
|---|---|---|
| code | int | 响应码， |
| message | string | 详情 |
人工客服关闭会话
开发者选择webhook作为人工服务接入方式时，GPTBots 提供的人工客服在需要时可以选择主动关闭对话的接口，关闭后用户将不能再接收到客服的消息，除非用户重新发起人工客服对话。
请求方式
POST
调用地址
https://api.gptbots.ai/v1/human/close
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| conversation_id | string | 对话 ID，在客服回复接口需要透传给 GPTBots |
| timestamp | long | 时间戳 |
响应
| 参数 | 类型 | 说明 | required |
|---|---|---|---|
| conversation_id | string | 对话ID，在会话创建接口和聊天接口有传，透传即可 | true |
| timestamp | long | 时间戳 | true |