> ## Documentation Index
> Fetch the complete documentation index at: https://latch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Get notifications and approve actions from your phone.

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:

```bash theme={null}
# 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)

## 4) Link your user account in the dashboard

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`.