Skip to main content

​
Telegram Integration Setup

This guide is for self-hosted deployments that want to enable Telegram chat with the Inbox Zero assistant.

​
1. Create a Telegram bot with BotFather

  1. Open Telegram and start a chat with @BotFather
  2. Send /newbot
  3. Choose a display name and bot username (must end with bot)
  4. Copy the bot token BotFather returns — this is your TELEGRAM_BOT_TOKEN

​
2. Configure the webhook

Set your bot’s webhook to Inbox Zero: 
curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
  -d "url=https://<your-domain>/api/telegram/events" \
  -d "secret_token=<TELEGRAM_BOT_SECRET_TOKEN>"
If you do not want to use a secret token, omit secret_token from the command. You can verify webhook status with: 
curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo"

​
3. Set environment variables

Set these in apps/web/.env (or your deployment env): 
TELEGRAM_BOT_TOKEN=
TELEGRAM_BOT_SECRET_TOKEN= # optional but recommended
If TELEGRAM_BOT_TOKEN is missing, the Telegram connect option is hidden in the UI and /api/telegram/events returns 503. If TELEGRAM_BOT_SECRET_TOKEN is set, webhooks must include x-telegram-bot-api-secret-token with the same value or requests are rejected.

​
4. Configure bot commands and optional profile photo (one-time)

Run the setup script once after configuring your environment: 
pnpm --filter inbox-zero-ai exec tsx scripts/setup-telegram-bot.ts
Local shortcut: 
pnpm --filter inbox-zero-ai telegram:setup
To also set a bot profile photo: 
pnpm --filter inbox-zero-ai exec tsx scripts/setup-telegram-bot.ts \
  --profile-photo-url https://<your-domain>/telegram-bot.png
This command registers Telegram slash commands (/connect, /switch, /help, /cleanup, /summary, /draftreply, /followups) and sets a profile photo only if the bot does not already have one.

​
5. Connect a user account from Inbox Zero

Each Inbox Zero email account links to a Telegram user via a connect code:
  1. In Inbox Zero, go to Settings → Connected Apps
  2. Click Connect Telegram
  3. Copy the generated command: /connect <code>
  4. Open a direct message with your bot in Telegram
  5. Send the command
After linking, the user can chat with the assistant in that DM.

​
6. Validate end-to-end

Check:
  1. POST /api/telegram/events returns 200 for valid Telegram updates
  2. Sending /connect <code> in bot DM links the account
  3. A normal DM message gets an assistant response
If linking fails, generate a new code — codes are one-time and expire after 10 minutes. For local development, Telegram must reach a public HTTPS URL (for example, via ngrok); localhost is not reachable from Telegram.