Skip to main content
Bots are automated user accounts you own. Each bot has its own User (with a username, display name, avatar, and description) and its own long-lived API token. You use the token to call almost any Clody API endpoint as the bot — sending messages, uploading files, reacting, and more. This guide covers how to create a bot, authenticate as one, and manage its lifecycle. For the full endpoint reference, see Bots API.

​
How Bots Work

  • Every bot is backed by a real User account with isbot = true. That user has a numeric ID just like any human account.
  • Only the owner of a bot can create, edit, delete, or regenerate the token for that bot. The owner is the user who called /api/bot/create.
  • Each user can own up to 20 bots.
  • The bot’s username must contain the word bot (case-insensitive). This is enforced at creation time.
  • Bots authenticate via the Authorization header instead of a session cookie. See Authenticating as a Bot.
  • Bots can be added to Branches like any other user, and once inside a Branch they can send/edit/delete their own messages, upload files, react, and receive real-time events.

​
Create a Bot

POST /api/bot/create Creates a new bot owned by the current session user. Requires a logged-in human session — you cannot create bots using another bot’s token.
​
string
required
Username for the bot. Max 32 characters. Must contain the substring bot (case-insensitive). Must be unique across all users.

​
Example

​
Response

The token field is returned only once, at creation time. Store it immediately — you cannot retrieve it again. If you lose it, use /api/bot/regenerate to issue a new one.

​
Authenticating as a Bot

Instead of a session cookie, send an Authorization header on every request. The value is the bot’s user ID (not the bot ID), a space, and the token you received:
Example:
Use the user field from the create response, not the id field. id is the internal bot record ID; user is the bot’s user ID and is what the rest of the API expects.
A valid header authenticates the bot for that request just like a session cookie would authenticate a human. If the header is malformed, the user isn’t a bot, or the token doesn’t match, the request is treated as unauthenticated and returns 400 Not Authorized.

​
Which endpoints accept bot auth?

Any endpoint whose handler calls check_session(..., header_authorization=request.headers.get("Authorization")) accepts a bot token. In practice this covers messaging, Branches, CDN uploads, reactions, gifs, comments, picnics, friends, voice calls, and settings. A small number of endpoints explicitly reject bots (they pass allow_bots=False). Bot management itself (/api/bot/*) is one such group — you cannot manage bots using another bot’s token.

​
Edit a Bot’s Profile

POST /api/bot/edit Update the bot’s display name and description. Both are shown to other users in chats.
​
number
required
The bot’s id (the internal bot record ID from the create response).
​
string
required
New display name. Trimmed; max 64 characters after trimming; must be non-empty.
​
string
Optional description shown on the bot’s profile. Trimmed and truncated to 300 characters. Omit or send "" to clear.
Returns the updated bot summary.

​
Regenerate the Token

POST /api/bot/regenerate Issue a new token and invalidate the old one. Use this if the token leaked or you rotated credentials.
​
number
required
The bot’s id.

​
Response

The new token is shown once. The previous token stops working immediately.

​
List Your Bots

GET /api/bots/get Returns every bot owned by the current session user, newest first. The token field is not included — tokens are only visible at creation and regeneration time.

​
Delete a Bot

POST /api/bot/delete Permanently deletes the bot, its backing user account, and removes it from every Branch it was a member of. Messages the bot sent are not deleted.
​
number
required
The bot’s id.
Deletion is irreversible. The bot’s username becomes available for reuse.

​
Common Patterns

​
Sending a message from a bot

Once your bot is a member of a Branch, sending a message is a normal POST /api/bmessage/send — just use the bot’s Authorization header instead of a session cookie. See Branch Messages.

​
Adding your bot to a Branch

You add the bot the same way you add any user — by calling /api/branch/add_member with the bot’s user ID. The bot must be a friend of the branch member adding it, following the same friendship rules as human users.

​
Receiving real-time events

Bots can open a Socket.IO connection just like a user. Authenticate the socket handshake by including the Authorization header. The bot receives all the same events as any Branch member — new_bmessage, update_bmessage, added_branch, and so on. See WebSocket Events.

​
Errors