Bot API

An HTTP interface. No protocol library, no persistent connection, no schema compiler — a curl one-liner is a complete client.

Not deployed yet

Every method below returns 404 today. See implementation status for what runs and how to verify it yourself.

Authorizing

Requests are authorized by putting the token in the path — there is no Authorization header:

https://api.casinoplaneta.info/bot<TOKEN>/<METHOD>

A token looks like 4210:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. The digits before the colon are the bot's user id and are not secret; the rest is. Anyone holding the whole string controls the bot completely — they can read everything it receives and post as it.

Because the token sits in the URL, it lands in places secrets normally do not: shell history, proxy logs, browser address bars, error trackers that capture request URLs. Keep it in an environment variable, and scrub URLs before logging them.

If a token leaks, revoke it. Rotating is cheap; a bot posting on someone else's behalf is not.

Making a request

GET and POST both work. Parameters go as a query string, application/json, or application/x-www-form-urlencoded — pick one per request, do not mix. File uploads use multipart/form-data.

# query string
curl "https://api.casinoplaneta.info/bot$TOKEN/sendMessage?chat_id=1337&text=Salom"

# JSON — preferred; the only one that handles nested objects cleanly
curl https://api.casinoplaneta.info/bot$TOKEN/sendMessage \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": 1337, "text": "Salom!"}'

Nested parameters such as reply_markup must be JSON-serialized. In a query string that means the value is itself a JSON blob — one of the more common sources of confusion, and a good reason to send JSON bodies instead.

Responses

Always a JSON object with ok:

{ "ok": true, "result": { "message_id": 42 } }

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 30",
  "parameters": { "retry_after": 30 }
}

error_code is only ever 400, 401, 403, 404, 409, 413, 429 or 500. description is for humans — it is not a stable identifier and you should not branch on its text. See Errors.

Addressing chats

chat_id encodes the chat type in its sign, so one number is never ambiguous:

Chat	chat_id	Example
Private (a person)	Positive	1337
Group	Negative	-42
Channel / supergroup	-100 prefix	-10000000042

Channel ids exceed 32 bits. Store them in a 64-bit column: a INT column silently truncates them, and a truncated id either resolves to the wrong chat or to none at all. (JavaScript's Number is safe here — these values sit far below 2^53 — but your database column may not be.)

Public chats can also be addressed by @username. That is convenient for a channel you own and a bad idea for anything else: usernames can be changed or transferred, and your bot would follow the name to whoever holds it next. Store the numeric id.

A bot learns ids by receiving updates. There is no directory to look a person up in, and no way to message someone who has not contacted the bot first.

Formatting text

parse_mode accepts MarkdownV2 or HTML, or you can skip it and pass explicit entities.

Entity offsets are counted in UTF-16 code units, not bytes and not characters. An emoji is two units. Computing offsets over a UTF-8 byte string produces formatting that lands in the wrong place, or a can't parse entities error — this is the most common formatting bug on any Telegram-shaped API, and it does not surface until someone sends you an emoji.

When interpolating user-supplied text into Markdown, escape it. An unescaped _ from a username will break the whole message, and a crafted string can forge a link.

How these pages are generated

Methods, Types, Updates and Errors are not written by hand. They are rendered from a machine-readable schema in this site's data/ directory, and the three code samples on each method — cURL, Python, PHP — are generated from a single example object, so they cannot drift apart from each other or from the parameter table above them.

The build validates the schema before rendering: a method missing a return type, a reference to an error that does not exist, or a status outside live | partial | planned fails the build rather than shipping a page with a hole in it. The build also refuses to render anything as live while the gateway is flagged as down.

This is deliberate. Hand-written API reference goes stale within a release, and stale reference is worse than none — it costs a developer an afternoon before they conclude the docs are lying. When the platform's canonical API schema package ships, the generator will read that instead, and these pages will not change shape.