canonical: https://jentic.com/apis/core.telegram.org/telegram # Core Telegram Telegram Bot API Jentic publishes the only available OpenAPI specification for Telegram Bot API, keeping it validated and agent-ready. The Telegram Bot API exposes 24 method-style endpoints under the path /{methodName} for sending messages, photos, documents and other media to chats, plus webhook setup, getMe identity checks, message forwarding and copying, and update polling for long-poll bot architectures. Authentication is via the bot token embedded in the path (https://api.telegram.org/bot{token}/METHOD), and methods accept JSON or form-encoded bodies. The API supports both polling (getUpdates) and push (setWebhook) flows for receiving incoming messages. ## For AI agents Send and receive Telegram messages, photos, documents and updates as a bot, with webhook or long-polling delivery for incoming events. ## Scope Does not handle Telegram MTProto user accounts, voice calls, or payments - use for Bot API messaging and updates only. ## Capabilities - Send a text message to a Telegram chat including markdown formatting and inline keyboards - Send photos or documents to a chat with optional captions - Forward or copy a message between two chats - Set a webhook URL so Telegram pushes incoming updates to your server - Long-poll for new updates with getUpdates when a webhook isn't usable - Verify the bot's identity and capabilities with getMe before sending ## Use cases ### Operational Alerts to a Telegram Channel Engineering and ops teams can send Slack-style alerts to a Telegram channel by calling /sendMessage with the channel chat_id and a markdown-formatted body. /sendDocument can attach log snippets or report PDFs, and inline keyboards let on-call engineers acknowledge an alert directly from the message. Example prompt: POST /sendMessage with chat_id of the on-call channel and a markdown alert body containing the failing service name and a link to the runbook. ### Customer Support Bot with Webhook Delivery Customer support teams can deploy a Telegram bot that receives messages via webhook and replies with /sendMessage. /setWebhook installs the receiver, /getWebhookInfo confirms delivery health, and /deleteWebhook switches back to long polling for testing without leaving the spec. Example prompt: POST /setWebhook with the support backend URL, then on each incoming update reply via /sendMessage referencing the original chat_id and message_id. ### Content Distribution from a CMS Publishers can broadcast new posts to a Telegram channel by combining /sendPhoto for hero images and /sendMessage for headline plus link. The bot token in the path keeps each publication's bot isolated, and /copyMessage lets the team rebroadcast curated picks across multiple channels without losing attribution. Example prompt: POST /sendPhoto with the article hero image to channel @example_channel, then POST /sendMessage with the headline and URL for that article. ### AI Agent Chat Interface on Telegram An AI agent can serve users directly inside Telegram by receiving updates via webhook and replying through /sendMessage and /sendDocument. Through Jentic, the bot token never leaves the credential vault and the agent calls Telegram operations using their plain method names mapped to /{methodName}. Example prompt: Use Jentic to call /sendMessage with chat_id from the incoming update and a generated reply body, after the webhook delivered the user's question. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /getMe | Get bot information | | POST | /sendMessage | Send a text message | | POST | /sendPhoto | Send a photo | | POST | /sendDocument | Send a document | | POST | /setWebhook | Set the webhook URL for incoming updates | | POST | /getUpdates | Long-poll for incoming updates | | POST | /forwardMessage | Forward a message between chats | ## Key resources - **Messages** — Send, forward and copy messages including text, photos and documents - **Updates** — Receive incoming updates via long polling (getUpdates) or webhooks (setWebhook) - **Bot** — Identity and capability checks for the bot account (getMe) - **Webhooks** — Webhook lifecycle: setWebhook, deleteWebhook and getWebhookInfo ## Why Jentic - **Setup:** Wiring the Telegram Bot API by hand means substituting your bot token into the api.telegram.org/bot{token} path on every call and coding the send and update operations yourself. Through Jentic you install once, import the Telegram Bot API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** The chat to message travels in the request body as chat_id, not as a fixed path resource, so scope this by operations: allow the agent the calls it needs, such as sending a message or a photo, and leave webhook configuration or update polling out unless you add them. Each operation you credit the agent with stays inside that allowed set. - **Credential handling:** Your Telegram bot token is stored once, encrypted, by your own Jentic One instance and substituted into the bot{token} path segment at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'send a Telegram message' or 'set a Telegram webhook', and Jentic returns the matching operation with its chat_id and body schema so the agent picks the right send variant for text, photo, or document without browsing the reference docs. ## Related APIs - **Slack API** — Workplace messaging platform with channels and threads, used for team comms rather than consumer chat - **Discord API** — Community chat platform with servers and channels, similar bot model to Telegram - **MessageBird Intent API** — NLU layer that can parse incoming Telegram messages before the bot replies ## FAQ ### Why is there no official OpenAPI spec for Telegram Bot API? Telegram does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Telegram Bot API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Telegram Bot API use? The bot token is embedded in the URL path (https://api.telegram.org/bot{token}/{method}). Through Jentic the bot token sits in the credential vault and is substituted into the path at execution time, so the secret never enters agent context. ### Can I send photos with the Telegram Bot API? Yes. POST /sendPhoto accepts a chat_id plus a photo (file_id, URL or upload) and an optional caption. Use /sendDocument for arbitrary files and /sendMessage for plain text or markdown bodies. ### Should I use webhooks or long polling with the Telegram Bot API? Webhooks (POST /setWebhook) are the production-grade option since Telegram pushes updates to your server. Long polling (POST /getUpdates) is useful for local development. Use /getWebhookInfo to confirm delivery health when debugging missed messages. ### What rate limits apply to the Telegram Bot API? The OpenAPI spec does not declare formal rate limits, but Telegram documents soft limits of roughly 30 messages per second across all chats and 1 message per second per chat. Implement exponential backoff on HTTP 429 with the retry_after value Telegram returns. ### How do I send a Telegram message through Jentic with the Telegram Bot API? Run pip install jentic, search Jentic with 'send a Telegram message', load the operation schema for POST /sendMessage and execute with the chat_id and text payload; Jentic substitutes the bot token in the path automatically. ### Can I limit what my agent is allowed to do with the Telegram Bot API? Yes. Because you run Jentic One yourself, your own rules decide which Telegram operations and credentials the agent may use. The chat travels in the request body as chat_id rather than as a fixed path, so you scope access by operation: grant only the calls the agent needs, such as /sendMessage or /sendPhoto, and leave /setWebhook, /deleteWebhook, and /getUpdates out unless you add them. Each operation you credit the agent with stays inside that allowed set.