# Telegram alerts

> Create a Telegram bot, find its Chat ID, connect it in BooleanSMTP, send a test alert, and fix common errors.

BooleanSMTP sends a Telegram message the moment an outgoing email finally fails to send. Setup uses your own Telegram
bot — BooleanSMTP only ever sees the bot token and Chat ID you enter. You need a bot, its bot token, and a Chat ID (which
chat the bot should post into).

## Create a Telegram bot

1. In Telegram, search for **@BotFather** and open a chat with it.
2. Send `/newbot`.
3. Choose a display name for your bot (for example "My Site Alerts").
4. Choose a username for it — it must end in `bot` (for example `mysite_alerts_bot`).
5. BotFather replies with a **bot token**, a string that looks like `123456789:AAH8x2C...`. Copy it. Keep it private —
   anyone with this token can send messages as your bot.

## Connect Telegram in BooleanSMTP

1. In the BooleanSMTP sidebar, click **Alerts**.
2. Under **Available Providers**, click the **Telegram** card.
3. In **Friendly Label**, enter a name for this channel (for example "Ops Telegram").
4. In **Bot token**, paste the token from the previous step.

## Find your Chat ID

1. In Telegram, send your new bot any message (search for its username and start a chat).
2. Back in BooleanSMTP, with **Bot token** already filled in, click **Detect** next to **Chat ID**.
3. Your chat appears in a small list below the field. Click it to fill in **Chat ID**.

If **Detect** finds nothing: you haven't sent the bot a message yet, or you're detecting a group chat with privacy mode
still on — send `/mybots` to **@BotFather**, pick your bot, go to **Bot Settings → Group Privacy**, and turn it off; then
message the group and try **Detect** again.

To post into a specific topic of a Telegram forum-mode group, fill in the optional **Forum topic ID (optional)** field
with that topic's numeric ID. Leave it blank for a normal group or private chat.

## Send a test alert

1. Toggle **Live Channel** on. BooleanSMTP does not send real alerts through a channel that is off.
2. Click **Send Test**. BooleanSMTP sends a real message to Telegram using the values currently in the form.
3. Click **Activate Channel** to save.

A failed test shows Telegram's own error text, not just "failed" — see below for what the common ones mean.

## Common errors

**"Bot token and Chat ID are required."** — one of the two fields is empty. Both are required.

**"Bad Request: chat not found"** — the bot hasn't been started by that chat yet. Send the bot a message first, or re-run
**Detect** to get a fresh Chat ID.

**A "Retry in N seconds" message** — Telegram is rate-limiting this bot. This is rare for normal alert volume; if you see
it often, several sites are likely sharing one bot token — use a separate bot per site.

**Detect finds your private chat but not a group** — turn off the bot's Group Privacy setting in @BotFather (see
[Find your Chat ID](#find-your-chat-id) above), then message the group again.

**Send Test worked, but no alerts arrive** — confirm **Live Channel** is on and the channel was saved with **Activate
Channel** (or **Update Channel**), not left unsaved in the form.

**Messages land in the wrong topic, or not in the topic at all** — double-check **Forum topic ID (optional)**. Leave it
blank if you're not using forum topics.

See also: [Alerts](/alerts/), [Slack alerts](/alerts/slack/), [Discord alerts](/alerts/discord/).