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

# Telegram

> Send security alerts to Telegram chats through a bot, with per-user pairing

The Telegram integration sends security alerts to Telegram through a bot you control. Because one bot can talk to many people, each user pairs their own Telegram account to the integration before they receive alerts.

## Prerequisites

* A Telegram account.
* A bot created with **BotFather**, and its bot token.

## Create a bot

<Steps>
  <Step title="Open BotFather">
    In Telegram, search for **BotFather** and open the chat.
  </Step>

  <Step title="Create the bot">
    Send `/newbot` and follow the prompts. Choose a display name and a username that ends in `bot`, for example `oasm_alerts_bot`.
  </Step>

  <Step title="Copy the token">
    BotFather replies with a token that looks like `1234567890:ABCdef...`. Copy it.
  </Step>
</Steps>

<Warning>
  The bot token grants full control of the bot. Keep it secret. If it leaks, revoke it with BotFather (`/revoke`) and reconnect the integration.
</Warning>

## Connect Telegram

<Steps>
  <Step title="Open the Applications tab">
    In the console sidebar, open **Integrations** and select the **Applications** tab.
  </Step>

  <Step title="Open Telegram">
    Select the **Telegram** card.
  </Step>

  <Step title="Enter a name and bot token">
    Enter an **Integration name**, then paste the **Bot Token** from BotFather.
  </Step>

  <Step title="Choose events">
    Use the **Event** and **Severity** switches to control what OASM sends. See [What notification integrations send](/integrations/overview#what-notification-integrations-send).
  </Step>

  <Step title="Connect">
    Select **Connect**. OASM verifies the bot token with Telegram before saving the integration.
  </Step>
</Steps>

<Info>
  Connecting the bot does not deliver alerts yet. Each recipient must pair their Telegram account first.
</Info>

## Pair a Telegram account

Pairing is per user. Anyone in the workspace can pair their own Telegram account to the same integration.

<Steps>
  <Step title="Open the integration">
    In the **Connected** tab, select the Telegram integration.
  </Step>

  <Step title="Open the pairing dialog">
    In the **Telegram Pairing** section, select **Pair**.
  </Step>

  <Step title="Generate a pairing token">
    Select **Generate Pairing Token**. OASM creates a one-time token valid for **10 minutes**.
  </Step>

  <Step title="Open the bot">
    Scan the QR code with your phone, or select **Open Telegram** to open the bot with the token already attached.
  </Step>

  <Step title="Send the token">
    If you opened the bot manually, send `/start <token>`. The dialog switches to **Connected** when Telegram confirms the chat.
  </Step>
</Steps>

<Accordion title="The token expired">
  Pairing tokens are valid for 10 minutes. Select **Generate New Token** and try again.
</Accordion>

<Accordion title="I already receive alerts on this chat">
  A Telegram chat can pair once per integration. To move it, disconnect the existing device first.
</Accordion>

## Manage paired accounts

The **Telegram Pairing** section lists every connected chat. To remove one, select the **unplug** icon next to it and confirm. OASM sends a final message to that chat and stops delivering to it.

<Info>
  In a production deployment, OASM registers a Telegram webhook for the bot automatically. In local development, it uses long polling instead. You do not choose between these — the deployment decides.
</Info>

## Test

Open the integration and select **Test Integration**. OASM sends a test message to every paired chat. If no chat receives it, confirm at least one account is paired and the bot token is still valid.

## Related

<Card icon="bell" title="Notifications" horizontal href="/notifications">
  See every event the platform produces
</Card>

<Card icon="slack" title="Slack" horizontal href="/integrations/slack">
  Send alerts to a Slack channel instead
</Card>

<Card icon="plug" title="Integrations overview" horizontal href="/integrations/overview">
  Learn how events, secrets, and connections work
</Card>


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