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

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