﻿The Telegram notifier sends messages through a Telegram bot. One bot token and
one `chat_id` point at one destination: a direct chat, a group, or a channel.

```toml title="runwisp.toml"
[notifiers.tg-oncall]
type      = "telegram"
bot_token = "${TG_BOT_TOKEN}"
chat_id   = "-1001234567890"
```

## Fields

| Key             | Required | What it does                                                                                          |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `bot_token`     | yes      | The bot token. Keep it out of the file; see [Storing the secret](/notifications/#storing-the-secret). |
| `chat_id`       | yes      | Where to send. A string, so negative group ids stay intact.                                           |
| `parse_mode`    | no       | Telegram's parse mode. Default `HTML`, which the built-in template uses.                              |
| `template_path` | no       | A Go template file that replaces the built-in message.                                                |

## Creating the bot

Message [@BotFather](https://t.me/BotFather) in Telegram:

1. Send `/newbot`.
2. Pick a display name.
3. Pick a username ending in `bot`, like `runwisp_ops_bot`.
4. BotFather replies with a token like
   `123456789:AAEa-PXxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. Save it.

Anyone with the token can post as your bot, so treat it as a secret.

## Finding the chat_id

First make the bot see a message in the chat you want:

- **Direct chat:** send your bot a message.
- **Group:** add the bot to the group and send any message there.
- **Channel:** add the bot as an administrator with "Post Messages"
  permission, then post a message.

Then open this URL with your token:

```
https://api.telegram.org/bot<TOKEN>/getUpdates
```

Find `"chat": { "id": ... }` in the JSON. A direct chat has a positive number
like `123456789`. Groups have negative ids, and channels and supergroups start
with `-100`, like `-1001234567890`.

To send some tasks to another chat with the same bot, use `"tg-oncall:<chat id>"`
in [`notify`](/configuration/tasks/#notify); see
[One channel, several destinations](/notifications/#one-channel-several-destinations).

## When messages don't arrive

If the bell shows a `notify.delivery_failed` warning, it includes Telegram's
error. Common causes:

- A wrong `chat_id`: Telegram answers `400 Bad Request: chat not found`.
- The bot isn't in the group, or can't post in the channel.
- A bad token. Check it with
  `curl https://api.telegram.org/bot<TOKEN>/getMe`, which returns the bot's
  profile when the token is valid.

## What a message looks like

```
❌ backup-postgres failed

Exited with code 1 after 0.3s.
Triggered via the REST API · 14 May, 17:11.

> Error: connection refused
> dial tcp 127.0.0.1:5432: connect:
> connection refused

🔗 View full run

from runwisp · bright-falcon
```

- The output block appears for failures and timeouts, up to three lines or 300
  bytes, when there is a log.
- The **View full run** link opens the run and appears only when the
  [Web UI address](/configuration/daemon/#external_url) is known.
- The footer names the daemon that sent it.

## Changing the message

Point `template_path` at your own Go template. Start from the built-in
[`telegram.tmpl.html`](https://github.com/runwisp/runwisp/blob/main/apps/runwisp/internal/notify/render/defaults/telegram.tmpl.html).
It gets the whole event and the same helpers as the
[Slack template](/notifications/providers/slack/#changing-the-message).

The built-in template is HTML. To write yours in Markdown, set
`parse_mode = "MarkdownV2"` together with `template_path`.

## What's rejected

- A missing or empty `bot_token` or `chat_id`.
- `parse_mode = "MarkdownV2"` without `template_path`.
