> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Overview

> Bot messaging with powerful automation capabilities

Telegram Bot API enables messaging through bots, offering powerful automation capabilities and rich message formatting.

## When to Use Telegram

* **Customer support bots**: Automated responses and human handoff
* **Notifications**: Real-time alerts and updates
* **Communities**: Group messaging and channel broadcasts
* **Automation**: Bot commands and workflows

## Basic Telegram Message

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.send({
    to: "123456789", // Telegram chat ID
    text: "Hello from Zavu!",
    channel: "telegram",
  });
  ```

  ```python Python theme={null}
  result = zavu.messages.send(
      to="123456789",  # Telegram chat ID
      text="Hello from Zavu!",
      channel="telegram"
  )
  ```

  ```ruby Ruby theme={null}
  result = client.messages.send(
    to: "123456789", # Telegram chat ID
    text: "Hello from Zavu!",
    channel: "telegram"
  )
  ```

  ```go Go theme={null}
  result, _ := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  	To:      zavudev.String("123456789"), // Telegram chat ID
  	Text:    zavudev.String("Hello from Zavu!"),
  	Channel: zavudev.String("telegram"),
  })
  ```

  ```php PHP theme={null}
  $result = $client->messages->send([
      'to' => '123456789', // Telegram chat ID
      'text' => 'Hello from Zavu!',
      'channel' => 'telegram',
  ]);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/messages \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "123456789",
      "text": "Hello from Zavu!",
      "channel": "telegram"
    }'
  ```
</CodeGroup>

## Key Differences from Other Channels

| Feature          | Telegram          | SMS           | WhatsApp         |
| ---------------- | ----------------- | ------------- | ---------------- |
| Recipient ID     | Chat ID (numeric) | Phone number  | Phone number     |
| Media support    | Yes               | Limited (MMS) | Yes              |
| Cost per message | Free\*            | Per message   | Per conversation |
| Bots required    | Yes               | No            | No               |

<Note>
  \*Telegram messaging is free, but you'll be charged for MAU (Monthly Active Users) as with other channels.
</Note>

## Chat IDs vs Phone Numbers

Unlike SMS and WhatsApp, Telegram uses numeric chat IDs rather than phone numbers:

```
Phone-based channels:  +14155551234
Telegram:              123456789
```

<Warning>
  You cannot message Telegram users by phone number. Users must first interact with your bot to establish a chat ID.
</Warning>

## Getting Chat IDs

Chat IDs are obtained when users interact with your bot:

1. User sends a message to your bot
2. Zavu receives the message via webhook
3. The `from` field contains the user's chat ID
4. Store and use this ID for future messages

## Message Types

Telegram supports various message types:

| Type     | Use Case                              |
| -------- | ------------------------------------- |
| Text     | Simple messages with markdown support |
| Photo    | Images and graphics                   |
| Document | Files and attachments                 |
| Location | Share locations                       |
| Contact  | Share contact information             |

## Sending Templates on Telegram

You can send pre-defined templates on Telegram by specifying `channel: "telegram"` and `messageType: "template"`:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.send({
    to: "123456789",
    channel: "telegram",
    messageType: "template",
    content: {
      templateId: "tpl_abc123",
      templateVariables: {
        "1": "John",
        "2": "ORD-12345",
      },
    },
  });
  ```

  ```python Python theme={null}
  result = zavu.messages.send(
      to="123456789",
      channel="telegram",
      message_type="template",
      content={
          "templateId": "tpl_abc123",
          "templateVariables": {
              "1": "John",
              "2": "ORD-12345"
          }
      }
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/messages \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "123456789",
      "channel": "telegram",
      "messageType": "template",
      "content": {
        "templateId": "tpl_abc123",
        "templateVariables": { "1": "John", "2": "ORD-12345" }
      }
    }'
  ```
</CodeGroup>

If the template has a `telegramBody`, it will be used instead of the default `body`. Contact variables like `{{contact.first_name}}` are automatically resolved from the recipient's contact metadata.

