AI 对话

AI 对话让你把自己的大模型接入 IM：用户和机器人单聊，你的服务端收到用户的消息后调用模型，把模型的回复边生成边写入，用户在客户端看到逐字出现的回复。平台负责把内容实时推给用户、断线续传、保存最终消息和离线推送；平台不调用模型，也不保存你的模型密钥。

要做什么	看哪里
建一个机器人	创建机器人，或控制台的 AI 机器人
收到用户发给机器人的消息	订阅回调事件 `ai.message_received`
把模型的回复边生成边发给用户	流式回复；用服务端 SDK 时见各语言“调用接口”中的“AI 流式回复”
在客户端显示 AI 回复	Web SDK：AI 回复
了解回复的格式、结束原因和上限	本页的 AI 消息、上限

一般不需要直接调用这些接口：服务端 SDK 的 StartStream 和 Pipe* 已经处理了合批、重试和对接 OpenAI、Anthropic、Gemini 的流。

AI 对话需要平台开启；没有开启时，本节的接口返回 404 not_found。

机器人

机器人是应用中的一种 IM 用户（用户对象的 kind 为 bot），通过创建机器人生成，不能用普通的创建用户接口创建。

和普通用户一样有用户名、昵称、头像，可以被加为好友、被拉黑，会出现在用户的会话列表中。创建时加好友方式设为“允许任何人添加”，用户可以直接加它为好友。
不能登录：签发登录凭证、修改密码等返回 403 permission_denied（details.reason 为 bot_account）。
不能入群：建群、邀请、申请入群、添加群成员时机器人一律被拒绝，返回 403 permission_denied（bot_account）；批量添加时机器人进入失败列表。机器人只在单聊中回复。
停用后，用户仍能给它发消息，但平台不再回调你的服务，也不能开始新的回复；停用前正在生成的回复不受影响。

一次对话的流程

用户在客户端给机器人发一条单聊消息。
平台向你的回调地址发送 ai.message_received，带上这条消息和之前最近的几条消息（默认 10 条，机器人配置 0～50 条）。机器人配置了回调地址的，只发给这个地址。
你的服务端开始一条回复：平台以机器人的身份给用户写入一条 type 为 ai、状态为“生成中”的消息，用户的客户端立即显示。
你的服务端调用模型，把模型返回的内容写入：正文、思考过程、图片、文件和工具调用的进度。平台每 50 毫秒或满 2 KB 合并一次，推送给用户的全部在线设备。
模型结束后结束回复。平台保存最终内容、更新消息，对不在前台的用户发离线推送，并发送 ai.stream_finished。

用户点“停止生成”时，回复立即以 stopped 结束，平台发送 ai.stream_stopped，你之后的写入返回 409 stream_closed。服务端 SDK 收到这个回调或这个错误时会自动停止读取模型的流。

AI 消息

AI 回复保存为一条普通的单聊消息，发送者是机器人，type 为 ai。用户换设备、清缓存后都能在历史消息中看到，会话列表、未读数和搜索与普通消息相同。body 为：

json

{
  "stream_id": "1841000000000000123",
  "status": "completed",
  "parts": [
    { "type": "reasoning", "text": "用户想知道明天的天气……" },
    { "type": "tool", "id": "call_1", "name": "weather", "title": "查询天气", "state": "done" },
    { "type": "text", "text": "明天上海**多云**，最高 23℃。" },
    { "type": "image", "url": "https://cdn.example.com/a.png", "width": 800, "height": 600, "alt": "天气图" }
  ],
  "text": "明天上海多云，最高 23℃。",
  "finish_reason": "stop",
  "error": null,
  "model": "gpt-4.1",
  "usage": { "input_tokens": 120, "output_tokens": 380 },
  "content_url": null,
  "last_seq": 57
}

字段	类型	说明
`stream_id`	String	这条回复的流 ID
`status`	String	`streaming` 生成中，`completed` 已完成，`stopped` 已停止，`failed` 生成中断。生成中 `parts` 为空数组，内容只在实时推送中
`parts`	Array	回复的片段，结束后保存
`text`	String	全部正文片段去掉 Markdown 标记后拼接，最多 2000 个字符，用于会话列表预览、离线推送、搜索，以及不认识 `ai` 类型的旧版客户端
`finish_reason`	String	结束原因
`error`	Object	生成中断时为 `{ "code": "…", "message": "…" }`，`message` 显示给用户；其他情况为 `null`
`model`、`usage`	—	结束时你给出的模型名和用量（`input_tokens`、`output_tokens`），只用于展示和统计
`content_url`	String	预留字段，目前总为 `null`
`last_seq`	Number	最后一段增量的序号

AI 消息不能通过发送消息接口发送（返回 400 invalid_argument），也不能编辑。撤回、删除与普通消息相同。

片段

`type`	字段	说明
`text`	`text`	正文，Markdown
`reasoning`	`text`	思考过程，客户端默认折叠显示
`image`	`url`，可选 `width`、`height`、`alt`	`url` 为 https 地址，建议先用文件上传上传
`file`	`url`、`name`、`size`，可选 `mime_type`	同上
`tool`	`id`、`name`、`title`、`state`	工具调用的进度，`state` 为 `running`、`done` 或 `failed`；只用于展示，不含参数和结果

结束原因

`status`	`finish_reason`	说明
`completed`	你给出的值，如 `stop`、`length`、`tool_calls`，默认 `stop`	正常结束
`stopped`	`user`	用户点了停止生成
`stopped`	`replaced`	开始新回复时用 `replace` 结束了这条
`failed`	`developer`	你报告了失败，`error` 为你给出的代码和说明（服务端 SDK 连续写入失败时代码为 `transport`，模型报错时为 `model_error`）
`failed`	`timeout`	超过机器人设置的时间（默认 60 秒）没有新内容
`failed`	`max_duration`	超过 30 分钟
`failed`	`too_large`	内容超过上限，见上限
`failed`	`content_rejected`	内容安全审核没有通过
`failed`	`bot_deleted`、`user_deleted`	机器人或接收的用户被删除
`failed`	`buffer_lost`	平台的临时缓存丢失（极少发生）

结束时，completed 和 stopped 的文字内容会提交内容安全审核，不通过的改为 failed（content_rejected）。

上限

项目	上限
每个应用的机器人	100 个
每个机器人同时生成的回复	默认 1000 条，机器人配置，最多 10000 条；超过时开始回复返回 `409 limit_exceeded`
每个会话同时生成的回复	1 条；会话中已有时返回 `409 stream_in_progress`，或用 `replace` 先结束它
没有新内容的超时	默认 60 秒，机器人配置 10～300 秒
一条回复的时长	30 分钟
一条回复的内容	32 KB；超过时以 `failed`（`too_large`）结束。写入累计超过 1 MB 时写入直接返回 `413 payload_too_large`
一条回复的片段	200 个；同一片段的追加不增加片段数
一段增量	64 KB
写入速率	每个应用每秒 5000 段，超过返回 `429 rate_limited`
回调附带的最近消息	默认 10 条，机器人配置 0～50 条，总大小不超过 48 KB

AI 回复按普通消息计入消息存储，不另外按消息条数计费。

离线推送

开始回复时不推送。回复以 completed 或 stopped 结束时，按普通单聊消息的规则（前台判断、免打扰、额度）给不在前台的用户推送一次，内容为机器人昵称和回复的开头；failed 的不推送。

AI 对话 ​

机器人 ​

一次对话的流程 ​

AI 消息 ​

片段 ​

结束原因 ​

上限 ​

离线推送 ​

AI 对话

机器人

一次对话的流程

AI 消息

片段

结束原因

上限

离线推送