Telegram

The Telegram connector uses the Telegram Bot API to let AI agents receive updates, send messages and media, manage chat pins, and configure webhooks. Unlike OAuth connectors, Telegram authenticates with a Bot Token — paste your token from @BotFather into the API Key field when connecting.

Authentication#

Telegram uses Bot Token authentication. To connect:

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts to create a new bot
  3. Copy the bot token provided by BotFather (format: 123456789:ABC-...)
  4. Paste it into the API Key field in MCPGate's connector setup form

Note

MCPGate stores the bot token encrypted in its vault — it is never forwarded to the AI client. The bot can only interact with chats where it has been added as a member.

Tool reference#

The Telegram connector exposes 10 tools: 3 read, 6 write, and 1 delete. Use the MCP Apps page to enable or disable individual tools per app, and the Guardrails page to add fine-grained rules on top.

ToolCategoryDescription
telegram_get_updatesreadGet updates (incoming messages and events) for the bot
telegram_get_chatreadGet information about a chat by ID
telegram_list_chat_membersreadList members of a chat or group
telegram_send_messagewriteSend a text message to a chat
telegram_send_photowriteSend a photo to a chat
telegram_send_documentwriteSend a document/file to a chat
telegram_edit_messagewriteEdit a previously sent message
telegram_pin_messagewritePin a message in a chat
telegram_set_webhookwriteSet the webhook URL for receiving bot updates
telegram_delete_messagedeleteDelete a message from a chat

Common guardrail recipes#

Send-only access#

Enable read tools plus telegram_send_message, telegram_send_photo, and telegram_send_document. Deny telegram_edit_message, telegram_pin_message, telegram_set_webhook, and telegram_delete_message. This is the safest configuration for notification bots that should only send — not manage — messages.

Restrict to specific chats#

Apply the allow_values template to all send tools targeting the chat_id field. Provide a list of chat IDs the agent is permitted to message. Requests to any other chat are denied before the API call is made.

Block webhook changes#

Deny telegram_set_webhookin all apps that don't explicitly need to change bot routing. An AI that can modify the webhook URL could redirect bot traffic to an attacker-controlled endpoint.

Troubleshooting#

  • Bot cannot send to a private chat — The bot must receive at least one message from the user before it can initiate a conversation. Ask the user to send /start to the bot first.
  • get_updates returns empty — If a webhook is configured, telegram_get_updates will not receive updates (Telegram sends them to the webhook URL instead). Use telegram_set_webhook with an empty URL to disable the webhook and switch back to polling.
  • Photo or document fails — telegram_send_photo and telegram_send_documentaccept either a public URL or a base64-encoded file. Ensure the URL is publicly accessible from Telegram's servers.