Skip to main content
The Telegram channel uses the Telegram bot API. You create a bot through BotFather (Telegram’s official bot for managing other bots), copy the generated token, and paste it into Timely.ai. The platform configures the webhook automatically.

​
Prerequisites

  • A Telegram account (personal or team)
  • Access to BotFather on Telegram to create the bot and obtain the token
  • An Agent created and active in Timely.ai
Unlike WhatsApp and Instagram, Telegram does not require a verified business account or third-party approval. Any Telegram account can create a bot.

​
Step-by-step connection

1

Create a bot in BotFather

Open Telegram and search for @BotFather. Start a conversation and send the command:
/newbot
BotFather will ask for:
  1. Bot name — a friendly name that appears in conversations (e.g., “Timely Support”)
  2. Bot username — must end in bot (e.g., timely_support_bot)
At the end, BotFather displays the access token in the format:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
Copy this token — you will need it in the next step.
Treat the bot token like a password. Anyone with access to the token can send messages on behalf of your bot. Do not share it in public repositories or logs.
2

Go to Channels in the Dashboard

In the Timely.ai sidebar, go to Channels → Add channel and select Telegram.
3

Paste the token and connect

Enter the bot token in the corresponding field. The token must be in the number:string format (e.g., 123456789:ABCdef...). Timely.ai validates the token with the Telegram API before proceeding.
Telegram bot configuration screen
4

Webhook configured automatically

Upon confirming the valid token, Timely.ai:
  1. Calls setWebhook on the Telegram API pointing to https://[YOUR-SUPABASE].supabase.co/functions/v1/telegram-webhook
  2. Generates a random webhook secret to validate requests
  3. Saves the integration in the database with the bot information (bot_id, bot_username, bot_name)
You do not need to configure anything manually in Telegram.
5

Link to the Agent

Select the Agent that will handle Telegram Conversations. One Telegram integration corresponds to one bot and one Agent.
You can create multiple bots (each with its own token) and link them to different Agents — useful for separating technical support, sales, and community into distinct bots.
6

Test the bot

Open Telegram, search for your bot’s username (e.g., @timely_support_bot) and send a message. The Agent should respond within 2 seconds.

​
Supported features

​
Media types

TypeReceiveSend
TextYesYes
Image (JPG, PNG, WebP)YesYes
Document (PDF, DOCX, etc.)YesYes
Audio / Voice messageYes—
VideoYes—
StickerYes—
LocationYes—

​
Bot commands

Telegram allows users to send slash commands (e.g., /start, /help). You can register commands in BotFather with /setcommands and the Agent treats those commands as regular text messages — the Agent’s prompt should describe how to respond to each one.

​
Groups and supergroups

By default, the bot only responds to direct messages (DMs). To enable responses in groups:
  1. In BotFather, send /setjoingroups and select Enable
  2. Add the bot to the desired group
  3. Configure the Agent to respond to @mentions or to all group messages
In groups with many members, the Agent may receive a high volume of messages. Configure filters in the prompt or use @mention_only so the bot only responds when directly mentioned.

​
Incoming webhook

Messages arrive via: 
POST https://[YOUR-SUPABASE].supabase.co/functions/v1/telegram-webhook
Timely.ai validates the X-Telegram-Bot-Api-Secret-Token header on each request. For details about the payload and supported events, see External Webhooks → Telegram.

​
Limits and best practices

  • Telegram API rate limit — 30 messages/second for the same chat, 20 messages/minute for different groups. The API returns error 429 when the limit is reached.
  • File size — bots can receive files up to 20 MB and send up to 50 MB.
  • Unique token per bot — one token corresponds to a single bot. For multiple Telegram channels, create separate bots in BotFather.
  • Bot cannot initiate conversation — unlike some channels, Telegram bots can only send messages to users who have already started a conversation with /start. Account for this in your prompt configuration.
  • Token rotation — if you suspect the token has been compromised, revoke it in BotFather with /revoke and generate a new one. Update it in Timely.ai under Channels → [your Telegram integration] → Edit.

​
Troubleshooting

Confirm that the token is in the correct format: number:string without spaces (e.g., 123456789:ABCdefGHI...). Tokens generated by BotFather always have two segments separated by :. If you copied it with accidental spaces, remove them.
Check whether the webhook was configured correctly by calling the Telegram API directly:
curl https://api.telegram.org/bot{TOKEN}/getWebhookInfo
The url field should point to https://[YOUR-SUPABASE].supabase.co/functions/v1/telegram-webhook. If it is empty, disconnect and reconnect the Channel in Timely.ai to force the setWebhook.
For groups, the bot needs permission to read messages. Check with BotFather whether can_read_all_group_messages is enabled (/setprivacy → Disable). Also, in groups with privacy enabled, the bot only receives messages with @mention.
This can happen if there are two webhooks pointing to the same bot (e.g., development and production environments). Use getWebhookInfo to check the active URL and deleteWebhook to clear it before reconfiguring.
Go to Channels → [Telegram integration] → Edit, update the token, and save. Timely.ai calls setWebhook with the new token automatically. The Conversation history is preserved in Timely.ai’s database.