機器人

機器人是 kind 為 bot 的 IM 使用者，加上一份 AI 對話的配置。說明見 AI 對話。也可以在控制檯的 AI 機器人頁管理。

要做什麼	介面
建一個機器人	建立機器人
列出或檢視機器人	查詢機器人列表、查詢機器人
改回撥地址、上下文條數、超時等配置	修改機器人
暫時不讓機器人回覆	停用與啟用
刪掉機器人	刪除機器人
改暱稱、頭像	修改使用者資料，與普通使用者相同

好友、黑名單和會話的介面對機器人照常可用。

機器人物件

json

{
  "username": "assistant",
  "nickname": "智能客服",
  "avatar_url": "",
  "status": "active",
  "user_status": "active",
  "endpoint_id": "1840200000000000007",
  "context_messages": 10,
  "idle_timeout_seconds": 60,
  "max_active_streams": 1000,
  "description": "官网客服",
  "version": 3,
  "created_at": "2026-11-02T08:00:00.000Z",
  "updated_at": "2026-11-02T09:30:00.000Z"
}

欄位	型別	說明
`username`	String	機器人的使用者名稱，規則與 IM 使用者相同，建立後不能修改
`nickname`、`avatar_url`	String	與機器人的 IM 使用者資料相同
`status`	String	`active` 啟用，`disabled` 停用
`user_status`	String	機器人的 IM 使用者的狀態：`active` 或 `disabled`（被封禁）
`endpoint_id`	String	接收 `ai.message_received` 的回撥地址 ID；為 `null` 時發給訂閱了這個事件的地址
`context_messages`	Number	回撥附帶的最近訊息條數，0～50，預設 10
`idle_timeout_seconds`	Number	回覆沒有新內容的超時，10～300 秒，預設 60；超過後以 `failed`（`timeout`）結束
`max_active_streams`	Number	同時生成的回覆數上限，1～10000，預設 1000
`description`	String	備註，最多 256 個字元
`version`	Number	修改配置時用於併發檢查
`created_at`、`updated_at`	String	時間

建立機器人

在同一個操作中建立機器人的 IM 使用者和配置，並把它的加好友方式設為 allow_any。

POST/{org_name}/{app_name}/ai/bots

請求體

欄位	型別	必填	說明
`username`	String	是	使用者名稱，不能與已有的 IM 使用者重複
`nickname`	String	否	暱稱
`avatar_url`	String	否	頭像地址
`endpoint_id`	String	否	回撥地址 ID，在控制檯“回撥”頁檢視
`context_messages`	Number	否	預設 10
`idle_timeout_seconds`	Number	否	預設 60
`max_active_streams`	Number	否	預設 1000
`description`	String	否	備註

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/ai/bots" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "assistant",
    "nickname": "智能客服",
    "context_messages": 10
  }'

響應

成功返回 201 Created，響應體為 { "bot": 机器人对象 }。

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	引數不合法，如使用者名稱格式不對、配置超出範圍
409	`already_exists`	使用者名稱已被 IM 使用者或機器人使用
409	`limit_exceeded`	應用的機器人數達到上限（`details.reason` 為 `app_bots`）

查詢機器人列表

GET/{org_name}/{app_name}/ai/bots

查詢引數

引數	型別	說明
`limit`	Number	每頁數量，1～100，預設 20
`cursor`	String	上一頁返回的 `next_cursor`，第一頁不傳

響應

成功返回 200 OK：{ "items": [机器人对象…], "next_cursor": "…" }，next_cursor 為 null 表示沒有下一頁。

查詢機器人

GET/{org_name}/{app_name}/ai/bots/{username}

成功返回 200 OK，響應體為 { "bot": 机器人对象 }；不存在返回 404 not_found。

修改機器人

修改 AI 對話的配置。暱稱和頭像用修改使用者資料的介面修改。

PATCH/{org_name}/{app_name}/ai/bots/{username}

請求體

欄位	型別	必填	說明
`version`	Number	是	讀到的 `version`；與當前不同時返回 `409 version_conflict`，重新讀取後再改
`endpoint_id`	String	否	傳 `null` 改為使用訂閱了事件的地址
`context_messages`、`idle_timeout_seconds`、`max_active_streams`、`description`	—	否	同建立

只修改請求中出現的欄位。成功返回 200 OK 和 { "bot": 机器人对象 }。

停用與啟用

POST/{org_name}/{app_name}/ai/bots/{username}/disable

POST/{org_name}/{app_name}/ai/bots/{username}/enable

停用後使用者仍能給機器人發訊息，但不再傳送 ai.message_received，開始回覆返回 403 permission_denied（details.reason 為 bot_disabled）。停用前正在生成的回覆不受影響。成功返回 200 OK 和 { "bot": 机器人对象 }，重複操作不報錯。

刪除機器人

刪除機器人和它的 IM 使用者，不能恢復。正在生成的回覆以 failed（bot_deleted）結束，已有的訊息保留。

DELETE/{org_name}/{app_name}/ai/bots/{username}

成功返回 204 No Content；不存在返回 404 not_found。

機器人 ​

機器人物件 ​

建立機器人 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢機器人列表 ​

查詢引數 ​