Telegram Overview

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

const result = await zavu.messages.send({
  to: "123456789", // Telegram chat ID
  text: "Hello from Zavu!",
  channel: "telegram",
});

result = zavu.messages.send(
    to="123456789",  # Telegram chat ID
    text="Hello from Zavu!",
    channel="telegram"
)

result = client.messages.send(
  to: "123456789", # Telegram chat ID
  text: "Hello from Zavu!",
  channel: "telegram"
)

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"),
})

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

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"
  }'

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

*Telegram messaging is free. Messages count toward your plan’s monthly message limits, with usage-based overage beyond them, as with other channels.

Chat IDs vs Phone Numbers

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

Phone-based channels:  +14155551234
Telegram:              123456789

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

Getting Chat IDs

Chat IDs are obtained when users interact with your bot:

User sends a message to your bot
Zavu receives the message via webhook
The from field contains the user’s chat ID
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":

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

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

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" }
    }
  }'

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.

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

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

Telegram doesn’t provide read receipts like WhatsApp. You’ll know the message was delivered, but not if it was read.

Bot Setup Requirements

Before sending Telegram messages, you need to:

Create a bot via @BotFather
Get your bot token
Configure the bot in your Zavu sender settings

See 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

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

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

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

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 - Configure your Telegram bot

Getting Started

Concepts

Guides

Telegram Overview

When to Use Telegram

Basic Telegram Message

Key Differences from Other Channels

Chat IDs vs Phone Numbers

Getting Chat IDs

Message Types

Sending Templates on Telegram

Delivery Status

Bot Setup Requirements

Common Errors

Limitations

User Initiation Required

No Phone Number Messaging

No Read Receipts

Rate Limits

No Pre-Approved Templates

Media Limitations

Group Limitations

Bot Blocking

No Fallback to Other Channels

Geographic Availability

Next Steps

​When to Use Telegram

​Basic Telegram Message

​Key Differences from Other Channels

​Chat IDs vs Phone Numbers

​Getting Chat IDs

​Message Types

​Sending Templates on Telegram

​Delivery Status

​Bot Setup Requirements

​Common Errors

​Limitations

​User Initiation Required

​No Phone Number Messaging

​No Read Receipts

​Rate Limits

​No Pre-Approved Templates

​Media Limitations

​Group Limitations

​Bot Blocking

​No Fallback to Other Channels

​Geographic Availability

​Next Steps

When to Use Telegram

Basic Telegram Message

Key Differences from Other Channels

Chat IDs vs Phone Numbers

Getting Chat IDs

Message Types

Sending Templates on Telegram

Delivery Status

Bot Setup Requirements

Common Errors

Limitations

User Initiation Required

No Phone Number Messaging

No Read Receipts

Rate Limits

No Pre-Approved Templates

Media Limitations

Group Limitations

Bot Blocking

No Fallback to Other Channels

Geographic Availability

Next Steps