# Telegram

Telegram delivers **administrator alerts** — new reports, contact messages, and optionally new content. It is not a member notification channel, and the application works fully with it disabled.

## Settings

| Key | Meaning |
|---|---|
| `notifications.telegram_enabled` | Master switch |
| `notifications.telegram_bot_token` | Bot token from BotFather; stored as a secret |
| `notifications.telegram_chat_id` | Target chat, group or channel |

Group and channel ids are negative. Keep the leading minus sign; dropping it is the single most common configuration error.

## Requirements

- The `curl` extension
- Outbound HTTPS to `api.telegram.org`

Both are reported by the diagnostics page. Some shared hosts block outbound HTTPS to non-whitelisted hosts; that shows up as a transport error, not as an authentication error.

## Testing

Use the test action in the notification settings and read the reported cause:

| Result | Cause | Fix |
|---|---|---|
| 400 | Chat id malformed or wrong | Re-read the id; keep the minus sign for groups |
| 401 | Token invalid | Re-copy from BotFather; check for a trailing space |
| 403 | The bot was never started, was blocked, or is not a channel admin | Message the bot first; promote it in a channel |
| transport error | cURL missing or egress blocked | Enable cURL; ask the host about outbound HTTPS |

Messages are translated and actionable. **Tokens and provider response bodies are never written to logs**, so a log file cannot leak the bot.

## Choosing events

Enable only what an administrator will act on. A channel that fires on every new question trains the team to mute it, and the report that mattered is then missed.

Sensible defaults: reports and contact messages on; new questions off unless the site is quiet enough that each one deserves attention.

## Failure behaviour

Delivery is inline, with no queue. A Telegram outage never blocks a member's post — the write succeeds and the delivery failure is logged.

## Rotating the token

Rotate immediately if the token appears in a screenshot, a paste, or a repository. Anyone holding it controls the bot. BotFather can revoke and reissue.

Step-by-step setup: [Telegram bot setup](../09-recipes/TELEGRAM-BOT-SETUP.md). Internals: [Notifications flow](../07-internals/NOTIFICATIONS-FLOW.md).
