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

# Telegram Alerts

> Deliver monitoring alerts into a Telegram direct message or group chat: connecting the bot, connection states, and troubleshooting.

Telegram alerts deliver matched developments straight into a Telegram chat, with no email, Slack,
or webhook infrastructure to run. Alerts can be sent two ways:

* **Direct Message.** The Blockworks alert bot messages you directly.
* **Group.** The Blockworks alert bot posts into a Telegram group you choose, so a whole team sees each alert.

Connecting Telegram is a one-time setup per monitoring view. You pick a destination, open a
single-use link that hands off to Telegram, complete a short confirmation there, then verify the
connection back in the app.

<Note>
  Each Telegram connection is tied to a single monitoring view. To send alerts from several views
  into the same chat, connect each view to that chat individually.
</Note>

<Warning>
  Group size is limited. Only groups smaller than **10** members can receive alerts.
</Warning>

## Connecting Telegram

Telegram delivery is configured in the [Intel app](https://app.blockworks.com), not
through the API: when you create or edit a monitoring view, the **Alerts & Access** step is where
you enable Telegram, alongside email, Slack, and [webhook](/api-reference/monitoring/webhooks)
delivery. The **Real-Time / Daily / Weekly** control at the top of **Alert Delivery** sets how
often alerts are sent.

<Steps>
  <Step title="Turn on the Telegram toggle">
    On the view's **Alerts & Access** step, switch the **Telegram** toggle on. A **Select Connection
    Type** row appears with two buttons: **Group** and **Direct Message**.

    <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/telegram-toggle-on.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=138d12063d35b9e8709c8cc1628dbef9" alt="Telegram toggle enabled showing the Group and Direct Message buttons" className="mx-auto" style={{ width:"70%" }} width="814" height="576" data-path="images/monitoring/telegram-toggle-on.png" />
  </Step>

  <Step title="Choose Group or Direct Message">
    Pick where alerts should go. The choice generates a one-time Telegram deep link unique to this
    view and reveals a **Click to Connect Telegram** button.

    <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/telegram-select-connection-type.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=c2321a060bd739ecc1f664a2cd46d744" alt="Select Connection Type buttons with the Click to Connect Telegram button" className="mx-auto" style={{ width:"70%" }} width="798" height="680" data-path="images/monitoring/telegram-select-connection-type.png" />

    <Note>
      The deep link is single-use and expires after a short window. If you do not finish the
      connection in time, the status shows an error; select **Cancel** and start over to generate a
      fresh link.
    </Note>
  </Step>

  <Step title="Open the link in Telegram">
    Select **Click to Connect Telegram**. A popup opens Telegram, using the desktop or mobile app if
    it is installed and Telegram Web otherwise, with the Blockworks alert bot (`@messari_alert_bot`)
    ready to be messaged directly or added to a group.

    <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/deep-link.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=ea72bab0987fd34ffb2453e29c563d7b" alt="Telegram deep link popup opening the Blockworks alert bot" className="mx-auto" style={{ width:"70%" }} width="1034" height="904" data-path="images/monitoring/deep-link.png" />
  </Step>

  <Step title="Complete setup inside Telegram">
    What you do next depends on the destination you picked.

    <Tabs>
      <Tab title="Direct Message">
        The bot chat opens with a **START BOT** button. Select it (this sends `/start`) and the bot
        replies to confirm the chat is connected.

        <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/dm-start.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=6269831d4d2473995ff16dab078a777e" alt="Telegram direct message with the alert bot confirming the chat is connected" className="mx-auto" style={{ width:"70%" }} width="952" height="1158" data-path="images/monitoring/dm-start.png" />
      </Tab>

      <Tab title="Group">
        Telegram opens an **Add to Group** picker. Search for your group and select it.

        <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/add-to-group.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=39da8c00a7c5040c42a25277207cba80" alt="Telegram Add to Group dialog selecting a group to add the alert bot to" className="mx-auto" style={{ width:"70%" }} width="724" height="600" data-path="images/monitoring/add-to-group.png" />

        On the **Add Bot** screen that follows, leave **Admin Rights** switched on and select
        **Add Bot as Admin**.

        <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/add-as-admin.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=cd1b16bdeff0458c1d97710404950e13" alt="Telegram Add Bot dialog with Admin Rights enabled and the Add Bot as Admin button" className="mx-auto" style={{ width:"70%" }} width="684" height="1370" data-path="images/monitoring/add-as-admin.png" />

        The bot posts in the group once it joins. If it still needs admin rights, its message spells
        out how to grant them: open the group's settings, tap **Administrators** then **Add Admin**,
        select the bot, and enable **Post Messages**.

        <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/group-admin-connected.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=775f5c25529855219fddf58c71f15af4" alt="Telegram group chat with the alert bot asking for the Post Messages permission" className="mx-auto" style={{ width:"70%" }} width="950" height="1162" data-path="images/monitoring/group-admin-connected.png" />

        <Warning>
          Admin rights with the **Post Messages** permission are required for groups. A bot that
          joins as a regular member stays pending and cannot deliver alerts.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify the connection">
    Back in the app, select **Check Connection**. The status line reports where things stand, so use
    it to tell whether Telegram is fully wired up or still waiting on a step.

    <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/waiting.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=a5807d9c31b8e8122bfcbf6bc33a4427" alt="Connection status line showing a waiting state with the Check Connection and Cancel actions" className="mx-auto" style={{ width:"70%" }} width="792" height="724" data-path="images/monitoring/waiting.png" />

    Confirmation from Telegram can take a moment to register, so if the status has not moved, wait a
    couple of seconds and select **Check Connection** again. See
    [Connection status](#connection-status) for what each state means.

    <img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/connected.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=68a460c4bcdd580d29e2b647e62fce17" alt="Connection status line showing the connected state after verifying" className="mx-auto" style={{ width:"70%" }} width="798" height="610" data-path="images/monitoring/connected.png" />
  </Step>

  <Step title="Save the view">
    Once the status reads **Connected**, save the monitoring view. Telegram delivery is now active,
    and matching alerts for this view go to the chat you connected.
  </Step>
</Steps>

## Connection status

| Status                                                        | What it means                                                                 |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `Waiting for the bot to be added...`                          | Direct Message chosen, but the chat with the bot has not been started yet.    |
| `Waiting for group Admin rights...`                           | Group chosen and the bot was added, but it has not been granted Admin rights. |
| `Waiting for the bot to be added and granted Admin rights...` | Group chosen, but nothing has been done in Telegram yet.                      |
| `Connected · Direct Message - <name>`                         | Alerts will be sent to you as a direct message.                               |
| `Connected · Group - <chat name>`                             | Alerts will be posted to the named group.                                     |

While a connection is pending, the app also prompts you to select **Check Connection** when you are
done on the Telegram side. Nothing is delivered until the status reads **Connected**.

## Managing an existing connection

**Cancel before connecting.** At any point before the connection completes, select **Cancel** to
back out and choose a different destination, for example switching from Direct Message to a Group.
Cancelling discards the pending deep link.

**Rebinding a connected view.** Opening a view that is already connected shows a read-only
**Connected** row with the current destination and a **Start over** option. Choosing **Start over**
rebinds the view to a different chat. The existing connection keeps delivering until the new one
succeeds, so no alerts are missed during the switch.

<img src="https://mintcdn.com/blockworksdocs/vDpnGk-ikoW5GBXD/images/monitoring/start-over.png?fit=max&auto=format&n=vDpnGk-ikoW5GBXD&q=85&s=4d948383f10704ce7454411c421a8c7c" alt="Connected row with a Start over option to rebind the view to a different chat" className="mx-auto" style={{ width:"70%" }} width="792" height="504" data-path="images/monitoring/start-over.png" />

<Note>
  **Start over** replaces the destination for this view only. Other views connected to the same chat
  are unaffected.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The status shows an error, or the link no longer works">
    The deep link is single-use and valid for a limited time. Select **Cancel**, pick the destination
    again, and use the fresh **Click to Connect Telegram** link right away.
  </Accordion>

  <Accordion title="The bot is in the group but the status stays pending">
    The bot joined as a regular member. Open the group's settings, tap **Administrators** then
    **Add Admin**, select the bot, enable **Post Messages**, and select **Check Connection** again.
  </Accordion>

  <Accordion title="The status does not update after finishing in Telegram">
    Confirmation can take a few seconds to propagate. Wait, then select **Check Connection** again.
    The status only advances when the app can see the completed handoff.
  </Accordion>

  <Accordion title="Alerts are not arriving in a group">
    Check the group size. Only groups smaller than 10 members can receive alerts. Also confirm the
    view was saved after the status read **Connected**: the connection is not persisted until the
    view is saved.
  </Accordion>

  <Accordion title="A second view needs to alert the same chat">
    Connections are per view. Open the other monitoring view and run the same setup against the same
    chat. Connecting a second view does not disturb the first.
  </Accordion>
</AccordionGroup>