Create and manage bots

Every bot you own is listed in My Bots. From there you can create a bot, copy its API token, and later change its details, pause it or delete it.

Availability

You can create bots in every app. The web app creates API bots only. The desktop app can pause and reactivate bots but can’t edit them, regenerate their tokens or delete them; use the iPhone, Android or web app for those.

Open My Bots

• iPhone, Android and web app: go to Profile > Tools & content > My Bots.
• Desktop app: go to Settings > App > My bots.

The list shows each bot’s picture, name and @username. A bot that’s switched off is labeled Paused identity on iPhone, Paused on Android and in the desktop app, and Inactive in the web app.

Bots that DonutChat creates for ChatGPT agents always show this label on iPhone, Android and the web app (the desktop app shows External agent). Leave them switched off: switching one on stops the agent from working in your conversations.

Add a bot

Tap + (Add a bot) on iPhone or Android, or click Add a bot in the desktop app. The app asks how you’ll use the bot:

• Create an AI assistant sets up an assistant that DonutChat runs for you. It needs approval and your own OpenAI or Anthropic API key. See Hosted AI assistants.
• Developer options > Build an API bot creates a bot that your own software runs. The steps are in the next section.

The web app has a single Create bot form, for API bots. You don’t create a bot for a ChatGPT agent here; DonutChat creates it when you set up the agent. See ChatGPT agents.

Create an API bot

iPhone

1. Open My Bots and tap +.
2. Open Developer options and tap Build an API bot.
3. Enter a Name, a Username and, if you want, a Description (optional).
4. Under Trigger mode, choose when the bot receives messages: When mentioned, All human messages or Manual only.
5. Tap Create and continue.
6. On Bot created!, tap Copy token, store the token somewhere safe, then tap Done.

Android

1. Open My Bots and tap +.
2. Tap Developer options, then tap Build an API bot.
3. Enter a Name, a Username and, if you want, a Description (optional).
4. Under Trigger mode, choose when the bot receives messages: When mentioned, All human messages or Manual only.
5. Tap Continue.
6. On Bot created!, tap Copy token, store the token somewhere safe, then tap Done.

Desktop

1. Open My bots and click Add a bot.
2. Open Developer options and click Build an API bot.
3. Enter a Name and a Username.
4. Click Create and continue.
5. Click Copy API token privately and store the token somewhere safe.
6. Click Go to My bots.

The desktop form has no description or trigger mode fields, so the bot starts in When mentioned mode. Copy the token before you switch to another window: the app hides it when the window loses focus, and you’d have to regenerate it in another app.

Web

1. Open My Bots and click + (or Create Bot if you don’t have any bots yet).
2. Enter a Name, a Username and, if you want, a Description (optional).
3. Under Trigger mode, choose when the bot receives messages: When mentioned, All human messages or Manual only.
4. Click Create.
5. On Bot created!, click Copy token, store the token somewhere safe, then click Done.

On iPhone, Android and the web app, the API usage example on the same screen has a curl command (Copy curl) for a test message. It works once the bot is in a chat and you replace CHAT_ID with that chat’s ID, which you can copy from Chat info > Manage chat > Chat ID. The copied command includes your token, so don’t paste it into a chat or share it.

Choose when a bot responds explains the trigger modes. Next, add the bot to a chat and connect your software with the Quickstart.

The token is shown only once

Anyone who has the token can act as your bot in every chat it belongs to. Keep it in a password manager or your server’s secret settings, and never paste it into a chat. If you lose it or it leaks, regenerate it.

Name, username and description

Field	Rules
Name	Required. Shown as the sender name on the bot’s messages. Keep it to 32 bytes or fewer.
Username	Required. English letters (a–z), numbers and underscores, up to 32 characters, saved in lowercase. People type it to @mention the bot, in any letter case. You can’t change it later, and no other bot can already have it. The desktop app also requires 5–32 characters, starting with a letter.
Description	Optional. Up to 500 bytes. Shown on the bot’s profile.
Picture	Add it after you create the bot. See Edit a bot.

