---
name: telegram-bot-integration
description: Guide for connecting and verifying Telegram Bot API integrations for AI agents. Covers token setup, resolving User/Chat IDs, and troubleshooting silent delivery failures.
---

# Telegram Bot Integration

This skill provides a verified workflow for connecting an AI agent to a Telegram bot, ensuring the bot has the correct permissions and target addresses to send and receive messages.

## When to Use
Use this skill when a user wants to:
- Link their Telegram account to the agent.
- Troubleshoot why messages sent via the Bot API are not appearing in the app.
- Resolve the difference between a Bot ID and a Chat/User ID.
- Set up a new bot via BotFather.

## Workflow

### 1. Bot Creation & Token Acquisition
- Direct the user to **@BotFather** on Telegram.
- Command: `/newbot` $\rightarrow$ Follow prompts $\rightarrow$ Receive API Token.
- **Verification:** Ensure the token is stored securely (e.g., in agent memory) and is the most current version.

### 2. Resolving the Chat ID (Critical Step)
The Bot Token identifies the *sender*, but the Chat ID identifies the *receiver*. A Bot ID is **not** a Chat ID.
- **Detection:** If messages "succeed" in the API but aren't received, the Chat ID is likely wrong.
- **Resolution:** Direct the user to **@userinfobot** on Telegram.
- The user should start that bot to receive their unique numeric **User ID**.
- This User ID serves as the `chat_id` for private messages.

### 3. Establishing the "Start" Handshake
Telegram prevents bots from messaging users who haven't interacted with them first to prevent spam.
- **Action:** User **MUST** find the new bot by its username and click the **[START]** button (or send `/start`).
- **Warm-up Handshake:** In some cases, the API may still return `chat not found` immediately after the user clicks start. Instruct the user to send a random manual message (e.g. "Hello") to the bot to "warm up" the session before attempting the first programmatic `sendMessage` call.
- **Verification:** If the user has not interacted with the bot, all API `sendMessage` calls will fail with a 400 error.

### 4. Connection Testing
1.  Send a simple "Hi" or a unique code (e.g., `HERMES-TEST-123`).
2.  If not received:
    - Verify Token $\rightarrow$ Verify User ID $\rightarrow$ Verify [START] button was clicked.
3.  If received: Connection is active.

## Pitfalls & Troubleshooting
- **Bot ID vs. Chat ID:** Users often provide the ID of the bot itself (found in BotFather or via API). This will always fail.
- **User ID vs. Chat ID:** Even a correct User ID from `@userinfobot` may result in `chat not found` if the specific bot-user session is not initialized or if a specific "Home Channel" ID is required. Always verify if the user has a designated "Home Channel" ID distinct from their global User ID.
- **Silent Failures:** Some gateways report 200 OK if the request reached Telegram's servers, even if the message was dropped because the user hadn't started the bot.
- **Token Revocation:** If a token is leaked, immediately revoke it via BotFather and update the agent's memory.