> For the complete documentation index, see [llms.txt](https://docs.zaia.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaia.app/channels/channel-types/telegram.md).

# Telegram

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 Settings** → **Connections** → **New 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.