Telegram
Connect a Telegram bot to handle private 1:1 conversations with text, images, audio, and PDFs.
The Telegram channel lets your Agent handle 1:1 conversations through a Telegram bot.
Use it when you need inbound and outbound support on Telegram with text, images, audio, and PDF files.
Connection requirements
Before the channel can work, you need a Telegram bot token.
Zaia validates the token before saving the connection.
The connection only activates when:
The token belongs to a valid Telegram bot
The bot is not already active in another Telegram connection
The webhook is configured successfully
If webhook setup fails, the connection stays in failed status and does not activate.
Connection flow
Go to Workspace Settings → Connections → New Connection.
Select Telegram.
Enter a name and the bot token.
Save the connection.
Wait for the webhook setup to finish.
Create a Channel linked to that connection.
Assign an Agent or Squad.
Once both the connection and channel are active, Zaia can exchange messages with Telegram users.
Supported conversation scope
Telegram support is limited to private chats.
Zaia processes messages sent directly to the bot by an individual user.
Zaia ignores messages from:
Groups
Supergroups
Channels
On the first valid message from a user, Zaia creates the external user and the conversation automatically if they do not exist yet.
Zaia also prevents duplicate processing of the same Telegram message.
Supported message types
Incoming from Telegram
Zaia can receive:
Text
Image
Audio / voice
PDF document
Outgoing to Telegram
Zaia can send:
Text
Image
Audio
PDF document
Media behavior
Images
If the user sends an image with a caption, Zaia stores the caption as the message text.
If Telegram sends multiple versions of the same image, Zaia uses the largest one.
When Zaia sends a reply with one image and text up to 1024 characters, the text is sent as the image caption.
If the reply includes longer text or another media combination, the text is sent separately from the media.
Documents
Document handling is implemented for PDF files.
Other document types are not part of the current Telegram scope.
Audio
When the user sends audio or voice, Zaia downloads the file and normalizes it to WAV for internal processing.
Long message behavior
Telegram has a technical limit for text length.
Zaia always respects that limit and splits oversized replies automatically.
You can also enable Split long messages on the channel.
When enabled, long responses are intentionally broken into smaller Telegram messages before delivery.
Important limitations
Telegram uses a bot token. It does not support user login.
The channel only works when the linked connection is active.
Public channel sharing is disabled for Telegram in the web app.
Manual takeover by reaction is not available for Telegram.
The Telegram-specific channel option is Split long messages.
Best-fit use cases
Telegram works best for:
1:1 support conversations
File and media exchange during support
Agent flows that react to user text, images, audio, or PDFs
It is not designed for community moderation or group mention workflows.
Current scope vs planned ideas
Some earlier planning considered replying inside groups or communities when the bot was mentioned.
That behavior is not part of the current implementation.
Only private chat messages are processed.
Troubleshooting
Connection does not activate Check whether the token belongs to a bot and whether the bot is already active in another connection.
Connection enters failed status right after creation Webhook setup likely failed. Recheck the token and try reconnecting.
Messages do not appear in Zaia Make sure the message came from a private chat and that both the connection and channel are active.
Last updated