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

# Telegram

> Send incidents to a Telegram group, topic or channel using your organization's own bot.

Telegram has no incoming webhooks. That's why aciona.me sends messages through a **bot created by your organization**. The name and picture shown in the chat are your bot's.

## Setting it up

<Steps>
  <Step title="Create the bot with @BotFather">
    In Telegram, open **@BotFather** and send `/newbot`. Name it `aciona.me` and pick a username ending in `bot`. Optionally set the bot picture with `/setuserpic` using the official aciona.me icon.

    Copy the **token** BotFather returns (format `123456789:AA…`).
  </Step>

  <Step title="Add the bot to the chat">
    Add the bot to the **group** that should receive incidents. For a **channel**, add the bot as an **administrator** allowed to post messages.
  </Step>

  <Step title="Find the Chat ID">
    Send any message in the group and open in your browser:

    ```text theme={null}
    https://api.telegram.org/bot<TOKEN>/getUpdates
    ```

    Look for `"chat":{"id":-100…}`. Groups, supergroups and channels have IDs starting with `-100`. Public channels also accept `@channel_name`.

    In groups with **topics**, the same result shows the topic's `message_thread_id` — enter it in the **Topic ID** field so messages land in that topic.
  </Step>

  <Step title="Add the integration in aciona.me">
    Under **Integrations → Telegram**, fill in the **Bot token**, the **Chat ID** and, optionally, the **Topic ID** and a **display name**. Owners and admins can do this.
  </Step>

  <Step title="Test it">
    Click **Test**. A test message should show up in the chat within a few seconds.
  </Step>
</Steps>

<Warning>
  The token gives full control of the bot. Don't share it in tickets, screenshots or messages. If it leaks, generate a new one with `/revoke` in @BotFather and update the integration.
</Warning>

## After saving

For security, aciona.me **never shows the token back**. The form shows the Chat ID, the Topic ID and only a mask with the last characters of the token.

* To change the name, status, chat or topic, you **don't need to type the token again**.
* To replace the token, just type the new one in the field.

## One chat per team

The organization configuration is the **default** for every team. Under **Team overrides**, you can point a specific team to another bot and chat (or disable it). Teams without an override keep using the organization configuration.

Removing a team's override makes it fall back to the organization configuration, if there is one.

## What lands in the chat

A message in the organization's language with:

* A highlighted title and severity shown as an emoji: 🔴 critical, 🟠 high, 🟡 warning, 🔵 low, ⚪ info.
* Affected service, alert source, current owner and event time, in the paged schedule's time zone (with the zone shown; UTC when there is no schedule).
* **Open incident**, **Acknowledge** and **Assign to me** buttons, which open the authenticated dashboard.

Messages follow the lifecycle: creation, acknowledgement, assignment, escalation and resolution each post a message. Acknowledgement, assignment and resolution arrive **silently** — only new and escalated incidents make a sound.

<Note>
  Like Slack, Teams and Discord, Telegram receives the incident **regardless** of whether personal recipients were resolved. Even if the schedule points at nobody, the chat still sees the incident.
</Note>

## Privacy

Telegram groups and channels are **not end-to-end encrypted**. Incident content is visible to Telegram and to every member of the chat. Pick a group restricted to the people who need to see incidents.

## Good practices

<AccordionGroup>
  <Accordion title="Use a dedicated group or topic" icon="hash">
    A group (or a topic) just for incidents keeps the history readable and lets you mute the rest of the conversation without missing alerts.
  </Accordion>

  <Accordion title="Telegram does not replace push" icon="triangle-alert">
    A group message is visibility, not paging. Whoever is on call needs push on their phone.
  </Accordion>

  <Accordion title="One bot per organization" icon="bot">
    Create a bot just for aciona.me instead of reusing one that does other things. That way, revoking the token doesn't affect other automations.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Symptom | What to check |
| - | - |
| Token rejected by the form | Use the full token generated by @BotFather, in the `123456789:AA…` format. |
| Chat ID rejected by the form | Use a number (e.g. `-1001234567890`) or `@public_channel`. |
| The test fails | The token is correct; the bot is in the group or channel; in channels, the bot is an administrator allowed to post; supergroup and channel Chat IDs start with `-100`. |
| Message lands outside the topic | Check the **Topic ID**. Without it, messages go to the group's general topic. |
| It worked and then stopped | The bot was removed from the group, lost admin rights, or the token was revoked. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.