创建会话

请求地址

权限

createConversation
确保调用该接口使用的访问令牌开通了 createConversation 权限，详细信息参考准备工作。

接口说明

创建一个会话。

Authorization

Bearer $Access_Token

用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。

Content-Type

application/json

解释请求正文的方式。

bot_id

String

可选

730454116184516*

会话对应的智能体 ID。
创建会话时指定智能体 ID，后续才能通过 查看会话列表 查看指定智能体 ID 对应的会话列表。
智能体 ID，获取方法如下：
进入智能体的 开发页面，开发页面 URL 中 bot 参数后的数字就是智能体 ID。例如https://www.coze.cn/space/341****/bot/73428668*****，智能体 ID 为73428668*****。

name

String

可选

推荐杭州美食

会话的名称。默认为空。为了方便区分不同会话，建议设置会话名称。最多支持 100 个字符。

messages

Array of EnterMessage

可选

[ { “role”: “user”, “content”:“[{“type”:“text”,“text”:“你好，这是我的图片”},{“type”:“image”,“file_id”:“145657573***”}]”, “content_type”:“object_string” }, { “role”: “assistant”, “content”: “你好我是一个bot”, “content_type”:“text” } ]

会话中的消息内容。详细说明可参考 EnterMessage object。

connector_id

String

可选

1024

该会话在哪个渠道创建。目前支持如下渠道：

• API：（默认）1024
• ChatSDK：999
• 自定义渠道：自定义渠道 ID。自定义渠道 ID 的获取方式如下：在扣子编程左下角单击头像，在账号设置 > 发布渠道 > 企业自定义渠道管理页面查看渠道 ID。

meta_data

JSON Map

可选

{ “uuid”: “newid1234” }

附加信息，通常用于封装一些业务相关的字段。查看会话信息时，扣子编程会透传此附加信息，查看消息列表时不会返回该附加信息。
自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。

role

String

必选

user

发送这条消息的实体。取值：

• user：代表该条消息内容是用户发送的。
• assistant：代表该条消息内容是 Bot 发送的。

type

String

可选

question

消息类型。默认为 question。

• question：用户输入内容。
• answer：Bot 返回给用户的消息内容，支持增量返回。如果工作流绑定了输出节点，可能会存在多 answer 场景，此时可以用流式返回的结束标志来判断所有 answer 完成。
• function_call：Bot 对话过程中调用函数（function call）的中间结果。
• tool_response：调用工具 （function call）后返回的结果。
• follow_up：如果在 Bot 上配置打开了用户问题建议开关，则会返回推荐问题相关的回复内容。不支持在请求中作为入参。
• verbose：多 answer 场景下，服务端会返回一个 verbose 包，对应的 content 为 JSON 格式，content.msg_type =generate_answer_finish 代表全部 answer 回复完成。不支持在请求中作为入参。

content

String

可选

[{“type”:“text”,“text”:“你好，这是我的图片”},{“type”:“image”,“file_id”:“145657573***”}]

消息的内容，支持纯文本、多模态（文本、图片、文件混合输入）、卡片等多种类型的内容。

• content_type 为 object_string 时，content 为 object_string object 数组序列化之后的 JSON String，详细说明可参考 object_string object。
• 当 content_type = text 时，content 为普通文本，例如 "content" :"Hello!"。

meta_data

JSON Map

可选

{ “uuid”: “newid1234” }

创建消息时的附加消息，获取消息时也会返回此附加消息。
自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。

content_type

String

可选

text

消息内容的类型，支持设置为：

• text：文本。
• object_string：多模态内容，即文本和文件的组合、文本和图片的组合。
• card：卡片。此枚举值仅在接口响应中出现，不支持作为入参。

data

Object of ConversationData

\

会话的基础信息，包含会话的唯一标识、名称、创建时间等详细信息。

detail

Object of ResponseDetail

{“logid”:“20241210152726467C48D89D6DB2****”}

包含请求的详细信息的对象，主要用于记录请求的日志 ID 以便于排查问题。

code

Long

0

调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。

msg

String

“”

状态信息。API 调用失败时可通过此字段查看详细错误信息。
状态码为 0 时，msg 默认为空。

id

String

737999610479815****

Conversation ID，即会话的唯一标识。

name

String

推荐杭州美食

会话的名称，用于标识和区分不同的会话。

meta_data

JSON Map

{ “uuid”: “newid1234” }

附加信息，通常用于封装一些业务相关的字段。查看会话信息时，扣子编程会透传此附加信息，查看消息列表时不会返回该附加信息。
自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。

creator_id

String

247877439325****

会话创建者的扣子 UID，用于标识创建该会话的用户。

created_at

Long

1718289297

会话创建的时间。格式为 10 位的 Unixtime 时间戳，单位为秒。

updated_at

Long

1718289297

会话的最后更新时间，格式为 10 位的 Unix 时间戳，单位为秒。

last_section_id

String

749566434761695***

会话中最新的一个上下文片段 ID。

connector_id

String

1024

该会话在哪个渠道创建。目前支持如下渠道：

• API：1024
• ChatSDK：999
• 自定义渠道：自定义渠道 ID。自定义渠道 ID 的获取方式如下：在扣子编程左下角单击头像，在账号设置 > 发布渠道 > 企业自定义渠道管理页面查看渠道 ID。

logid

String

20241210152726467C48D89D6DB2****

本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。