# Recipe: Telegram bot setup

Telegram is for **administrator alerts** — new reports, new questions, contact messages. It is not a member notification channel.

## 1. Create the bot

In Telegram, talk to **@BotFather**:

1. `/newbot`
2. Give it a display name and a username ending in `bot`
3. BotFather returns a token in the form `123456789:AA...`

Treat that token like a password. Anyone holding it controls the bot.

## 2. Get the chat id

**For a personal chat:** message your bot once — a bot cannot start a conversation — then read the chat id from the updates endpoint, or use a chat-id helper bot.

**For a group:** add the bot to the group, send one message, then read the id. Group ids are negative; keep the minus sign.

**For a channel:** add the bot as an administrator; the id is negative and typically starts with `-100`.

## 3. Configure Quaeriva

Settings → Notifications:

```
Telegram enabled: on
Bot token:        123456789:AA...
Chat id:          the value from step 2
```

## 4. Test

Use the test action and read the result:

| Result | Cause | Fix |
|---|---|---|
| 400 | Chat id malformed or wrong | Re-read it; keep the leading minus 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 unavailable, or outbound HTTPS blocked | Enable cURL; ask the host about egress |

Tokens and provider response bodies are never written to logs.

## 5. Choose the events

Enable only what an administrator will actually act on. An alert stream nobody reads is worse than no alerts, because it teaches everyone to ignore the channel.

Reasonable defaults: new reports and contact messages on; every new question off unless the site is quiet.

## Notes

- The application works with Telegram disabled. It is an amplifier, not a dependency.
- Delivery is inline. A Telegram outage never blocks a member's post; the failure is logged.
- Rotate the token if it ever appears in a screenshot, a paste or a repository.

See [Telegram](../03-configuration/TELEGRAM.md) and [Notifications flow](../07-internals/NOTIFICATIONS-FLOW.md).
