Bot API

Buko Bot API lets an external agent operate a bot account inside Buko chats. The bot is only the messaging endpoint. Your agent service decides what to do with each message.

Status

Bot API is available for official and approved bots. Public self-service bot creation is not open yet.

Base URLs

Purpose	URL
REST API	`https://ims.buko.app`
Bot Gateway WebSocket	`wss://ims.buko.app/bot/ws`
Documentation	`https://im.buko.app/dev-docs/bot-api/`

All REST methods use HTTPS. All Bot Gateway connections use WSS.

Core concepts

Concept	Meaning
Bot account	A Buko identity with `kind = bot`, display name, handle, avatar, and owner.
Official bot	A Buko-operated bot with an explicit official marker in clients.
Managed agent	A Buko official bot whose token is encrypted in `secret_vault` for the official runner.
Bot token	Secret token used by your agent. It starts with `bot_`.
Chat	A Buko `space_id`. It can be a private bot DM or a group.
Update	An event delivered to a bot, such as `message`, `edited_message`, or `my_chat_member`.
Message ID	The message `seq` inside one chat, serialized as a string.

Identifier contract

Buko uses Telegram-like method names, but identifiers follow Buko's existing chat model.

API field	Buko meaning	Type
`chat_id`	`space_id`, opaque string	string
`message_id`	message `seq` inside the chat	string
`reply_to_message_id`	target message `seq` in the same chat	string
`update_id`	monotonically increasing update id scoped to one bot	string
`from.id`	per-bot scoped user id	string

message_id is not a small global integer. Treat it as an opaque string even when it looks numeric.

from.id is scoped to the current bot. It is stable for that bot, but it is not the user's raw internal account id.

Private chats and `/start`

Bots cannot send private messages to arbitrary users.

A private bot chat becomes available only after a user starts the bot from the Buko app. The current user-facing start flow creates or opens the private chat, records the start relationship, and sends a visible /start message into that chat. The /start message is delivered to the bot as a normal message update.

Groups

Bots can be added to groups. In groups, privacy mode is enabled by default: the bot receives only explicit invocations:

/command@bot_handle
messages mentioning @bot_handle
replies to one of the bot's messages

Bot-authored messages are not echoed back to the same bot.

Delivery modes

Buko does not support webhooks. Use one of these modes:

Bot Gateway WebSocket: realtime delivery, recommended for production agents.
Polling: simple fallback for environments where WebSocket is unavailable.

See Receiving Updates.

Quick start

export BUKO_BOT_TOKEN="bot_xxx"

curl -sS https://ims.buko.app/bot/getMe \
  -X POST \
  -H "Authorization: Bot $BUKO_BOT_TOKEN" \
  -H "Content-Type: application/json"

Send a message after a user has started your bot:

curl -sS https://ims.buko.app/bot/sendMessage \
  -X POST \
  -H "Authorization: Bot $BUKO_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "spc_abc123",
    "text": "Hello from Buko Bot API"
  }'

Response envelope

Successful responses use:

{
  "ok": true,
  "result": {}
}

Errors use:

{
  "ok": false,
  "error_code": 403,
  "code": "CHAT_FORBIDDEN",
  "description": "User has not started this bot."
}