> ## 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

> Deploy your thinnestAI agent as a Telegram bot with automatic lead capture and session management.

# 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](https://t.me/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:

```bash theme={null}
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

| Feature          | Supported                    |
| ---------------- | ---------------------------- |
| Private messages | Yes                          |
| Group chats      | Yes (via @mention)           |
| Text messages    | Yes                          |
| Media messages   | Not yet                      |
| Inline mode      | Not 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

| Issue                  | Solution                                         |
| ---------------------- | ------------------------------------------------ |
| No response            | Verify 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 appear     | Search for your bot by its @username in Telegram |
| Webhook not set        | Run the `setWebhook` curl command manually       |