Documentation Index
Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.
Step 2: Connect via the config modal
- 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 |
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 |
| 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.
Post-Call Receipt / Transcript Share
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.
| 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.
