# Telegram — how to use (mcp.ai)

Connect your Telegram account and use 18 tools for team chat straight from your AI agent. Connect with your own API key. Telegram is a cloud-based messaging app with a focus on security and speed. Build bots to send messages, manage chats, and interact with users.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_telegram?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `telegram_answer_callback_query`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/telegram`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/telegram/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/telegram/answer/callback/query` — Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert.
  - body: { url?: string, text?: string, cache_time?: integer, show_alert?: boolean, callback_query_id: string }
- `POST https://api.mcp.ai/api/telegram/create/chat/invite/link` — Generate a new primary invite link for a chat; any previously generated primary link is revoked. The bot must be an administrator in the chat for this to work and must have the appropriate administrat
  - body: { chat_id: integer|string }
- `POST https://api.mcp.ai/api/telegram/delete/message` — Delete a message, including service messages. Limitations: cannot delete messages older than 48 hours in groups, forwarded messages, or content in protected chats (returns 400 'message can’t be delete
  - body: { chat_id: integer|string, message_id: integer }
- `POST https://api.mcp.ai/api/telegram/edit/message` — Edit text messages sent by the bot. Only bot-authored messages can be edited; editing messages from other users will fail. In groups, the bot must have edit permissions.
  - body: { text: string, chat_id?: integer|string, message_id?: integer, parse_mode?: string, reply_markup?: string, inline_message_id?: string, disable_web_page_preview?: boolean }
- `POST https://api.mcp.ai/api/telegram/forward/message` — Forward messages of any kind. Service messages can't be forwarded.
  - body: { chat_id: integer|string, message_id: integer, from_chat_id: integer|string, disable_notification?: boolean }
- `POST https://api.mcp.ai/api/telegram/get/chat` — Get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.). The bot must be a member of or have access to the
  - body: { chat_id: integer|string }
- `POST https://api.mcp.ai/api/telegram/get/chat/administrators` — Get a list of administrators in a chat. On success, returns an Array of ChatMember objects containing information about all chat administrators except other bots. Only meaningful for supergroups and c
  - body: { chat_id: integer|string }
- `POST https://api.mcp.ai/api/telegram/get/chat/history` — Get chat history messages via the getUpdates polling method, filtered by chat_id. Returns only updates from the specified chat. Bot can only retrieve messages sent after it joined the chat; missing ol
  - body: { limit?: integer, offset?: integer, chat_id: integer|string, message_id?: integer }
- `POST https://api.mcp.ai/api/telegram/get/chat/member` — Get a chat member's status/role (including the bot itself) to preflight permissions and troubleshoot 403/empty-history issues. Use before sending messages to verify bot membership and permissions.
  - body: { chat_id: integer|string, user_id: integer }
- `POST https://api.mcp.ai/api/telegram/get/chat/members/count` — Get the number of members in a chat. The bot must be an administrator in the chat for this to work. Insufficient admin permissions surface as authorization errors, not as a zero or empty count.
  - body: { chat_id: integer|string }
- `POST https://api.mcp.ai/api/telegram/get/me` — Get basic information about the bot using the Bot API getMe method. Returns fields like id, username, first_name, and capabilities. If the response returns ok=false, the bot token is invalid or revoke
- `POST https://api.mcp.ai/api/telegram/get/updates` — Use this method to receive incoming updates using long polling. An Array of Update objects is returned. IMPORTANT: This method will not work if an outgoing webhook is set up. Webhooks and getUpdates a
  - body: { limit?: integer, offset?: integer, timeout?: integer, allowed_updates?: string[] }
- `POST https://api.mcp.ai/api/telegram/send/document` — Send general files (documents) to a Telegram chat using the Bot API. Prefer over TELEGRAM_SEND_PHOTO when original file format or image resolution must be preserved. Rapid sends trigger flood control 
  - body: { caption?: string, chat_id: integer|string, document: string, thumbnail?: string, parse_mode?: string, reply_markup?: string, reply_to_message_id?: integer, disable_notification?: boolean, disable_content_type_detection?: boolean }
- `POST https://api.mcp.ai/api/telegram/send/location` — Send point on the map location to a Telegram chat using the Bot API.
  - body: { chat_id: integer|string, heading?: integer, latitude: number, longitude: number, live_period?: integer, reply_markup?: string, horizontal_accuracy?: number, reply_to_message_id?: integer, disable_notification?: boolean, proximity_alert_radius?: integer }
- `POST https://api.mcp.ai/api/telegram/send/message` — Send a text message to a Telegram chat using the Bot API. Bots must be members of target groups/channels with post rights. Rate limit: ~1 msg/sec per chat, ~30 msg/sec globally; exceeding returns 429 
  - body: { text: string, chat_id: integer|string, parse_mode?: string, reply_markup?: string, reply_to_message_id?: integer, disable_notification?: boolean, disable_web_page_preview?: boolean }
- `POST https://api.mcp.ai/api/telegram/send/photo` — Send photos to a Telegram chat using the Bot API. Telegram compresses and re-encodes images; use TELEGRAM_SEND_DOCUMENT to preserve original resolution/format. Each call produces a separate post; no m
  - body: { photo: string, caption?: string, chat_id: integer|string, parse_mode?: string, reply_markup?: string, reply_to_message_id?: integer, disable_notification?: boolean }
- `POST https://api.mcp.ai/api/telegram/send/poll` — Send a native poll to a Telegram chat using the Bot API.
  - body: { type?: string, chat_id: integer|string, options: string[], question: string, is_closed?: boolean, close_date?: integer, explanation?: string, open_period?: integer, is_anonymous?: boolean, reply_markup?: string, correct_option_id?: integer, reply_to_message_id?: integer, disable_notification?: boolean, explanation_parse_mode?: string, allows_multiple_answers?: boolean }
- `POST https://api.mcp.ai/api/telegram/set/my/commands` — Use this method to change the list of the bot's commands. See https://core.telegram.org/bots#commands for more details about bot commands.
  - body: { scope?: string, commands: object[], language_code?: string }

## Example prompts
- "What can I do in Telegram?"
- "Show me a summary of my Telegram account"

## More
- Page: https://mcp.ai/telegram
- Agent spec (llms.txt): https://mcp.ai/telegram/llms.txt
- Postman collection: https://mcp.ai/telegram/postman.json