Skip to main content

​
Telegram

Turn your agent into a Telegram bot that users can message directly. Supports private chats, group mentions, and automatic lead capture.

​
Prerequisites

  • A Telegram account
  • Your agent created and tested in thinnestAI

​
Setup

​
Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Choose a name (e.g., “Acme Support Bot”)
  4. Choose a username ending in bot (e.g., acme_support_bot)
  5. BotFather gives you a Bot Token — copy it

​
Step 2: Configure Your Agent

  1. Open your agent in thinnestAI
  2. Go to the Deploy tab
  3. Select Telegram
  4. Enter:
    • Bot Token — The token from BotFather
    • Bot Username — Your bot’s username (e.g., acme_support_bot)
    • Secret Token — A random string for webhook verification (generate one or let thinnestAI generate it)
  5. Click Save & Enable

​
Step 3: Set the Webhook

The webhook is set automatically when you save. If you need to set it manually: 
curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=https://api.thinnest.ai/webhooks/telegram/<AGENT_ID>&secret_token=<SECRET_TOKEN>"

​
Step 4: Test It

Open your bot in Telegram and send a message. Your agent should respond within seconds.

​
How It Works

User sends Telegram message
        ↓
Telegram forwards to /webhooks/telegram/{agent_id}
        ↓
thinnestAI verifies secret token (X-Telegram-Bot-Api-Secret-Token)
        ↓
Extracts user info → auto-captures lead
        ↓
Routes message to your agent (GraphExecutor)
        ↓
Agent responds → sent via Telegram Bot API

​
Session Persistence

Each Telegram user gets their own conversation session per chat. The agent remembers the full conversation history. Session ID format: telegram_{user_id}_{chat_id}

​
Automatic Lead Capture

Every Telegram user is automatically captured as a lead with:
  • Name: First name + last name from Telegram profile
  • Username: @username stored in custom fields
  • Chat ID: Stored in custom fields
  • Platform: telegram
  • Deduplication: One lead per Telegram user per agent

​
Ignored Commands

The bot automatically ignores /start and /help commands (they don’t trigger agent responses).

​
Security

  • Secret token verification: Every webhook request must include the correct X-Telegram-Bot-Api-Secret-Token header
  • Mandatory verification: If no secret token is configured, all requests are rejected (secure by default)
  • Constant-time comparison: Token verification uses hmac.compare_digest to prevent timing attacks

​
Bot Capabilities

FeatureSupported
Private messagesYes
Group chatsYes (via @mention)
Text messagesYes
Media messagesNot yet
Inline modeNot yet
Bot commands/start and /help handled

​
Customizing Your Bot

​
Set Bot Description

Tell BotFather about your bot: 
/setdescription — Set a description for your bot
/setabouttext — Set the about text
/setuserpic — Set the bot's profile picture

​
Set Bot Commands

/setcommands
Then enter: 
start - Start a conversation
help - Get help

​
Troubleshooting

IssueSolution
No responseVerify bot token is correct
”Unauthorized”Check secret token matches webhook configuration
”telegram not enabled”Enable Telegram in agent Deploy settings
”no bot token”Add bot token in agent configuration
Bot doesn’t appearSearch for your bot by its @username in Telegram
Webhook not setRun the setWebhook curl command manually