Bots

A bot is an IM user whose kind is bot, plus an AI conversation configuration. See AI conversations. Bots can also be managed on the console's AI bots page.

You want to	API
Create a bot	Create a bot
List or view bots	List bots, Get a bot
Change the callback endpoint, context size, timeout and other settings	Update a bot
Stop a bot replying for now	Disable and enable
Remove a bot	Delete a bot
Change nickname or avatar	Update user profile, as for normal users

The friend, blacklist and conversation APIs work for bots as usual.

Bot object

{
  "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"
}

Field	Type	Description
username	String	The bot's username; same rules as IM users; cannot be changed after creation
nickname, avatar_url	String	Same as the bot's IM user profile
status	String	active enabled, disabled disabled
user_status	String	Status of the bot's IM user: active or disabled (banned)
endpoint_id	String	ID of the callback address that receives ai.message_received; when null, addresses subscribed to the event receive it
context_messages	Number	Number of recent messages included in the callback, 0–50, default 10
idle_timeout_seconds	Number	Timeout without new content, 10–300 seconds, default 60; the reply then ends as failed (timeout)
max_active_streams	Number	Maximum replies being generated at once, 1–10000, default 1000
description	String	Note, up to 256 characters
version	Number	Used for concurrency checks when updating
created_at, updated_at	String	Timestamps

Create a bot

Creates the bot's IM user and configuration in one operation, and sets its friend-add mode to allow_any.

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

Request body

Field	Type	Required	Description
username	String	Yes	Username; must not duplicate an existing IM user
nickname	String	No	Nickname
avatar_url	String	No	Avatar URL
endpoint_id	String	No	Callback address ID, shown on the console's "Callbacks" page
context_messages	Number	No	Default 10
idle_timeout_seconds	Number	No	Default 60
max_active_streams	Number	No	Default 1000
description	String	No	Note

Request example

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
  }'

Response

Returns 201 Created with { "bot": bot object }.

Errors

HTTP status	code	Description
400	invalid_argument	Invalid parameters, such as a malformed username or settings out of range
409	already_exists	The username is already used by an IM user or bot
409	limit_exceeded	The app has reached its bot limit (details.reason is app_bots)

List bots

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

Query parameters

Parameter	Type	Description
limit	Number	Page size, 1–100, default 20
cursor	String	next_cursor from the previous page; omit for the first page

Response

Returns 200 OK: { "items": [bot objects…], "next_cursor": "…" }; next_cursor is null when there are no more pages.

Get a bot

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

Returns 200 OK with { "bot": bot object }, or 404 not_found if it does not exist.

Update a bot

Updates the AI conversation configuration. Nickname and avatar are changed with the update-user-profile API.

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

Request body

Field	Type	Required	Description
version	Number	Yes	The version you read; if it differs from the current one, 409 version_conflict is returned; read again and retry
endpoint_id	String	No	null switches back to the addresses subscribed to the event
context_messages, idle_timeout_seconds, max_active_streams, description	—	No	Same as when creating

Only the fields present in the request are changed. Returns 200 OK with { "bot": bot object }.

Disable and enable

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

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

After disabling, users can still message the bot, but ai.message_received is no longer sent and starting a reply returns 403 permission_denied (details.reason is bot_disabled). Replies already being generated are not affected. Returns 200 OK with { "bot": bot object }; repeating the operation is not an error.

Delete a bot

Deletes the bot and its IM user; this cannot be undone. Replies being generated end as failed (bot_deleted); existing messages are kept.

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

Returns 204 No Content, or 404 not_found if it does not exist.