# Connect Your Agent to Telegram

> Connect your AI agent to Telegram — use the shared AgentPMT bot for instant messaging, or build your own branded bot with BotFather in under 15 minutes.

Content type: documentation
Source URL: https://www.agentpmt.com/docs/tutorials/connect-agent-to-telegram
Markdown URL: https://www.agentpmt.com/docs/tutorials/connect-agent-to-telegram?format=agent-md
Category: Tutorials

---

# Connect Your Agent to Telegram

Telegram is a popular messaging app with a public Bot API, and AgentPMT offers two connectors that make your AI agent a first-class Telegram participant. You can use the **shared AgentPMT bot** for one-chat personal notifications with zero setup, or you can bring your **own BotFather-issued bot** for branded, multi-chat messaging. This tutorial walks through both paths end to end — pick the one that fits your use case in the comparison section below.

> INFO: Tested
>
> Tested with Telegram Bot API 7.x and AgentPMT — April 2026.

---

## What You Will Need

- An **AgentPMT account with a connected agent** — follow [Sign Up And Connect Your Agent](/docs/getting-started/set-up-your-account) if you have not yet
- A **Telegram account** — free, on mobile or web
- About **1 minute** for the shared bot path or **10 minutes** for the custom bot path

---

## Which Telegram Connector Should You Use?

The **Telegram Instant Messenger** uses a shared AgentPMT bot and binds each budget to one Telegram chat via a one-time code — the fastest setup and the right choice for personal agent-to-you notifications. The **Custom Telegram Bot** uses a bot you create in BotFather, supports unlimited chats under your own branding, and is the right choice for multi-user bots or business messaging. Both connectors share the same send and receive actions, so switching later is mainly a credential swap.

| Capability | Telegram Instant Messenger (shared) | Custom Telegram Bot (BYO) |
|---|---|---|
| **Setup time** | ~1 minute (OTP) | ~10 minutes (BotFather + token) |
| **Bot identity** | Shared `@AgentPMT_bot` | Your name, username, avatar |
| **Chat scope per budget** | One chat (OTP-bound) | Unlimited chats |
| **`chat_id` handling** | Automatic (hidden from agent) | Explicit `chat_id` on each send |
| **Best for** | Personal notifications and one-to-one dialogue | Multi-user bots, branded support, business messaging |

---

## Option A — Telegram Instant Messenger (Shared Bot)

The Telegram Instant Messenger connects your agent to the shared AgentPMT bot — `@AgentPMT_bot` — with no BotFather step and no token to manage. Each budget binds to exactly one Telegram chat through a short one-time code. Outbound actions never need a `chat_id` because the connector routes every message to the bound chat automatically. Setup takes about one minute once you have an AgentPMT budget.

### Step A1 — Adding the Shared Tool to Your Budget

Adding the Telegram Instant Messenger attaches the shared-bot connector to your budget and makes its actions available to every agent scoped to that budget. No credential prompt appears — the shared bot token is already managed by AgentPMT.

1. **Open the marketplace product**
   Go to the [Telegram Instant Messenger](/marketplace/telegram-instant-messenger) page in the AgentPMT marketplace.

2. **Add the tool**
   Click **Add Tool** and select the budget your agent uses. AgentPMT attaches the connector immediately — no token is requested.

### Step A2 — Binding Your Budget With a One-Time Code

Binding ties your AgentPMT budget to a single Telegram chat through a short OTP the shared bot verifies on its side. The connector never sends a message until you complete this binding. Once bound, the budget's Telegram scope is fixed — every `send_message` from that budget goes to the bound chat.

1. **Ask your agent to send a test message**
   ```text
       Send me a Telegram message that says "Connected"
       ```

       Because the budget is not bound yet, the connector returns a `connection_required` response instead of sending anything:

       ```json title="example connection_required response"
       {
         "action": "send_message",
         "status": "connection_required",
         "connected": false,
         "bot_username": "@AgentPMT_bot",
         "chat_url": "https://web.telegram.org/k/#@AgentPMT_bot",
         "otp_code": "482915",
         "start_command": "/start 482915",
         "instructions": "This budget is not connected to Telegram yet. Open chat_url, send start_command exactly, then send any message."
       }
       ```

2. **Open the AgentPMT bot in Telegram**
   Click the `chat_url` from the response, or search for `@AgentPMT_bot` in Telegram. Open the chat.

