Core Telegram Telegram Bot API
0
AI ReadinessNon-Ready (F)0/100
Agent-ready OpenAPI document · curated by JenticCommunicationsChat MessagingapiKey24 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Send and receive Telegram messages, photos, documents and updates as a bot, with webhook or long-polling delivery for incoming events.
Use for: Send a Telegram message to a chat from my bot, Send a photo with a caption to a Telegram group, Forward a message from one Telegram chat to another, Set a webhook URL to receive Telegram bot updates
Not supported: Does not handle Telegram MTProto user accounts, voice calls, or payments - use for Bot API messaging and updates only.
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.
Install Jentic One Beta
Connect the Telegram Bot API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Telegram Bot API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcore.telegram.org%2Ftelegram" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcore.telegram.org%2Ftelegram" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Telegram Bot API.
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
Patterns agents use Telegram Bot API for, with concrete tasks.
★ 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.
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.
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.
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}.
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
24 endpoints — jentic publishes the only available openapi specification for telegram bot api, keeping it validated and agent-ready.
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
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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
T
Telegram Bot API
- Non-Ready (F)0/100
59
Foundational Compliance63
Developer Experience & Jentic Compatibility47
AI-Readiness & Agent Experience94
Agent Usability0
Security100
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
59
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: C+Signals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
42%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: B-Signals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
47
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: DSignals: 4
38%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
100%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
50%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
0
Security
Trust, risk posture, and security compliance.
Grade: FSignals: 1
0%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
100
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A+Signals: 1
100%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Telegram Bot API through Jentic.
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.
GET STARTED