机器人

机器人是 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。

机器人 ​

机器人对象 ​

创建机器人 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询机器人列表 ​

查询参数 ​