3. **Send the /start command with your OTP**
   Paste the exact `start_command` into Telegram — for example, `/start 482915`. The OTP is valid for 24 hours and reusable until the binding completes.

4. **Send one follow-up message**
   Send any additional message — for example, `hello`. Telegram only surfaces bot updates after the user sends a second message, so this step is required.

5. **Re-run the original action**
   Ask your agent again:

       ```text
       Send me a Telegram message that says "Connected"
       ```

       The connector finds your `/start` in pending updates, binds the budget, and delivers the message in the same call. Future actions send immediately without another prompt.

### Step A3 — Sending and Receiving Messages Through the Shared Bot

Once bound, the shared Telegram Instant Messenger behaves like a single-chat messaging channel for your budget. Every `send_message` goes to the bound chat without a `chat_id`; every `get_updates` filters automatically to that chat. File Manager-based photo and document sends work the same way they do on the custom bot.

1. **Send a text message**
   ```json title="send_message"
       {
         "action": "send_message",
         "text": "Your Q1 report is ready"
       }
       ```

2. **Read unread inbound messages**
   ```json title="get_updates"
       {
         "action": "get_updates",
         "unread_only": true,
         "limit": 10
       }
       ```

       Only messages from the bound chat are returned, and the connector tracks a per-budget read cursor so each poll returns new messages only.

3. **Send a photo from the File Manager**
   ```json title="send_photo"
       {
         "action": "send_photo",
         "photo_file_id": "f7d2f9d5-2d45-4d41-9d84-0dd5f6de1234",
         "caption": "Q1 chart"
       }
       ```

---

## Option B — Custom Telegram Bot (Your Own Bot)

The Custom Telegram Bot connects your agent to a bot you create and own through BotFather — with your chosen name, your `@username`, your avatar, and your token. One bot can serve unlimited users and chats. Outbound actions explicitly target a `chat_id` that your agent discovers from inbound messages. Setup takes about ten minutes, most of it spent in the BotFather chat.

### Step B1 — Creating Your Bot With BotFather

BotFather is the official Telegram bot that issues API tokens for new bots. A chat with BotFather produces three pieces of information your AgentPMT connector needs: a bot **API token**, a **bot username** ending in `bot`, and a **bot display name**. BotFather handles the underlying Telegram Bot API registration — you never sign anything or configure a server.

1. **Open BotFather in Telegram**
   In Telegram, search for `@BotFather` and open the verified account (blue checkmark). Tap **Start** if this is your first time.

2. **Send /newbot**
   Send the command `/newbot`. BotFather replies asking for a display name.

3. **Choose a display name**
   Send the display name — for example, `Sales Assistant`. This is what appears in chat headers and Telegram notifications.

4. **Choose a username**
   Send a username ending in `bot` and unique across Telegram — for example, `sales_assistant_bot`. Usernames are 5–32 characters, letters, digits, and underscores only.

5. **Copy the API token**
   BotFather replies with a message containing a line like `HTTP API: 7862819274:AAEg...xyz`. Copy the full token string. Treat it like a password — anyone with this token controls the bot.

> WARNING: Guard the token
>
> Do not paste the bot token into a chat with your AI agent. Only paste it into the AgentPMT credential field in the next step, where it is encrypted at rest and never returned to a model.

### Step B2 — Connecting the Bot in AgentPMT

AgentPMT stores your bot token as a scoped credential and injects it at runtime into every Telegram API call your agent makes. The token is encrypted at rest, bound to your budget, and never returned to the model's context. When your agent invokes any action, AgentPMT signs the request to `https://api.telegram.org/bot<token>/...` automatically.

1. **Open the Custom Telegram Bot connector**
   Go to the [Custom Telegram Bot](/marketplace/custom-telegram-bot) product in the AgentPMT marketplace and click **Add Tool**.

2. **Paste the bot token**
   When prompted for credentials, paste the API token from Step B1 into the **Telegram Bot Token** field.

3. **Save the connection**
   Click **Save**. AgentPMT encrypts the token and attaches the tool to your active budget.

### Step B3 — Starting a Conversation With Your Bot

Telegram bots cannot message a user until that user has opened a chat with the bot and sent `/start`. This is a Telegram platform rule — not an AgentPMT one — and it prevents bots from spamming arbitrary users. The first `/start` registers the user's `chat_id` on Telegram's side, which the Custom Telegram Bot connector then surfaces to your agent via `get_updates`.

