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

TypeScript

const result = await zavu.messages.send({
  to: "123456789", // Telegram chat ID
  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, but you’ll be charged for MAU (Monthly Active Users) 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:  [phone]
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:

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":

TypeScript

const result = await zavu.messages.send({
  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:

1. Create a bot via @BotFather
2. Get your bot token
3. 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 [phone]
• 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