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）；批次新增時機器人進入失敗列表。機器人只在單聊中回覆。
• 停用後，使用者仍能給它發訊息，但平臺不再回撥你的服務，也不能開始新的回覆；停用前正在生成的回覆不受影響。

一次對話的流程

1. 使用者在客戶端給機器人發一條單聊訊息。
2. 平臺向你的回撥地址傳送 ai.message_received，帶上這條訊息和之前最近的幾條訊息（預設 10 條，機器人配置 0～50 條）。機器人配置了回撥地址的，只發給這個地址。
3. 你的服務端開始一條回覆：平臺以機器人的身份給使用者寫入一條 type 為 ai、狀態為“生成中”的訊息，使用者的客戶端立即顯示。
4. 你的服務端呼叫模型，把模型返回的內容寫入：正文、思考過程、圖片、檔案和工具呼叫的進度。平臺每 50 毫秒或滿 2 KB 合併一次，推送給使用者的全部線上裝置。
5. 模型結束後結束回覆。平臺儲存最終內容、更新訊息，對不在前臺的使用者發離線推送，併傳送 ai.stream_finished。

使用者點“停止生成”時，回覆立即以 stopped 結束，平臺傳送 ai.stream_stopped，你之後的寫入返回 409 stream_closed。服務端 SDK 收到這個回撥或這個錯誤時會自動停止讀取模型的流。

AI 訊息

AI 回覆儲存為一條普通的單聊訊息，傳送者是機器人，type 為 ai。使用者換裝置、清快取後都能在歷史訊息中看到，會話列表、未讀數和搜尋與普通訊息相同。body 為：

{
  "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 的不推送。