1. **Open your bot in Telegram**
   In Telegram, search for your bot's username (for example `@sales_assistant_bot`) and open the chat.

2. **Send /start**
   Tap **Start** or send the text `/start`. Telegram delivers the message to your bot and records the conversation.

3. **Send a test message**
   Send any additional message — for example, `Hello`. This ensures at least one message is available for your agent to read in Step B4.

### Step B4 — Reading Inbound Messages and Discovering `chat_id`

The Telegram Bot API identifies conversations by numeric `chat_id`, not by username or display name. Your agent discovers each `chat_id` by calling `get_updates` once after any user has sent a message. The response includes the sender's `chat_id`, their username, and the message text. AgentPMT also persists a shortlist of seen chats per budget so your agent can recall them later with `list_known_chat_ids`.

1. **Ask your agent to check for unread messages**
   ```text
       Check for new Telegram messages on my custom bot
       ```

       The agent calls `get_updates` with `unread_only: true`:

       ```json title="example response"
       {
         "action": "get_updates",
         "updates": [
           {
             "update_id": 482915031,
             "message": {
               "message_id": 14,
               "from": {
                 "id": 482109573,
                 "username": "alice",
                 "first_name": "Alice"
               },
               "chat": {
                 "id": 482109573,
                 "type": "private"
               },
               "text": "Hello"
             }
           }
         ],
         "count": 1
       }
       ```

2. **Note the chat_id**
   The `chat.id` value (here `482109573`) is the `chat_id` your agent uses for every outbound message to that user. Save it or let AgentPMT cache it — `list_known_chat_ids` returns every chat the bot has seen within this budget.

### Step B5 — Sending Messages From Your Agent

Outbound messages use the `send_message` action with a `chat_id` discovered in Step B4 and a `text` body. The Telegram Bot API supports `parse_mode: "MarkdownV2"` or `parse_mode: "HTML"` for rich formatting, inline keyboards via `reply_markup`, silent delivery via `disable_notification`, and topic threading via `message_thread_id` for forum-style chats.

1. **Ask your agent to send a message**
   ```text
       Send a Telegram message to chat 482109573 saying "Your report is ready"
       ```

       The agent calls `send_message`:

       ```json title="request"
       {
         "action": "send_message",
         "chat_id": "482109573",
         "text": "Your report is ready"
       }
       ```

2. **Format with Markdown or HTML**
   To send bold, italic, or link-formatted text, set `parse_mode`:

       ```json title="rich-formatted send_message"
       {
         "action": "send_message",
         "chat_id": "482109573",
         "text": "*Report ready.* Open: [Dashboard](https://example.com/report/42)",
         "parse_mode": "MarkdownV2"
       }
       ```

### Step B6 — Sending and Receiving Files Through Your Bot

The Custom Telegram Bot connector sends photos with `send_photo` and arbitrary files with `send_document`. Each action accepts either a **File Manager `file_id`** or a **direct source** — URL, Telegram file_id, or base64 payload. Using a File Manager `file_id` keeps large attachments out of the chat payload. Inbound photos and documents can be ingested into the File Manager by setting `ingest_files_to_manager: true` on `get_updates`.

1. **Send a photo from the File Manager**
   ```json title="send_photo from File Manager"
       {
         "action": "send_photo",
         "chat_id": "482109573",
         "photo_file_id": "f7d2f9d5-2d45-4d41-9d84-0dd5f6de1234",
         "caption": "Q1 chart"
       }
       ```

2. **Send a document from a URL**
   ```json title="send_document from URL"
       {
         "action": "send_document",
         "chat_id": "482109573",
         "document": "https://example.com/reports/q1-2026.pdf",
         "caption": "Q1 2026 report"
       }
       ```

3. **Save inbound files to the File Manager**
   ```json title="get_updates with ingestion"
       {
         "action": "get_updates",
         "unread_only": true,
         "ingest_files_to_manager": true,
         "ingest_max_files": 5,
         "ingest_expiration_days": 7
       }
       ```

       The response includes each saved file with a new File Manager `file_id`:

       ```json title="ingested_files excerpt"
       {
         "ingested_files": [
           {
             "source_telegram_file_id": "AgACAg...xyz",
             "file_id": "b94c8f2a-17de-4fa8-b3b8-2c9e0f1a5b42",
             "filename": "receipt.jpg",
             "content_type": "image/jpeg",
             "size_bytes": 204819
           }
         ]
       }
       ```

