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.

What You Will Need#

• An AgentPMT account with a connected agent — follow Sign Up And Connect Your Agent 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.

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.

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.

Send me a Telegram message that says "Connected"

{
  "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."
}

Send me a Telegram message that says "Connected"

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.

{
  "action": "send_message",
  "text": "Your Q1 report is ready"
}

{
  "action": "get_updates",
  "unread_only": true,
  "limit": 10
}

{
  "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.

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.

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.

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.

Check for new Telegram messages on my custom bot

{
  "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
}

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.

Send a Telegram message to chat 482109573 saying "Your report is ready"

{
  "action": "send_message",
  "chat_id": "482109573",
  "text": "Your report is ready"
}

{
  "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.

{
  "action": "send_photo",
  "chat_id": "482109573",
  "photo_file_id": "f7d2f9d5-2d45-4d41-9d84-0dd5f6de1234",
  "caption": "Q1 chart"
}

{
  "action": "send_document",
  "chat_id": "482109573",
  "document": "https://example.com/reports/q1-2026.pdf",
  "caption": "Q1 2026 report"
}

{
  "action": "get_updates",
  "unread_only": true,
  "ingest_files_to_manager": true,
  "ingest_max_files": 5,
  "ingest_expiration_days": 7
}

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

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