Telegram Integration | Botpress Hub

The Telegram integration allows Botpress chatbots and AI agents to communicate with users on Telegram through the official Telegram Bot API. It enables two-way real-time messaging, supporting text, media, buttons, and interactive commands within private chats or groups.

Under the hood, the integration uses Telegraf—a robust Node.js framework—to manage message routing, commands, and events from Telegram. Messages sent by your AI agent are automatically formatted from Markdown into Telegram’s supported HTML syntax, ensuring perfect rendering of text, links, and formatting.

With built-in utilities for message sanitization and typing indicators, this integration ensures clean, secure, and responsive communication experiences for end users. Developers can use it to automate updates, handle tickets, or extend their chatbots into Telegram communities with minimal setup.

The Telegram integration allows your AI-powered chatbot to seamlessly interact with Telegram, a popular messaging platform with a large user base. Connect your chatbot to Telegram and engage with your audience in real-time conversations. With this integration, you can automate customer support, provide personalized recommendations, send notifications, and handle inquiries directly within Telegram. Leverage Telegram's rich features, including text messages, inline buttons, media files, and more, to create dynamic and interactive chatbot experiences. Empower your chatbot to deliver exceptional user experiences on Telegram with the Telegram Integration for Botpress.

## Migrating from version `0.x.x` to `1.x.x`

### Removal of proactive conversations (and proactive users)

- Telegram does not currently support proactive conversations, so any bots using this feature will need to be updated to use the normal conversation flow.

### Removal of dedicated Markdown messages type

- The `markdown` channel message type is being deprecated in favor of integrating this behavior into the base `text` message type.
- This new Markdown behavior (commonmark spec) will allow image Markdown. However, since Telegram does not support mixed message types, it will split the message into multiple messages with images sent in between text messages.

### Addition of message limits

- Telegram has a message length limit of 4096 characters, so that limit has been added to the text parameter in the `text` message payload. Going over this limit will result in the message being rejected.

FAQs

What is the Botpress Telegram integration and how does it work?

The Botpress Telegram integration connects a Botpress chatbot or AI agent to the official Telegram Bot API so conversations can run natively inside Telegram chats. Behind the scenes, the integration uses the Botpress SDK along with the Telegraf framework to receive updates from Telegram and send responses back in real time. Incoming Telegram messages are normalized into Botpress events so the agent can apply policies, knowledge retrieval, and workflows just like on any other channel. Outgoing messages are converted from Botpress’ internal message format into Telegram-compatible payloads, including support for text, inline buttons, and media where appropriate. Once configured with a Bot Token and Webhook URL, the integration handles the low-level API calls and retries, so teams focus on designing conversations, not wiring up HTTP requests.

How is the Telegram integration set up in Botpress from end to end?

Setting up the integration starts in Telegram itself by creating a bot through BotFather, which generates a Bot Token for accessing the Telegram Bot API. In Botpress Studio, the Telegram integration is installed from the Hub, then configured with this Bot Token in the integration settings. The configuration screen exposes a simple set of options such as Enabled (to toggle communication), Webhook URL (where Telegram sends updates), and the token field that authorizes the integration. Once saved, Botpress registers the webhook and begins listening for new updates so any message sent to the Telegram bot appears as a conversation event in the Botpress project. From that point forward, flows, policies, and AI agents operate on Telegram conversations exactly as they do on webchat or other channels, giving a consistent architecture across the stack.

Which features and message types does the Telegram integration support for chatbots and AI agents?

The Telegram integration supports standard text messages along with many of the rich features Telegram is known for, such as inline buttons and media attachments. Messages produced by a Botpress AI agent are mapped into Telegram’s message types so they can include interactive buttons, quick reply–style flows, and links that follow Telegram’s formatting rules. Typing indicators are available through integration-specific Cards, allowing a bot to signal that it is composing a response and create a more natural chat experience for end users. The integration also exposes tags on conversations and users, such as a Telegram conversation ID or user ID, so advanced builders can correlate Telegram identities with CRM records or internal systems. Together, these capabilities make the Telegram integration suitable for customer support, proactive-style notifications (within Telegram’s limitations), community management, and automated information retrieval scenarios.

How does the Botpress Telegram integration handle Markdown, HTML, and message formatting safely?

Telegram supports specific formatting modes such as HTML and Markdown, but it is strict about which tags and characters are allowed. To deliver reliably formatted content, the integration uses a Markdown processing pipeline based on markdown-it to transform Botpress content into Telegram-compatible HTML, and relies on sanitize-html to strip or escape unsafe tags and attributes before sending. This approach ensures that headings, bold text, links, and lists render correctly without breaking messages or exposing users to untrusted HTML. On top of that, the integration follows Telegram’s constraints around mixed content and message length, splitting text and images into multiple messages where necessary so complex content from an AI agent still appears cleanly in the Telegram client. As a result, teams can design rich, Markdown-based content in Botpress while the integration takes care of all the Telegram-specific formatting edge cases in the background.

What are common use cases for running a Botpress chatbot or AI agent on Telegram?

A Telegram-connected AI agent is typically used for customer support, community engagement, or transactional messaging in channels where Telegram already has a strong user base. Many teams use the integration to provide instant self-service support, FAQ automation, and ticket triage directly in Telegram chats, reducing the need for separate web portals or mobile apps. Others rely on it to send order updates, account notifications, or product announcements to subscribers who prefer Telegram as a primary communication channel. Because Telegram supports groups and supergroups, the integration is also effective for moderating communities, routing complex questions to human agents via Botpress policies, and capturing feedback from power users in real time. Combined with Botpress features like knowledge retrieval, policies, and human-in-the-loop, the Telegram integration becomes a flexible entry point for any organization that wants to bring its chatbot or AI agent into an existing Telegram audience.

Maintained by

Botpress Team

Telegram

FAQs

Explore popular integrations