Bot API

Request format

All requests are made over HTTPS to an address like

https://api.telenoda.org/bot<token>/<method>

GET and POST are supported. Parameters are passed in the query string or in the body as application/x-www-form-urlencoded, application/json or multipart/form-data — the last one is needed for uploading files. Method names are case-insensitive.

The response is always JSON with an ok field:

{"ok": true, "result": {"id": 7000000123, "is_bot": true, "first_name": "Shop", "username": "shop_helper_bot"}}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

An unknown method returns 404. When a limit is exceeded, 429 is returned with parameters.retry_after — the number of seconds after which to retry the request.

Getting updates

getUpdates — long polling with the parameters offset, limit, timeout (up to 50 seconds) and allowed_updates. Acknowledge what you received by passing an offset one greater than the last update_id. Only one polling request per bot works at a time.

setWebhook accepts only an https:// address with a domain name on ports 443, 80, 88 or 8443. Addresses in internal networks are not accepted. Your server must respond to the request within 15 seconds, otherwise delivery will be retried later.

Set a secret_token and check it in the X-Telenoda-Bot-Api-Secret-Token header to tell our requests apart from others. Libraries check it automatically. The last delivery error is shown in getWebhookInfo.

Update types: message, edited_message, channel_post, edited_channel_post, callback_query, inline_query, chosen_inline_result, my_chat_member, chat_member. Updates are kept for 24 hours.

Methods (54)

Methods not on this list return 404. What isn't supported yet is described in the Limitations section.

Getting updates

• getUpdates
• setWebhook
• deleteWebhook
• getWebhookInfo

Bot

• getMe
• logOut
• close
• setMyCommands
• getMyCommands
• deleteMyCommands
• setMyName
• getMyName
• setMyDescription
• getMyDescription
• setMyShortDescription
• getMyShortDescription
• setChatMenuButton
• getChatMenuButton

Sending

• sendMessage
• forwardMessage
• copyMessage
• sendPhoto
• sendVideo
• sendAnimation
• sendAudio
• sendVoice
• sendVideoNote
• sendDocument
• sendSticker
• sendLocation
• sendChatAction

Editing and deleting

• editMessageText
• editMessageCaption
• editMessageReplyMarkup
• deleteMessage
• deleteMessages

Files

• getFile

Replies

• answerCallbackQuery
• answerInlineQuery
• answerWebAppQuery

Chats and members

• getChat
• getChatAdministrators
• getChatMember
• getChatMemberCount
• leaveChat
• banChatMember
• unbanChatMember
• restrictChatMember
• promoteChatMember
• pinChatMessage
• unpinChatMessage
• unpinAllChatMessages
• setChatTitle
• setChatDescription

For compatibility, the old names kickChatMember and getChatMembersCount also work.

Formatting

parse_mode accepts HTML, MarkdownV2 and Markdown. Instead, you can pass ready-made entities, and for media captions — caption_entities.

Commands

setMyCommands, getMyCommands and deleteMyCommands accept scope and language_code. Up to 100 commands per list and up to 1000 lists per bot.

• default, all_private_chats, all_group_chats, all_chat_administrators — general lists.
• chat with chat_id — one chat: a group the bot is in, or the private chat with a user who started the bot.
• chat_administrators with a group chat_id — the administrators of that group.
• chat_member with a group chat_id and user_id — one member; the bot must have met this user.

language_code is two lowercase Latin letters, for example ru, or empty for a list that serves all languages. getMyCommands and deleteMyCommands work with exactly the given scope and language.

A user sees the first list that is set, in this order; at each step the list in the language of their app comes first, then the list without a language:

• in the private chat with the bot — chat, all_private_chats, default;
• in a group — chat_member, chat_administrators, chat, all_chat_administrators, all_group_chats, default; administrator lists are shown to administrators only.

Keyboards and callbacks

reply_markup is accepted by all sending methods, copyMessage and editing methods.

• Buttons under a message — callback_data (1–64 bytes), url, copy_text, web_app, switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat. The style field: primary, danger or success. Up to 8 buttons per row and 100 in total.
• A keyboard instead of the system one — up to 12 buttons per row, request_contact, request_location, web_app, as well as remove_keyboard and force_reply.

Editing text or a caption without reply_markup removes the buttons. answerCallbackQuery shows a notification or an alert; a url in the answer can only open the same bot. cache_time of up to an hour lets the answer be repeated without a request to the bot.

Inline mode

The bot receives an inline_query; it answers each query once via answerInlineQuery within 10 seconds.

Supported results: article; saved photo, gif, mpeg4_gif, video, audio, voice, document and sticker by file_id; location, venue, contact. cache_time defaults to 300 seconds, maximum 3600; is_personal caches the answer separately for each user.

If a result has buttons, the sent message gets an inline_message_id: callbacks arrive with it, and the bot can edit this message with the editMessage* methods.

Groups and channels

A bot in a group with privacy mode receives commands, mentions and replies to its own messages; admins and bots without privacy mode receive all messages. In channels, admin bots receive channel_post.

When its own status changes, the bot receives my_chat_member. An admin bot that included chat_member in allowed_updates receives changes of other members.

Every action is checked against the bot's rights in that chat. Changing rights and the title works in supergroups and channels.

A bot doesn't get the full list of members: getChatMemberCount returns their number, getChatAdministrators returns the admins. By id, a bot finds only users it has already met: those who started it or wrote to it, opened its mini app, and the authors of messages, callbacks, inline queries and member changes the bot has received. For other ids, getChatMember, banChatMember, unbanChatMember, restrictChatMember and promoteChatMember return Bad Request: user not found.

Files

Upload files via multipart/form-data or pass the file_id of an already uploaded file. Sending by external URL is not supported.

getFile returns a file_path from which the file is downloaded:

https://api.telenoda.org/file/bot<token>/<file_path>

Identifiers

User and chat ids can be larger than 2³²: store them in 64-bit integers. Group and channel ids are negative. Message ids are unique within a chat.

Limits

Limitations

• No sending of files or inline results by URL; thumbnail_url is not used.
• Payments, games, sticker sets, polls from bots, albums (sendMediaGroup), editMessageMedia and login_url are not supported yet.
• answerWebAppQuery accepts only an article with text.
• In groups the Telenoda apps do not show the bot command menu yet: group lists are stored and returned by getMyCommands, and users can type a command or tap it in a message.
• chat_id as @name is not supported; pass the numeric id.
• Mini apps open only on domains from the bot's settings; the bridge is called window.Telenoda.WebApp (see Mini apps).