人工服务
人工服务
当开发者选择Webhook 作为人工服务接入方式时，首先需要在自己的服务器环境构建一个 Webhook 服务，开发者需要按规范提供以下3个接口用于接收人工服务请求、接收用户消息和人工客服回复消息。GPTBots 同时提供了2个接口用于接收客服回复消息和对话关闭指令。
创建对话ID
用于创建一个conversation_id，以传递用户请求人工服务的消息。
请求方式
POST
调用地址
https://your_domain/conversation/establish
请求示例
curl -v -X POST https://YOUR_DOMAIN/human/service/conversation/establish
--header "Content-Type: application/json"
--data '{
"body":[{"text":"human service","message_type":"QUESTION"},{"text":"","message_type":"ANSWER"}],"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 -v -X POST https://YOUR_DOMAIN/human/service/conversation/establish
--header "Content-Type: application/json"
--data '{
"body":[{"text":"human service","message_type":"QUESTION"},{"text":"","message_type":"ANSWER"}],"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 | string | 会话id，在客服回复接口需要透传给 GPTBots |
| timestamp | long | 时间戳 |
| string | 用户邮箱，部分人工服务系统必须提供邮箱方可正常提供服务 | |
| bot_id | string | Agent（原 bot）的id |
| body | list<Object> | 消息体 |
| body.message_type | string | 消息类型，QUESTION/ANSWER |
| body.text | string | 客户发起人工客服的问题以及上下文 |
| 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 | string | 对话ID，在客服回复接口需要透传给 GPTBots |
| timestamp | long | 时间戳 |
| body | string | 用户的消息 |
响应
| 参数 | 类型 | 说明 |
|---|---|---|
| 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 提供用于接收 Webhook端人工客服回复消息的接口，并将消息内容发送给用户。
请求方式
POST
调用地址
https://api.gptbots.ai/v1/human/message/receive
请求参数
| 参数 | 类型 | 说明 | required |
|---|---|---|---|
| conversation_id | string | 对话ID，在对话创建接口和聊天接口有传，透传即可 | true |
| timestamp | long | 时间戳 | true |
| body | string | 人工客服的回复内容 | true |
响应
| 参数 | 类型 | 说明 |
|---|---|---|
| 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 |