For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

  1. Go to Workspace SettingsConnectionsNew Connection.

  2. Select Telegram.

  3. Enter a name and the bot token.

  4. Save the connection.

  5. Wait for the webhook setup to finish.

  6. Create a Channel linked to that connection.

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