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

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

Key Differences from Other Channels

Chat IDs vs Phone Numbers

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

CodeCopy
Phone-based channels:  +14155551234
Telegram:              123456789

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:

Quoted Replies

To answer a specific message, set content.replyToMessageId to its Zavu ID, such as the data.messageId of a message.inbound webhook. Telegram shows the quoted message above your reply.

TypeScriptcURLCopy
const result = await zavu.messages.send({
  to: "123456789",
  channel: "telegram",
  text: "Got it, checking now.",
  content: { replyToMessageId: "msg_abc123" },
});

The quoted message must be in the same chat as to and must belong to the same bot you send from. Telegram numbers messages per chat, so a message from another chat or bot is refused with 400 and is never sent unquoted. A button tap is not a message: the inbound created when a contact taps an inline button (data.isCallbackQuery: true on its message.inbound) cannot be quoted, so quote the message that carried the button instead. When answering from a webhook, send to data.telegramChatId: data.from carries a telegram: prefix that to does not accept. Inbound Telegram messages do not report what the contact quoted yet. The replyTo* fields of message.inbound are filled in on WhatsApp only.

Sending Templates on Telegram

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

TypeScriptcURLCopy
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.

Delivery Status

Telegram provides delivery tracking:

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

Limitations

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

User Initiation Required

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:

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

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