Skip to main content
GAIA has bots for Discord, Slack, Telegram, WhatsApp and iMessage. They live in apps/bots/ and all talk to the same GAIA API, so a user’s conversations, todos and workflows are the same on every platform. This section is for running and changing the bots from source. To add the bots to a self-hosted instance, see Self-Hosting: Bots. To chat with GAIA on a platform as a user, see the guides for Slack, Discord, Telegram, WhatsApp or iMessage.

How the bots work

Each bot is a thin TypeScript process that forwards a platform’s messages to the GAIA API, then renders the reply in the platform’s own format: for example embeds on Discord, Block Kit on Slack, Markdown on Telegram and plain text on iMessage. The shared logic (commands, streaming, formatting, the API client) lives in libs/shared/ts/src/bots/, so most changes are made once for every platform. Users link their platform account to their GAIA account once, with the /auth command. Each bot serves GET /health on its port. BOT_SERVER_PORT overrides the port.

Shared setup

Do this once, whichever bot you work on.
1

Run GAIA

Follow Set up GAIA for development until mise dev --agent is running.
2

Create the bots' env file

All bots read one shared file, apps/bots/.env:
Then set the four values every bot needs:A bot refuses to start while any of these four is missing.
3

Give the API the same secrets

In apps/api/.env, set GAIA_BOT_API_KEY to the same value: the API rejects bot requests whose key doesn’t match. Set BOT_LOG_HASH_SECRET to the same value too, so a user’s hashed id matches in the API’s and the bots’ logs. Also set BOT_SESSION_TOKEN_SECRET to a third value from openssl rand -hex 32: the API uses it to sign the bots’ session tokens. Restart mise dev after editing.
4

Add the platform's credentials

Follow the page for your platform below. It adds that platform’s token to apps/bots/.env.
5

Start the bot

RABBITMQ_URL is already set in the template. Keep it: without it the bot can still answer messages, but it never receives the replies and reminders the API sends later on its own, such as the result of a long background task. Per-bot files (apps/bots/<platform>/.env) are still read, after the shared file, for Docker and older setups. Prefer the shared file: when both set a variable, the shared file wins.

Platform guides

Discord

Discord application, gateway intents, slash commands, account linking

Slack

Slack app with Socket Mode, no public URL required

Telegram

BotFather setup with long polling, no webhook required

WhatsApp

Kapso and the Meta Cloud API, through a signed webhook

iMessage

Photon Spectrum, through a signed webhook

Test without a platform account

bot-harness (apps/bots/harness) is a simulated platform. It sends a message through the real shared bot code to your running API and records the reply, with no Discord, Slack or Telegram account:
It needs the same apps/bots/.env. apps/bots/harness/README.md covers scenarios and flags. The bots’ unit tests run with mise test:bots.

Commands

Every platform has the same core commands (/gaia, /todo, /workflow, /conversations, /auth). The full list, with platform differences, is in the Commands reference.