---

## Troubleshooting

### 'This budget is not connected to Telegram yet' on the shared bot

The Telegram Instant Messenger returns this when the budget has no active binding. Complete the OTP flow in Option A, Step A2 — open the `chat_url`, send the exact `/start <otp_code>`, and send one follow-up message. Re-run the action to complete the bind.

### 'Telegram Bot connection is required. Please connect Telegram Bot Token and retry.'

The Custom Telegram Bot has no token attached. Open the [Custom Telegram Bot](/marketplace/custom-telegram-bot) connector, click **Add Tool**, and paste the token from BotFather.

### 'Unauthorized' or HTTP 401 from Telegram

The bot token is wrong, was revoked in BotFather, or was regenerated with `/revoke`. Send `/mybots` to BotFather, select the bot, tap **API Token**, copy the current token, and update the AgentPMT credential.

### 'Forbidden: bot was blocked by the user'

The recipient blocked the bot in Telegram. Telegram does not allow bots to message users who have blocked them. The user must unblock the bot and send `/start` again.

### 'Bad Request: chat not found'

The `chat_id` is wrong or the user has never messaged the bot. Bots can only send to chats where the user has sent at least one message. Have the user open the bot and send `/start`, then run `get_updates` to capture the correct `chat_id`.

### 'send_message requires chat_id'

This error appears on the Custom Telegram Bot only — it is multi-chat, so every outbound action must specify a `chat_id`. Call `list_known_chat_ids` or `get_updates` first to discover available chats. The shared Telegram Instant Messenger does not require a `chat_id` because each budget is bound to one chat.

### 'Too Many Requests: retry after N'

Telegram is rate-limiting the bot. The default limits are ~30 messages per second globally and ~1 message per second per chat. Space out high-volume sends or batch messages into a single formatted digest.

---

## Frequently Asked Questions

### Can I switch from the shared bot to a custom bot later?

Yes. The two connectors share the same action surface (`send_message`, `send_photo`, `send_document`, `get_updates`). Add the Custom Telegram Bot connector, have users send `/start` to the new bot so Telegram registers them, and route new sends through the new tool. Automations that were written against the shared bot need one edit — add an explicit `chat_id` to every send, since the custom bot is multi-chat.

### Does the Custom Telegram Bot receive messages via webhook or polling?

The Custom Telegram Bot uses long-polling through the Telegram Bot API `getUpdates` endpoint — no public webhook URL is required. Your agent fetches pending updates on demand with the `get_updates` action, and AgentPMT persists a per-budget read cursor so `unread_only: true` returns only new messages. Long-polling means the bot works behind any firewall without inbound networking.

### Can one custom bot handle multiple users and multiple chats?

Yes. The Custom Telegram Bot connector supports any number of chats scoped to the same bot token within a budget. Each chat is identified by its numeric `chat_id`, which your agent discovers via `get_updates` or recalls via `list_known_chat_ids`. Every `send_message`, `send_photo`, and `send_document` call takes an explicit `chat_id`, so routing is always explicit.

### How do I change my custom bot's avatar, description, or commands?

All bot presentation is managed through BotFather in Telegram — not through AgentPMT. Open BotFather, send `/mybots`, select your bot, and use options like **Edit Bot Picture**, **Edit Description**, **Edit About**, and **Edit Commands**. Changes take effect in Telegram immediately; no AgentPMT reconfiguration is needed.

### What happens if I revoke the token in BotFather?

Revoking a token in BotFather (`/revoke` + select bot) invalidates the old token immediately. The bot itself continues to exist under a new token; only the credential changes. After revoking, copy the new token from BotFather and update it in the AgentPMT credential — your agent keeps working with no code change. See [How Credentials Work](/docs/core-concepts/how-credentials-work) for AgentPMT's credential rotation model.

### Are there message-size or file-size limits?

Yes — Telegram enforces **4096 characters** per text message, **50 MB** per file upload through the Bot API, and **10 MB** per photo upload. Agents sending larger content should split text into multiple messages, send files via `send_document` instead of `send_photo` when over 10 MB, or host the file externally and send a link.

---

## Related Docs