Telegram

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 account
Access to @BotFather to create a bot and obtain its token
Access to the Novu dashboard

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, 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 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
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 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
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 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
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 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

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 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 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
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 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
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 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
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 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. 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 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

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) 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.

<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>