Telegram Bot API Tester

Before you paste a live bot token

The Telegram Bot API changes as new methods and fields are added, and existing behaviour is subject to change. This page is an independent guide, not documentation. Check the official Telegram Bot API documentation for authoritative details.

How the Telegram Bot API is addressed

Telegram's URL scheme is the whole story. Every request looks like this:

https://api.telegram.org/bot<TOKEN>/<METHOD>

The literal string bot is immediately followed by your token with no separator, then a slash and the method name. So a token like 123456:ABC-DEF produces a path beginning /bot123456:ABC-DEF/. Forgetting the bot prefix, or inserting a slash or space between it and the token, is the most common first-attempt mistake and produces a confusing error because the path no longer matches anything Telegram recognises.

Method names are camelCase and read like verbs: getMe, getUpdates, sendMessage, getWebhookInfo, setWebhook, deleteWebhook. Arguments can be supplied as query-string parameters or as a JSON request body, and Telegram accepts either — a genuinely flexible design. For quick tests, query parameters in the Params tab are easiest; for anything with nested structure, a JSON body is cleaner. Notably, Telegram tolerates GET for most methods, including ones that cause side effects, which makes casual testing easy and makes it worth being careful about what you fire off.

Because there is no Authorization header, the Auth tab above stays on "No authentication". That is correct and not an oversight. The only header worth setting is Content-Type: application/json when you send a JSON body.

Valid and invalid: reading Telegram's envelope

Every Telegram response is wrapped in a consistent envelope with an ok boolean. On success you get "ok": true and a result field carrying the payload. On failure you get "ok": false alongside an error_code and a human-readable description.

Helpfully — and unlike some other chat platforms — Telegram also sets the HTTP status line to match. A rejected token gives you a real 401 Unauthorized on the status line as well as in the body, so both the status pill and the JSON tell the same story. You do not have to remember to look past a misleading 200.

getMe is the canonical health check. A valid token returns ok: true with a result object containing the bot's numeric id, its username, its display name and an is_bot flag. Seeing the username you expect is a complete confirmation: the token is live and it belongs to the bot you think it does. An invalid token returns 401 with ok: false and a description of "Unauthorized", which covers a mistyped token, a revoked one, and a malformed path all at once — so check the bot prefix before assuming the token itself is dead.

The sample button above deliberately sends a deformed token. It is there so you can see the failure shape without risking a real credential, and to prove connectivity to Telegram independently of whether your own token works.

Getting a token from BotFather

Telegram bot tokens are not issued through a web dashboard. You get them by talking to BotFather, an official bot inside Telegram itself. Start a chat with it, send the new-bot command, and answer its prompts for a display name and a username ending in "bot". BotFather replies with the token in the chat.

That reply is worth noticing: your token now lives in a Telegram message, which syncs across every device signed into your account. BotFather can reissue a token, which invalidates the previous one, and it can also show you the current token again on request. For testing, create a dedicated bot rather than reusing a real one — the cost is a minute of chat and the benefit is that experiments cannot reach anyone.

Sending a message, and why chat_id is the hard part

sendMessage needs two arguments: a chat_id and some text. The text is easy; the chat id is where people get stuck, because you cannot invent it. Telegram bots cannot initiate conversations — a user must message the bot first, or the bot must be added to a group. Only then does a chat id exist for it to reply to.

The usual bootstrap is: message your bot from your own Telegram account, then call getUpdates from this page. The response contains the pending update objects, and inside them the chat id you need. Copy it into a chat_id parameter, add text, and call sendMessage. If getUpdates returns an empty result array, either nobody has messaged the bot yet or a webhook is registered — which is the next section.

Polling versus webhooks, and reading 429

A Telegram bot receives updates one of two mutually exclusive ways. It either polls with getUpdates, or it registers a webhook with setWebhook and Telegram posts updates to a URL you host. You cannot use both. If a webhook is set, getUpdates will not return anything, and this catches out almost everyone who inherits a bot someone else configured.

getWebhookInfo settles it instantly: it reports the currently registered URL, if any, along with pending update counts and details of recent delivery errors. That last part is quietly excellent for debugging — if Telegram cannot reach your endpoint, it will tell you why it failed. Once you know what Telegram is sending, the webhook tester helps you understand the payloads arriving at your side. deleteWebhook switches back to polling.

A 429 Too Many Requests from Telegram arrives with a retry_after value in the response, telling you how many seconds to wait. Telegram applies different practical limits to direct messages, group messages and broadcasts, so this page quotes no numbers — use the value Telegram actually returns. A 403 typically means the bot is not permitted in that conversation: the user blocked it, or it was removed from the group. Response headers in general are covered in the HTTP headers reference. Telegram bot tokens are opaque strings rather than JSON Web Tokens, so if you are holding a credential you cannot identify, the JWT decoder will tell you locally which kind you have. The general API tester handles endpoints outside Telegram's scheme.

Test another provider's API

Frequently asked questions