TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Telegram Bot API Basics: Methods, Updates and Responses

· 4 min read · 18+ readers

Telegram Bot API Basics: Methods, Updates and Responses: TSocial guide cover card

The Bot API is an HTTP interface. Your program sends requests to Telegram to do things, and receives updates describing what users did. Understanding its shape makes every library easier to use. This guide covers the essentials and points you to the official documentation at core.telegram.org/bot icon bots/api for the full, current list of methods.

The request format

Every call goes to:

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

You may send parameters as a query string, as form data or as code icon JSON with the header content-type: application/json. JSON is the most convenient for nested objects such as keyboards.

The response format

Responses are JSON objects:

{ "ok": true, "result": { ... } }

On failure you get "ok": false with an error_code and a description, and sometimes a parameters object. For rate limits it includes retry_after in seconds. Always check ok before you read result.

Updates

An update is an object that tells you something happened. It has an update_id and exactly one of several optional fields. The ones you will meet first are:

  • message: a new message in a chat with the bot or in a group where the bot can see it.
  • edited_message: a message was edited.
  • callback_query: someone pressed an inline button.
  • inline_query: someone typed @yourbot something in any chat. See inline bots.
  • pre_checkout_query and message.successful_payment: payments. See Stars payments.
  • my_chat_member: the bot was added, removed or blocked.
  • business_connection and business_message: Telegram Business. See Business bots.

Telegram numbers updates in order. You can store the last update_id and ignore repeats.

Getting updates

Two ways, never at the same time: getUpdates (long polling) and setWebhook. See webhook vs long polling. You can limit the types of updates with the allowed_updates parameter. Some types, such as chat member changes, are not sent unless you list them.

Methods you will use constantly

  • getMe: check the token and read the bot's info.
  • sendMessage: chat_id, text, optional parse_mode, reply_markup, reply_parameters.
  • editMessageText and deleteMessage.
  • sendPhoto, sendVideo, sendDocument: send files by file_id, URL or upload.
  • answerCallbackQuery: acknowledge a button press, or the button will show a loading spinner.
  • setMyCommands, setMyDescription, setMyShortDescription: bot profile. See profile setup.
  • getChat, getChatMember: look up chats and members.
  • setWebhook, deleteWebhook, getWebhookInfo.

Formatting text

parse_mode accepts HTML, MarkdownV2 or the legacy Markdown. HTML is easier to get right:

{ "chat_id": 123, "text": "<b>Hello</b> <i>world</i>", "parse_mode": "HTML" }

If you insert user text into HTML or MarkdownV2, escape special characters, or you will see can't parse entities errors. A message can hold up to 4096 characters. Captions are shorter.

Keyboards

reply_markup can be an inline keyboard attached to the message:

{ "inline_keyboard": [[ { "text": "Open site", "url": "https://example.com" },
                        { "text": "More", "callback_data": "more" } ]] }

callback_data is limited to 64 bytes. Reply keyboards replace the phone keyboard. See inline keyboards and callbacks.

Files

Uploading is done with multipart form data. Once Telegram has a file, it gives you a file_id you can reuse. The file_id is specific to your bot. Downloading files from users uses getFile and then a URL under https://api.telegram.org/file/bot<TOKEN>/<file_path>. Size limits apply, so check the documentation for current numbers.

Local Bot API server

Telegram publishes the Bot API server code so you can run your own. It allows larger file sizes and other options, at the cost of running it. Most bots do not need it.

Good habits

  • Check ok on every response and log failures.
  • Respect rate limits. See rate limits and flood control.
  • Keep handlers fast, and do slow work in a queue.
  • Pin the library version you use and read changelogs when Telegram adds features.

Quick checklist

  • URL format is https://api.telegram.org/bot<TOKEN>/METHOD.
  • Requests use JSON with a content-type header.
  • ok is checked on every response.
  • allowed_updates lists only what you handle.
  • HTML or MarkdownV2 text is escaped.
  • callback_data stays under 64 bytes.
  • file_id values are cached and reused.
  • Method names are copied from the official reference.

Reading the reference

The Bot API reference lists every method with its parameters and the objects it returns. When you add a feature, find the method, read the required fields, try it with a plain HTTP request and then write it in your library. This habit prevents most mistakes caused by guessing names or fields.

Frequently asked questions

Are Bot API method names case sensitive?

Yes. Use the exact names from the documentation, such as sendMessage.

How do I know a method exists?

Check core.telegram.org/bots/api. Do not guess method names.

Can bots send messages to anyone?

No. A user must have interacted with the bot first, or the bot must be in the chat.

Where do I see all error codes?

Errors carry a description string. See common errors and fixes.

Related guides

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Telegram Bot API Basics: Methods, Updates and Responses | TSocial