发起对话

首先需要通过“创建对话”API创建一个对话ID，然后通过“发送对话消息”API向该对话发送消息，以完成对话过程。通过该流程，开发者可以实现终端用户与Bot的聊天对话。支持开发者为一个用户创建一个或多个对话ID，每个对话ID 之间的聊天数据相互隔离。

创建对话

用于请求创建并获取一个对话ID，对话ID是用户与Bot进行聊天的基础载体。聊天记录、长期记忆和短期记忆等能力都是基于对话ID。

请求方式

POST

调用地址

https://api.gptbots.ai/v1/conversation

调用验证

详情参见【API概述】内的鉴权方式说明。

请求

请求示例

curl -X POST https://api.gptbots.ai/v1/conversation \
  -H 'Authorization: Bearer your_apikey' \
  -H 'Content-Type: application/json' \
  -d '{
        "user_id": "123456789"
}'

请求头

字段	类型	描述
Authorization	Bearer ${token}	使用Authorization: Bearer ${token}进行调用验证，请在API密钥页面获取密钥作为token。
Content-Type	application/json	数据类型，取值为application/json。

请求体

字段	类型	必填	描述
user_id	string	是	用户标识，开发者需为终端用户定义一个user_id，在Bot内唯一识别一个用户。

响应

响应示例

{
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2"
}

成功响应

字段	类型	描述
conversation_id	string	对话标识符。

失败响应

字段	类型	描述
code	int	错误码。
message	string	错误详情。

错误码

Code	Message
40000	参数错误
40127	开发者鉴权失败

发送对话消息

向指定的对话ID发送消息，并获取Bot响应信息。

请求方式

POST

调用地址

https://api.gptbots.ai/v1/conversation/message

调用验证

详情参见API概述的鉴权方式说明。

请求

请求示例

curl -X POST https://api.gptbots.ai/v1/conversation/message \
  -H 'Authorization: Bearer your_apikey' \
  -H 'Content-Type: application/json' \
  -d '{
        "user_id": "123456",
        "text": "你好！",
        "conversation_id": "xxxxxx",
        "response_mode": "streaming"
}'

请求头

字段	类型	描述
Authorization	Bearer ${token}	使用Authorization: Bearer ${token}进行调用验证，请在API密钥页面获取密钥作为token。
Content-Type	application/json	数据类型，取值为application/json。

请求体

字段	类型	必填	描述
user_id	string	是	用户标识，开发者需为终端用户定义一个 user_id，在 Bot 内唯一识别一个用户。
text	string	是	用户的提问内容，内容的长度不能超过 Bot 配置的输入框长度限制。
conversation_id	string	是	对话标识符，传入需要继续对话的 conversation_id。
response_mode	string	是	blocking：阻塞型，等待执行完毕后返回结果。(请求若流程较长可能会被中断)。 streaming：流式返回，基于 SSE（Server-Sent Events）实现流式返回。

响应

响应示例

 {
  "message_id": "059f87d9-15c0-473a-870c-fde95cdcc1e4",
  "message_type": "ANSWER",
  "text": "Hi, is there anything I can help you?",
  "correlate_dataset": [
    {
      "data_id": "64ba14b0e62000708d1ee6ae",
      "data_name": "文档名称"
    }
  ],
  "next_question": [
    "需要帮忙吗？",
    "有什么问题吗？",
    "还需要我做什么吗？"
  ],
  "flow_output": [
    {
      "content": "你好",
      "branch": "1",
      "from_component_name": "User Input"
    }
  ],
  "create_time": 1679587005,
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2"
}

成功响应（阻塞）

字段	类型	描述
message_id	string	消息的唯一标识。
message_type	string	消息类型，取值：ANSWER、QUESTION。
text	string	回复内容。
next_question	array	系统为用户提供的下一步问题建议。若未开启或无结果或报错，则返回空。
correlate_dataset	JSON Array	回复内容引用的知识文档。
- data_id	string	知识文档的ID。
- data_name	string	知识文档的名称。
flow_output	JSON Array	flow bot回复内容。
- content	string	flow bot组件回复内容。
- branch	string	flow bot分支。
- from_component_name	string	flow bot上游组件名称。
create_time	int	回复的这条消息产生的时间戳。
conversation_id	string	对话标识符。

成功响应（流式）

字段	类型	描述
code	int	消息的类型编码，1-知识来源、3-文本类型、7-下一步建议内容、10-flowbot输出、0-结束标识。
message	string	消息类型，取值：CorrelateDataset、Text、NextQuestion、FlowOutput、End。
data	object	回复内容。

流式数据分多次返回：

{"code":1,"message":"CorrelateDataset","data":[{"dataId":"64ba14b0e62000708d1ee6ae","dataName":"文档名称"}]}
{"code":3,"message":"Text","data":"我"}  
{"code":3,"message":"Text","data":"可以"}
{"code":3,"message":"Text","data":"帮"}  
{"code":3,"message":"Text","data":"助"}
{"code":3,"message":"Text","data":"你"}  
{"code":3,"message":"Text","data":"的"}
{"code":3,"message":"Text","data":"吗"}
{"code":3,"message":"Text","data":"?"}
{"code":7,"message":"NextQuestion","data":["需要帮忙吗?","有什么问题吗?","还需要我做什么吗?"]}
{"code":10,"message":"FlowOutput","data":[{"content":"你好","branch":null,"from_component_name": "User Input"}]}
{"code":0,"message":"End","data":null}

失败响应

字段	类型	描述
code	int	错误码。
message	string	错误详情。

错误码

Code	Message
40000	参数错误
40127	开发者鉴权失败
40356	会话不存在
50000	系统内部错误