Skip to main content
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.
Check out the agents documentation to build conversational agents on Telegram. Users message your bot in Telegram and your agent replies in the same chat.

​
Prerequisites

​
Create a Telegram bot

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

Open BotFather

Open @BotFather in Telegram (mobile or desktop).
2

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

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.
Treat the bot token like a password. Store it only in Novu or on your server. Never embed it in client-side code.

​
Configure Telegram in Novu

1

Open the Integrations Store

In the Novu dashboard, click Integrations Store in the sidebar.
2

Add Telegram

Click Connect Provider, select Chat, then choose Telegram.
3

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

Create the integration

Click Create Integration.
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. 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.
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 instead.

​
From your backend

Request a connection URL from your server when the subscriber chooses to connect Telegram: 
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>"
}'
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. 
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.
1

Add a Chat step

In the Novu dashboard, open your workflow, add a step, and select Chat as the channel.
2

Write the message body

Compose the message content. Use dynamic placeholders such as {{subscriber.firstName}} or payload variables from your trigger.
3

Trigger the workflow

Trigger the workflow for a subscriber who has connected Telegram.
import { Novu } from '@novu/api';

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

await novu.trigger({
  workflowId: 'order-shipped',
  to: { subscriberId: 'user-123' },
  payload: {
    orderNumber: 'ORD-12345',
    trackingUrl: 'https://acme.com/track/123',
  },
});
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.

Build agents on Telegram

Learn how Novu agents work, including managed and custom code agents.

​
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

1

Create or open an agent

In the Novu dashboard, go to Agents and create an agent or open an existing one.
2

Add Telegram as a provider

Add Telegram as a provider. Novu creates the integration and links it to your agent.
3

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

Connect a test chat

Open the connection link (or scan the QR code) and tap Start in Telegram.
5

Send a test message

Message your bot in Telegram and confirm your agent replies.
You can also use the CLI: 
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 caseWhat happens
Agent conversationThe user messages your bot and your agent replies in the same chat.
Workflow notificationYou 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.

Adding a chat channel

General steps for enabling the Chat channel and wiring it into workflows.

Connect components

Prebuilt React buttons for Slack, Teams, Telegram, and more.