<Info>
  Telegram templates do not require external approval like WhatsApp. You can create and use them immediately.
</Info>

## Delivery Status

Telegram provides delivery tracking:

| Status      | Description                   |
| ----------- | ----------------------------- |
| `queued`    | Message accepted by Zavu      |
| `sending`   | Being sent to Telegram        |
| `delivered` | Delivered to Telegram servers |
| `failed`    | Delivery failed               |

<Note>
  Telegram doesn't provide read receipts like WhatsApp. You'll know the message was delivered, but not if it was read.
</Note>

## Bot Setup Requirements

Before sending Telegram messages, you need to:

1. Create a bot via [@BotFather](https://t.me/BotFather)
2. Get your bot token
3. Configure the bot in your Zavu sender settings

See [Telegram Setup](/guides/telegram/setup) for detailed instructions.

## Common Errors

| Error                       | Cause                  | Solution                       |
| --------------------------- | ---------------------- | ------------------------------ |
| `Bot token invalid`         | Wrong or expired token | Regenerate token via BotFather |
| `Chat not found`            | Invalid chat ID        | Verify the chat ID             |
| `Bot blocked by user`       | User blocked your bot  | Cannot message this user       |
| `Forbidden: bot was kicked` | Bot removed from group | Bot must be re-added           |

## Limitations

Before choosing Telegram as your messaging channel, consider these limitations:

### User Initiation Required

<Warning>
  Your bot cannot message users first. Users must send a message to your bot before you can reply or send notifications.
</Warning>

This is a fundamental Telegram restriction. Unlike SMS or Email, you cannot "cold message" Telegram users. Build your flow so users initiate contact (e.g., via a "Message us on Telegram" button on your website).

### No Phone Number Messaging

You cannot reach users by phone number. Telegram uses internal chat IDs:

* **SMS/WhatsApp**: Send to `+14155551234`
* **Telegram**: Send to `123456789` (chat ID)

If you only have a user's phone number, you cannot message them on Telegram even if they have the app installed.

### No Read Receipts

Telegram does not provide read receipts. You'll know:

* Message was delivered to Telegram servers
* Message failed to deliver

You will **not** know:

* If the user read the message
* When the user read the message

### Rate Limits

Telegram enforces rate limits on bot messages:

| Scope                   | Limit                    |
| ----------------------- | ------------------------ |
| Same chat               | \~1 message per second   |
| Different chats         | \~30 messages per second |
| Broadcast to many users | May require delays       |

<Note>
  Zavu handles rate limiting automatically, but large broadcasts may take longer to complete on Telegram compared to other channels.
</Note>

### No Pre-Approved Templates

Unlike WhatsApp, Telegram has no template approval system. This means:

* **Pro**: Send any message content without approval
* **Con**: No way to message users outside of an active conversation

### Media Limitations

| Media Type | Max Size |
| ---------- | -------- |
| Photos     | 10 MB    |
| Documents  | 50 MB    |
| Video      | 50 MB    |
| Audio      | 50 MB    |

### Group Limitations

* Bot must be added to the group by an admin
* Bot can be kicked or restricted by group admins
* In supergroups (>200 members), bot may need admin privileges to see all messages

### Bot Blocking

Users can block your bot at any time. When blocked:

* You cannot send messages to that user
* You receive a `bot_blocked_by_user` error
* There's no way to "unblock" programmatically

### No Fallback to Other Channels

Unlike SMS/WhatsApp where numbers are portable, Telegram chat IDs are specific to Telegram. You cannot automatically fall back to SMS if Telegram fails, unless you have the user's phone number stored separately.

### Geographic Availability

Telegram may be blocked or restricted in some countries (e.g., China, Iran at times). Consider your user base's location when choosing Telegram as a primary channel.

## Next Steps

* [Telegram Setup](/guides/telegram/setup) - Configure your Telegram bot