Skip to main content
Latch can send Telegram notifications when an action requires approval, and lets you approve/deny from your phone.

​
1) Create a Telegram bot

  1. Open Telegram and chat with @BotFather.
  2. Run /newbot and follow prompts.
  3. Copy the bot token (looks like 123456:ABCDEF...).
  4. (Recommended) Set a bot username (used for the “Connect Telegram” link).

​
2) Configure environment variables

Add these to your environment (Docker: docker-compose.yml / production: your secret manager):
  • TELEGRAM_BOT_TOKEN
  • TELEGRAM_BOT_USERNAME (without the @)
  • NEXT_PUBLIC_APP_URL (your public URL, used to compute the webhook URL)
For local dev, you can put them in .env (see env.example).

​
3) Set the Telegram webhook

Latch receives Telegram updates at: /api/telegram/webhook Use the provided helper script: 
# Uses NEXT_PUBLIC_APP_URL from .env by default
npx tsx scripts/setup-telegram.ts

# Or explicitly pass a public base URL
npx tsx scripts/setup-telegram.ts https://your-public-url.example
This calls Telegram’s setWebhook API and prints the webhook info.

​
Local development note

Telegram requires a publicly reachable HTTPS URL for webhooks. For local dev, use something like a tunnel (ngrok/cloudflared) and pass that URL into the script, then set:
  • NEXT_PUBLIC_APP_URL to the same tunnel URL (so dashboard links match)
  1. Start Latch and open the dashboard.
  2. Go to Settings.
  3. Click “Connect Telegram”.
  4. Telegram will open a link to your bot with a start token.
  5. Press Start in the bot.
Once linked, approval notifications will be sent to your Telegram account.

​
Troubleshooting

​
“Telegram bot not configured”

  • Ensure TELEGRAM_BOT_USERNAME is set in the app environment.

​
“TELEGRAM_BOT_TOKEN not configured”

  • Ensure TELEGRAM_BOT_TOKEN is set in the app environment.

​
Webhook seems set, but nothing arrives

  • Confirm the webhook URL in Telegram matches your public base URL + /api/telegram/webhook.
  • Check app logs for webhook errors.
  • Ensure your deployment allows POSTs to /api/telegram/webhook.