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",
});
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: +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 |
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.
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 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