In byte limits, each English letter, digit or space counts as 1 byte, and accented letters and most other scripts take 2 or 3 bytes. A typical emoji takes 4 bytes, and flags or emoji with a skin tone take more.

If creating a bot fails with We couldn’t create this bot. Please try again., the username may already be taken. Try a different one.

Bot home and profile

Open a bot from My Bots to see its home: Bot home on iPhone and Android, Bot Details in the web app. On iPhone and Android, other people see your bot’s public profile, Bot Profile, when they tap the bot’s name on one of its messages.

On iPhone and Android, the bot home has these sections:

Section	What it’s for
Connection details (Android: Connection status)	Whether the bot is active, whether its event stream was connected at the last refresh, and its trigger mode.
Conversations	The chats the bot is in. Add it to a chat with Add to Chat. The menu next to a chat removes the bot from it or, if you own or manage that chat, changes the bot’s trigger mode there.
Behavior	Change the bot’s default trigger mode and its profile.
Model & connection	Set up or manage a hosted AI assistant on this bot.
Advanced developer settings (Android: Advanced · developer settings)	The bot’s event webhook, and integration prompts you can copy into an AI coding agent. See Event webhooks.

The web app’s Bot Details page shows the bot’s status, chats, event webhook and integration prompts on one page.

Let a bot upload files

A bot can’t attach files to its replies until you allow it. Only you, as the bot’s owner, can change this.

• iPhone and Android: open the bot from My Bots, then turn on Allow file uploads. The switch appears for bots whose execution method is Bot token / API integration or My own Hermes; other methods don’t use the bot API.
• Desktop app: open Manage bot under the bot and turn on Allow file uploads.

With this on, the bot can attach images (PNG, JPEG, GIF, WebP), PDFs and plain-text files to its thread replies, up to 10 MiB each. Turn it on only for bots whose code you trust: anyone who has the bot’s token can then post files in every chat the bot is in. Files stay in the chat after you turn the setting off. See Attach files for the API.

Start a private conversation with a bot

On a bot’s home or profile, tap Open conversation (iPhone, Android) or click Message (web app). In the desktop app, open Manage bot under one of your bots and click Chat with bot. DonutChat opens a conversation named after the bot with just you and the bot, or reopens it if it already exists.

An API bot receives every message you send in this conversation. To ask a hosted AI assistant, see Hosted AI assistants.

Anyone who can open your bot’s profile can start a private conversation with it while it’s active, and the bot receives what they send there.

Edit a bot

1. Open the bot from My Bots.
2. Open the menu (⋯ on iPhone, ⋮ on Android and the web app) and select Edit.
3. Change Name, Description, Active or Trigger Mode. To change the picture, select it and choose a photo.
4. Select Save.

You can’t change a bot’s username. In the desktop app you can only pause or reactivate a bot.

Pause a bot

Switch off Active when you edit the bot. In the desktop app, open Manage bot under the bot and click Pause. While a bot is paused:

• It receives no messages from any chat.
• Its software can’t use the bot API with its token.
• Nobody can add it to a chat or start a new private conversation with it. On iPhone and Android, its profile shows This bot is inactive. New chats are unavailable. In the web app, the Message button is hidden.

Switch Active back on (desktop app: Activate) to resume. To quiet a bot in only one chat, see Pause or remove a bot.

Regenerate the API token

1. Open the bot from My Bots.
2. Open the menu (⋯ on iPhone, ⋮ on Android and the web app) and select Regenerate Token, then Regenerate to confirm.
3. In New API Token, select Copy, store the token somewhere safe, then select Done.

The old token stops working immediately, so update your software with the new one. The new token is also shown only once. The desktop app can’t regenerate tokens.

Delete a bot

Open the bot, open the menu and select Delete, then select Delete in the Delete Bot dialog. The desktop app can’t delete bots.

Caution

Deleting a bot can’t be undone. To stop a bot but keep it, pause it instead.

Related

• Use bots in chats
• Hosted AI assistants
• Quickstart: build a bot
• Authentication