Telegram Integration

Give your agents the ability to message users on Telegram — plain text, inline keyboards with tappable buttons, PDFs, images, polls, and location pins. Telegram’s global reach (strong in Eastern Europe, Central Asia, parts of LATAM) makes it the right complement to WhatsApp for international voice workflows: end a call, then message the caller via whichever channel they actually use.

Connecting Telegram

Telegram doesn’t use traditional OAuth for bots. thinnestAI connects via your bot token — a one-time secret you get from Telegram’s @BotFather. Composio brokers the token storage so you don’t manage it in env vars.

Step 1: Create your bot with BotFather

Open Telegram and search for @BotFather.
Send /newbot and follow the prompts to pick a bot name (display name) and a username (must end in bot).
BotFather returns a token that looks like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz.
Copy the token — you’ll only see it once.

Keep the token secret. Anyone with the token can control the bot. Don’t paste it into Slack / email / a shared doc. The token goes directly from the BotFather chat into thinnestAI’s secure token store.

Navigate to Agents and select your agent.
Open the Tools section and click Add Tool.
Select Telegram.
Paste the Bot Token from BotFather.
Click Connect Telegram.

thinnestAI validates the token against Telegram’s getMe endpoint and shows a green Connected badge with the bot’s username.

Step 3: Choose Allowed Actions

Four capability toggles control which action groups the agent can invoke:

Toggle	Default	What it unlocks
Send Messages	✅ On	Plain text and messages with inline keyboards
Media & Files	✅ On	Photos, documents, audio, video
Rich Content	✅ On	Locations, contacts, polls, venues
Chat Admin	Off	Pin messages, set chat title/description, manage members

Leave Chat Admin off unless the agent manages a Telegram group on your behalf.

Available Actions

Messaging (4)

Action	Description
Send Message	Plain text message to a user or group chat by `chat_id`
Send Inline Keyboard	Message with tappable reply buttons
Edit Message	Update a previously-sent message’s text or keyboard
Delete Message	Remove a message the bot sent

Media (4)

Action	Description
Send Photo	Send an image by URL or file upload
Send Document	Send a PDF / DOC / XLSX / other file
Send Audio	Send an MP3 / OGG / voice note
Send Video	Send an MP4 video (≤50 MB)

Rich Content (4)

Action	Description
Send Location	Share a GPS pin
Send Contact	Share a contact card (name + phone)
Send Poll	Create a single-answer or multi-answer poll
Send Venue	Send a named location (e.g. “Taj Mahal”) with GPS

Admin (3) — opt-in

Action	Description
Pin Message	Pin an important message in a chat
Unpin Message	Remove a pinned message
Set Chat Title	Rename a group chat (agent must be admin)

Voice-AI Use Cases

Telegram’s strengths — instant delivery, no per-message cost, global reach — make it ideal for lightweight post-call touches where WhatsApp’s template-message friction would slow you down.

