Skip to main content
Chat with your GAIA on Telegram, Discord or Slack. You make a bot on each platform, then add it with one command:
Use discord or slack in place of telegram. The command asks for the bot’s token, checks it, saves it and starts the bot. No public URL or domain is needed.
Run it on the machine where you ran gaia up. Older installs need gaia update first.

​
Telegram

  1. In Telegram, message @BotFather and send /newbot. Pick a name and a username.
  2. BotFather replies with a token like 123456789:AA.... Copy it.
  3. Run gaia bots add telegram and paste the token.
A wrong or revoked token is rejected, and nothing changes:
Terminal output of gaia bots add telegram: it explains where to get a token from @BotFather, asks for the Telegram bot token, checks the credentials, and stops with Error: Telegram rejected the bot token: Unauthorized. Copy it again from @BotFather.

A token that Telegram rejects is never saved

​
Discord

  1. Open the Discord Developer Portal and create an application.
  2. On the Bot page, click Reset Token and copy the token.
  3. On the same page, turn on Message Content Intent. Without it the bot can’t read messages.
  4. Run gaia bots add discord and paste the token.
The command prints a link to add the bot to your server.

​
Slack

You need three values from your app’s page at api.slack.com/apps.
  1. Create an app From scratch in your workspace.
  2. Socket Mode: turn it on and create an app-level token with the connections:write scope (starts with xapp-).
  3. OAuth & Permissions: add the bot scopes app_mentions:read, chat:write, commands, im:history, im:read and im:write. Install the app and copy the Bot User OAuth Token (starts with xoxb-).
  4. Event Subscriptions: turn them on and subscribe to app_mention and message.im.
  5. Slash Commands: create /gaia, /auth, /workflow, /todo and /conversations. Leave the request URL empty.
  6. Basic Information: copy the Signing Secret.
  7. Run gaia bots add slack and enter the three values.
The bot only answers people who linked their chat account. In a chat with the bot, send /auth, open the link it sends and sign in. Each person does this once. Your instance’s Bots page (/bots) links to your bots.

​
Check on your bots

Terminal output of gaia bots list: No chat bots enabled. Add one with: gaia bots add <telegram|discord|slack>

gaia bots list on an install with no bots yet

A bot that keeps restarting usually has a revoked token. Run gaia bots add <platform> again with a fresh one. To see the error, run docker compose -p gaia-selfhost logs bot-telegram (or bot-discord, bot-slack).

​
Remove a bot

This stops the bot and deletes its token. People’s linked accounts stay linked.

​
Scripts and automation

Pass the values as flags:
  • A shared key, GAIA_BOT_API_KEY, in apps/api/.env
  • Your bot tokens in apps/bots/.env, readable only by your user
  • The published bot images, at your install’s version. gaia update updates them