> ## Documentation Index
> Fetch the complete documentation index at: https://novu-c5de82d9-docs-homepage-redesign.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Use the Telegram provider in Novu for chat notifications and two-way agent conversations. Create a bot, store the token, and route messages through workflows.

The Telegram chat integration lets your application send messages to subscribers through a Telegram bot. Each subscriber connects their Telegram chat to Novu once; after that, Novu can deliver workflow notifications or agent replies to that chat.

<Note>
  Check out the [agents](/agents) documentation to build conversational agents on Telegram. Users message your bot in Telegram and your agent replies in the same chat.
</Note>

## Prerequisites

* A [Telegram](https://telegram.org/) account
* Access to [@BotFather](https://t.me/botfather) to create a bot and obtain its token
* Access to the [Novu dashboard](https://dashboard.novu.co)

## Create a Telegram bot

Every Telegram integration uses one bot. Create it with BotFather before adding the provider in Novu.

<Steps>
  <Step title="Open BotFather">
    Open [@BotFather](https://t.me/botfather) in Telegram (mobile or desktop).
  </Step>

  <Step title="Run /newbot">
    Send the `/newbot` command and follow the prompts to choose a **display name** and a **username** (must end in `bot`, for example `acme_alerts_bot`).
  </Step>

  <Step title="Copy the confirmation message">
    BotFather replies with a confirmation message that includes your bot token, for example:

    ```
    1234567890:AAFdT8_…
    ```

    Copy the full message — Novu can extract the token automatically when you paste it into the dashboard.
  </Step>
</Steps>

<Warning>
  Treat the bot token like a password. Store it only in Novu or on your server. Never embed it in client-side code.
</Warning>

## Configure Telegram in Novu

<Steps>
  <Step title="Open the Integrations Store">
    In the Novu dashboard, click **Integrations Store** in the sidebar.
  </Step>

  <Step title="Add Telegram">
    Click **Connect Provider**, select **Chat**, then choose **Telegram**.
  </Step>

  <Step title="Save the bot token">
    Paste the full BotFather confirmation message into the credentials form, or paste the token directly into the **API Token** field.

    On mobile, scan the QR code in the form to open a setup page and paste the BotFather message from the device where you received it.
  </Step>

  <Step title="Create the integration">
    Review your credentials, then click **Create Integration** to save.
  </Step>
</Steps>

If you add Telegram to an [agent](/agents), the dashboard also walks you through connecting your bot and sending a test message.

## Connect a subscriber's Telegram chat

Before Novu can deliver messages, each subscriber must connect their Telegram chat.

### Connection link (recommended)

Novu gives you a link that opens your bot in Telegram. When the subscriber taps **Start**, their chat is linked to their Novu subscriber profile.

<Note>
  The connection link flow is available when Telegram is set up on an agent. If you only need one-way workflow notifications and already know a subscriber's Telegram chat ID, you can register it with the [channel endpoints API](/api-reference/channel-endpoints/create-a-channel-endpoint) instead.
</Note>

#### From your backend

Request a connection URL from your server when the subscriber chooses to connect Telegram:

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    import { Novu } from '@novu/api';

    const novu = new Novu({ secretKey: '<NOVU_SECRET_KEY>' });

    const response = await novu.integrations.linkChannelEndpoint({
      integrationIdentifier: 'telegram',
      subscriberId: '<SUBSCRIBER_ID>',
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from novu_py import Novu

    with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
        response = novu.integrations.link_channel_endpoint(link_channel_endpoint_request_dto={
            "integration_identifier": "telegram",
            "subscriber_id": "<SUBSCRIBER_ID>",
        })
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import (
        "context"
        "os"

        novugo "github.com/novuhq/novu-go"
        "github.com/novuhq/novu-go/models/components"
    )

    s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

    res, err := s.Integrations.LinkChannelEndpoint(context.Background(), components.LinkChannelEndpointRequestDto{
        IntegrationIdentifier: "telegram",
        SubscriberID: "<SUBSCRIBER_ID>",
    }, nil)
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use novu;
    use novu\Models\Components;

    $sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();
    $response = $sdk->integrations->linkChannelEndpoint(
        linkChannelEndpointRequestDto: new Components\LinkChannelEndpointRequestDto(
            integrationIdentifier: 'telegram',
            subscriberId: '<SUBSCRIBER_ID>',
        ),
    );
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using Novu;
    using Novu.Models.Components;

    var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");
    var response = await sdk.Integrations.LinkChannelEndpointAsync(
        linkChannelEndpointRequestDto: new LinkChannelEndpointRequestDto() {
            IntegrationIdentifier = "telegram",
            SubscriberId = "<SUBSCRIBER_ID>",
        });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import co.novu.Novu;
    import co.novu.models.components.*;

    Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();
    var response = novu.integrations().linkChannelEndpoint()
        .body(LinkChannelEndpointRequestDto.builder()
            .integrationIdentifier("telegram")
            .subscriberId("<SUBSCRIBER_ID>")
            .build())
        .call();
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -L -X POST 'https://api.novu.co/v1/integrations/channel-endpoints/link' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "integrationIdentifier": "telegram",
      "subscriberId": "<SUBSCRIBER_ID>"
    }'
    ```
  </Tab>
</Tabs>

Open the returned `url` in a new tab or show it as a button in your UI. Generate a fresh link each time the subscriber starts the flow — links expire after a short time.

#### From your app with `@novu/react`

For agent applications, use `TelegramConnectButton` inside `NovuProvider`. It opens Telegram for the subscriber and confirms when the chat is connected.

```tsx theme={null}
import { NovuProvider, TelegramConnectButton } from '@novu/react';

function ConnectTelegram() {
  return (
    <NovuProvider subscriberId="user-123" applicationIdentifier="your-app-id">
      <TelegramConnectButton
        integrationIdentifier="telegram"
        connectLabel="Connect Telegram"
        connectedLabel="Connected to Telegram"
        onConnectSuccess={() => {
          console.log('Telegram connected');
        }}
      />
    </NovuProvider>
  );
}
```

See the [connect components](/agents/custom-code-agent/setup-your-agent/connect-components#telegram-connect-button) guide for the full props reference.

## Send chat workflow notifications

Once subscribers have connected Telegram, add a **Chat** step to a workflow and trigger it as usual.

<Steps>
  <Step title="Add a Chat step">
    In the Novu dashboard, open your workflow, add a step, and select **Chat** as the channel.
  </Step>

  <Step title="Write the message body">
    Compose the message content. Use dynamic placeholders such as `{{subscriber.firstName}}` or payload variables from your trigger.
  </Step>

  <Step title="Trigger the workflow">
    Send a test trigger for a subscriber who has connected Telegram.
  </Step>
</Steps>

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    import { Novu } from '@novu/api';

    const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

    await novu.trigger({
      workflowId: "order-shipped",
      to: { subscriberId: "user-123", },
      payload: {
        "orderNumber": "ORD-12345",
        "trackingUrl": "https://acme.com/track/123"
    },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import novu_py
    from novu_py import Novu

    with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
        novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
            workflow_id="order-shipped",
            to={"subscriber_id": "user-123"},
            payload={
            "orderNumber": "ORD-12345",
            "trackingUrl": "https://acme.com/track/123"
    },
        ))
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import (
        "context"
        "os"

        novugo "github.com/novuhq/novu-go"
        "github.com/novuhq/novu-go/models/components"
    )

    s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

    res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
        WorkflowID: "order-shipped",
        To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
            SubscriberID: "user-123",
        }),
        Payload: map[string]any{
        "orderNumber": "ORD-12345",
        "trackingUrl": "https://acme.com/track/123"
    },
    }, nil)
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use novu;
    use novu\Models\Components;

    $sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

    $sdk->trigger(
        triggerEventRequestDto: new Components\TriggerEventRequestDto(
            workflowId: 'order-shipped',
            to: new Components\SubscriberPayloadDto(subscriberId: 'user-123'),
            payload: {
            "orderNumber": "ORD-12345",
            "trackingUrl": "https://acme.com/track/123"
    },
        ),
    );
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using Novu;
    using Novu.Models.Components;

    var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

    await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
        WorkflowId = "order-shipped",
        To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "user-123" }),
        Payload = {
        "orderNumber": "ORD-12345",
        "trackingUrl": "https://acme.com/track/123"
    },
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import co.novu.Novu;
    import co.novu.models.components.*;

    Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

    novu.trigger()
        .body(TriggerEventRequestDto.builder()
            .workflowId("order-shipped")
            .to(To2.of(SubscriberPayloadDto.builder().subscriberId("user-123").build()))
            .payload({
            "orderNumber": "ORD-12345",
            "trackingUrl": "https://acme.com/track/123"
    })
            .build())
        .call();
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl --location 'https://api.novu.co/v1/events/trigger' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "order-shipped",
        "to": [
            "user-123"
        ],
        "payload": {
            "orderNumber": "ORD-12345",
            "trackingUrl": "https://acme.com/track/123"
        }
    }'
    ```
  </Tab>
</Tabs>

Novu finds the subscriber's linked Telegram chat, renders the message, and sends it through your bot. Verify delivery in **Activity** or in Telegram.

## Using Telegram with agents

Telegram is a supported [agent provider](/agents/get-started/agents-and-providers). Connect your bot to an agent so users can message the bot and get replies in the same chat — without building Telegram integrations yourself.

<Card title="Build agents on Telegram" icon="bot" href="/agents">
  Learn how Novu agents work, including managed and custom code agents.
</Card>

### What you get

When Telegram is connected to an agent:

* Users message your bot in Telegram and your agent responds in that chat
* Conversations appear in the dashboard under **Agent Conversations**
* Supported content includes text, markdown, files, reactions, and typing indicators

See [agent conversations](/agents/conversations#supported-platforms) for capabilities across all providers.

### Set up Telegram for an agent

<Steps>
  <Step title="Create or open an agent">
    In the Novu dashboard, go to **Agents** and create an agent or open an existing one.
  </Step>

  <Step title="Add Telegram as a provider">
    Add **Telegram** as a provider. Novu creates the integration and links it to your agent.
  </Step>

  <Step title="Save the bot token">
    Follow the setup guide in the dashboard: create a bot with BotFather, paste the confirmation message (or use the mobile QR setup page), and save your credentials.
  </Step>

  <Step title="Connect a test chat">
    Open the connection link (or scan the QR code) and tap **Start** in Telegram.
  </Step>

  <Step title="Send a test message">
    Message your bot in Telegram and confirm your agent replies.
  </Step>
</Steps>

You can also use the CLI:

```bash theme={null}
npx novu@latest connect
```

Select your agent and Telegram when prompted. The CLI guides you through bot setup, token entry, and a test message.

### Let your users connect Telegram in your app

Add `TelegramConnectButton` to your app (see [Connect a subscriber's Telegram chat](#connect-a-subscribers-telegram-chat)) or request a connection URL from your backend and send users to that link.

After a chat is connected, messages to your bot are handled by your agent. Replies show up in the same Telegram chat.

### Agent conversations vs. workflow notifications

| Use case                  | What happens                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Agent conversation**    | The user messages your bot and your agent replies in the same chat.                                       |
| **Workflow notification** | You trigger a workflow with a Chat step and Novu sends a one-way message to the subscriber's linked chat. |

Both can use the same bot and the same connected chat. Your agent can handle back-and-forth conversations while workflows send updates such as order confirmations to the same subscriber.

## Related

<Columns cols={2}>
  <Card icon="plus" href="/platform/integrations/chat/adding-chat" title="Adding a chat channel">
    General steps for enabling the Chat channel and wiring it into workflows.
  </Card>

  <Card icon="code" href="/agents/custom-code-agent/setup-your-agent/connect-components" title="Connect components">
    Prebuilt React buttons for Slack, Teams, Telegram, and more.
  </Card>
</Columns>