Agent instructions:
"After every call, send the caller a Telegram message with:
- A one-line summary ('Thanks for calling — here's what we agreed')
- The PDF transcript as a Document
- An inline button: [📅 Book follow-up]"

International Reminder Flow

Agent instructions:
"For international callers where WhatsApp isn't standard:
1. Ask during the call: 'Are you on Telegram?'
2. If yes, collect their @username or chat_id
3. 24h before the appointment, send a Telegram reminder with
   inline buttons: [Confirm] [Reschedule] [Cancel]"

Poll for Scheduling

Agent instructions:
"When a caller needs to pick a time slot from multiple options:
1. Send a Telegram poll with 3-5 time slot options
2. Wait for their vote via webhook
3. Book the winning slot in Calendar."

Example: International Scheduling Agent

Build a voice agent that handles multilingual inbound calls and follows up via Telegram for users outside WhatsApp-first markets.

Agent Setup

Field	Value
Name	Global Scheduler
Model	GPT-4o
Tools	Telegram, Google Calendar, WhatsApp

Agent Instructions

You are a booking agent serving customers worldwide. During the
call, detect the caller's locale and pick the right follow-up
channel.

WORKFLOW:
1. Collect: caller name, preferred date/time, service.
2. Detect locale from the caller's country code:
   - India, Brazil, Indonesia → WhatsApp first
   - Russia, Ukraine, Iran, Vietnam → Telegram first
   - Everywhere else → ask the caller
3. Send follow-up via the chosen channel:
   - Inline keyboard / interactive buttons for confirm vs reschedule
   - Calendar invite as a document / file attachment
4. Wait for button tap; update Calendar accordingly.

RULES:
- Always confirm the chat_id / username verbally before hangup.
  Telegram can't SMS cold — the caller must have messaged the
  bot first or you must have their chat_id.
- If neither Telegram nor WhatsApp works, fall back to SMS.

Starting a Conversation

Unlike WhatsApp (which allows template-message cold outreach), Telegram bots can only message users who have started a chat with the bot first. The simplest flow:

During the call, give the caller the bot’s link: t.me/yourbot
Ask them to tap Start inside Telegram — this reveals their chat_id to your bot
thinnestAI captures the chat_id via webhook for future messages

For returning customers, the chat_id is cached — no re-start needed.

Combining with Other Tools

Combination	Use Case
Telegram + Voice	Post-call summary, transcript delivery, follow-up reminders
Telegram + Google Calendar	Inline-keyboard reschedule flows
Telegram + WhatsApp	Channel-of-choice routing by caller locale
Telegram + Google Sheets	Log every poll result for weekly analysis
Telegram + UPI/Payment	Send a payment link; poll for “Did you pay?”

Security & Privacy

Bot tokens are encrypted at rest. thinnestAI stores them via Composio and never logs the token value.
Per-user scoping — Each user’s bot token is isolated. Your agent cannot send from another user’s bot.
Revoke access — From BotFather, send /revoke and pick the bot to invalidate the token. Then reconnect in the config modal with a fresh token.
Rate limits — Telegram enforces ~30 messages/sec to different users, 1 message/sec to a given chat. Agents that blast won’t succeed.
No read receipts — Telegram doesn’t expose read status to bots. Don’t rely on “was it seen” unless you ask for a reply.

Troubleshooting

Issue	Solution
”Unauthorized” right after connect	Token was rejected by `getMe`. Double-check you pasted the full token from BotFather with no trailing whitespace.
”chat_id not found”	The user hasn’t started a chat with the bot yet. Give them `t.me/yourbot` and ask them to tap Start.
Messages not arriving	Check if the user has blocked the bot, or if your bot hit the per-chat rate limit (1/sec).
”Bad Request: message too long”	Telegram caps at 4096 chars. Break long summaries into multiple messages or send as a document.
Inline keyboard taps don’t come through	You need a webhook configured. For button-driven flows, enable the Voice → Telegram post-call webhook in your agent settings.
Media upload fails	Telegram bot API caps at 50 MB for documents, 20 MB for photos. For larger files, host elsewhere and share a link.

Next Steps

Voice — Pair Telegram with outbound calling for full post-call workflows.
WhatsApp — Primary channel for India / Brazil / SEA markets.
Google Calendar — Build reschedule flows with inline-keyboard taps.

​Telegram Integration

​Connecting Telegram

​Step 1: Create your bot with BotFather

​Step 2: Connect via the config modal

​Step 3: Choose Allowed Actions

​Available Actions

​Messaging (4)

​Media (4)

​Rich Content (4)

​Admin (3) — opt-in

​Voice-AI Use Cases

​Post-Call Receipt / Transcript Share

​International Reminder Flow

​Poll for Scheduling

​Example: International Scheduling Agent

​Agent Setup

​Agent Instructions

​Starting a Conversation

​Combining with Other Tools

​Security & Privacy

​Troubleshooting

​Next Steps