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

# Telegram

> Route Tallwatch alerts to a Telegram group, channel, or DM through a bot you create.

Tallwatch sends a plain-text message to Telegram using the [Bot API](https://core.telegram.org/bots/api). Telegram has no one-click webhook, so setup takes about five minutes: you create a bot, copy its token, and tell Tallwatch which chat to post to.

You'll need a Telegram account and the chat (group, channel, or DM) that should receive alerts.

## 1. Create a bot with BotFather

<Steps>
  <Step title="Open BotFather">
    Search for `@BotFather` in Telegram and start a chat. It's the official bot for managing bots.
  </Step>

  <Step title="Create the bot">
    Send `/newbot` and follow the prompts. Pick a name (`Tallwatch alerts`) and a username ending in `bot` (`tallwatch_alerts_bot`). The username has to be unique across Telegram.
  </Step>

  <Step title="Save the token">
    BotFather replies with a token like `123456789:AAEfghijklmnopqrstuvwxyz`. Keep it somewhere safe.
  </Step>
</Steps>

<Warning>
  The bot token is a credential. Anyone who has it can post as the bot to any chat it has joined. If it leaks, run BotFather's `/revoke` to issue a new token, then update Tallwatch.
</Warning>

## 2. Add the bot to the chat and find the chat ID

Telegram doesn't show chat IDs in its client, so you add the bot first, then read the ID from the API.

<Steps>
  <Step title="Add the bot">
    In a group, open the group name and **Add member**, search for your bot's username, and add it. For a channel, add the bot as an admin so it can post. For a DM, open the bot and press **Start**.
  </Step>

  <Step title="Post a message">
    Send any message in the chat. This guarantees the bot's update log has a recent entry to read.
  </Step>

  <Step title="Read the chat ID">
    Open `https://api.telegram.org/bot<TOKEN>/getUpdates` in your browser, replacing `<TOKEN>` with the bot token. Find `chat.id` in the JSON. It's negative for groups and channels (`-1001234567890`) and positive for DMs.
  </Step>
</Steps>

<Tip>
  If `getUpdates` returns an empty array, the bot hasn't seen any messages. Post another one in the chat and retry.
</Tip>

## 3. Add the channel in Tallwatch

<Steps>
  <Step title="Open the channels page">
    Go to **Settings → Alerts → Channels** and click **Add channel**.
  </Step>

  <Step title="Pick Telegram">
    Choose the Telegram kind and name it for the audience, like `Telegram on-call`.
  </Step>

  <Step title="Paste the token and chat ID, then test">
    Put the BotFather token in **Bot token** and the `getUpdates` ID in **Chat ID**. Click **Save**, then **Send test alert**. The message should arrive within a few seconds.
  </Step>
</Steps>

## What the alert looks like

A Markdown-formatted message:

* The event and the monitor name
* The URL, when there is one
* The failing regions
* When the incident opened
* The last error from the check
* Your workspace name

There are no rich cards in v1; Telegram renders it with its standard formatting.

## Troubleshooting

<AccordionGroup>
  <Accordion title="`bot was kicked from the group`">
    Someone removed the bot. Re-add it (as admin for a channel), post a message so `getUpdates` works again, and retry the test.
  </Accordion>

  <Accordion title="`chat not found`">
    The chat ID is wrong or the bot was never added. Post a fresh message in the target chat, re-run `getUpdates`, and copy the correct ID.
  </Accordion>

  <Accordion title="`Unauthorized` from the Bot API">
    The token is invalid, usually because it was revoked in BotFather or copied with stray whitespace. Re-issue with `/revoke` and update Tallwatch.
  </Accordion>

  <Accordion title="The bot doesn't see new messages in `getUpdates`">
    Telegram keeps only the last 24 hours of updates, so old messages expire. Post a fresh one and retry.

    Also, another long-poll consumer (a second bot integration) may be reading and acknowledging updates before you. If `getUpdates` keeps coming back empty, that's why. Add `?offset=-1` to read just the latest update without acknowledging it.
  </Accordion>
</AccordionGroup>

## Reference

| Property        | Value                                                                   |
| --------------- | ----------------------------------------------------------------------- |
| Channel kind    | `telegram`                                                              |
| Required config | `bot_token`, `chat_id`                                                  |
| Delivery        | Immediate, no proactive rate limit; Telegram enforces its own           |
| Retry           | Up to 3 inline attempts on 5xx, 429, network, or timeout, then `failed` |
| Outbound to     | `api.telegram.org`                                                      |