Bot API: Telegram-compatible adapter
Sensever accepts requests in the Telegram Bot API format. Existing Telegram libraries work with a Sensever bot once you change their base URL and token. Methods run on the same code as the native Bot API, with the same permissions and limits. This article is the complete list of what the adapter supports and how it differs from Telegram.
Connecting
Request:
GETorPOSTtohttps://api.sensever.com/bot<token>/<method>. Method names are case-insensitive.Parameters go in the query string, a form (
application/x-www-form-urlencodedormultipart/form-data) or JSON, as in Telegram. Nested objects in a form (reply_markup,results,commands,allowed_updates,reaction,options,scope,reply_parameters,link_preview_options) are passed as a JSON string.Token:
<bot_id>:<the part of the token after "b1.">. For example, for a bot withbot_id812 and tokenb1.AbC…, it is812:AbC…. Such a token passes the format check in libraries. Theb1.…token itself is accepted too.Response:
{"ok": true, "result": …}or{"ok": false, "error_code": 400, "description": "Bad Request: …"}; on429and on a temporary server error (500,503),"parameters": {"retry_after": N}is added.
Library | Setup |
|---|---|
aiogram 3 |
|
python-telegram-bot |
|
grammY |
|
Telegraf |
|
Any HTTP client |
|
Example without a library:
curl -s "https://api.sensever.com/bot$TG_TOKEN/sendMessage" \
-H "Content-Type: application/json" \
-d '{"chat_id": 901, "text": "Your order is <b>on its way</b>", "parse_mode": "HTML", "reply_markup": {"inline_keyboard": [[{"text": "Track", "callback_data": "track"}]]}}'Supported methods
Parameters not listed in the tables are accepted and have no effect.
Getting updates
Method | Supported parameters | Notes |
|---|---|---|
getMe | — | Returns |
getUpdates |
| Negative |
setWebhook |
| An empty |
deleteWebhook |
| Returns the bot to |
getWebhookInfo | — |
|
Messages
Method | Supported parameters | Notes |
|---|---|---|
sendMessage |
|
|
sendPhoto, sendDocument, sendVideo, sendAudio, sendVoice, sendAnimation |
| The file is a |
sendPoll |
| Only a regular single-answer poll: |
editMessageText |
| Without |
editMessageReplyMarkup |
| Only the bot's own messages |
deleteMessage |
| Other people's messages only in a group or channel where the bot is an admin |
sendChatAction |
| Any |
setMessageReaction |
| The list replaces the bot's reactions on the message; an empty list removes all of them. Only |
getFile |
|
|
chat_id by email or phone. Instead of a chat number, every method that takes chat_id accepts a subscriber's confirmed email ("anna@example.com") or phone with + ("+447700900123"); digits alone are a chat number. Send it in the JSON or form body: in a URL query a + must be written as %2B. The person must have opened the bot and tapped Start; otherwise the answer is 400 Bad Request: chat not found.
Buttons, commands, profile
Method | Supported parameters | Notes |
|---|---|---|
answerCallbackQuery |
| Once, within 15 minutes |
answerInlineQuery |
| Only |
setMyCommands |
|
|
getMyCommands, deleteMyCommands |
| — |
setMyDescription, getMyDescription |
| One description for all languages: |
setMyShortDescription, getMyShortDescription |
| Same |
Groups and channels
Method | Supported parameters | Notes |
|---|---|---|
getChat |
| Chat: |
leaveChat |
| — |
banChatMember |
| Removes the member. There are no bans: they can come back if the community allows it |
restrictChatMember |
| Switches the member to "read only"; |
unbanChatMember | — | Does nothing and returns |
sendMediaGroup returns 400: send files one at a time or with the native API (up to 10 files per message). All other Telegram methods return 404 "Not Found: method not found".
Objects
Chat and identifiers
chat.idis the conversation'sthread_id(a number);message_idis the message'sseqin it.chat.type: a direct chat and a project request areprivate, a group issupergroup, a channel ischannel. There is nogrouptype.chat_idin requests is a number only; a channel's@usernameis not accepted.In a project request, the adapter acts on behalf of the project by itself: you do not need the
X-Tenant-IDheader.
User
id, is_bot, first_name and, if present, username. A person's id is their number in Sensever; a visitor in a project request gets a permanent number greater than 2^51 that reveals nothing about the person. There are no last_name, language_code or is_premium fields.
Message
Field | How it is filled |
|---|---|
| Always |
| Author; in a channel, |
| Text without markup. |
| Caption for files, without markup |
| The first file of the message, by content type: an image is |
| All files of the message (up to 10) in Sensever format, with |
| Poll: |
| The number shared with a |
| Only |
| Group topic |
| Edit time |
| The message's |
Update
The following types arrive: message, edited_message, channel_post, edited_channel_post, callback_query, message_reaction, poll_answer, inline_query, chosen_inline_result, my_chat_member, chat_member. Notes:
callback_query.chat_instanceis the conversation'sthread_id.message_reactiondescribes a single change:new_reactionwith one reaction if it was added, orold_reactionif it was removed. The person's full list of reactions is not passed.poll_answer.poll_idis the poll's<chat_id>_<message_id>;option_idsare zero-based option numbers.inline_query.offsetis always empty.The owner's test update arrives as an Update with only
update_id.
Keyboards and markup
reply_markup.inline_keyboard: buttons withcallback_data,urlorweb_app. Other kinds (switch_inline_query,login_url,pay,copy_text) return error400.reply_markup.keyboard: text buttons andrequest_contact;one_time_keyboardandinput_field_placeholderwork.resize_keyboard,is_persistent,selectivehave no effect; buttons withrequest_location,request_poll,request_usersorweb_appbecome plain text buttons.reply_markup.remove_keyboardremoves the keyboard;force_replyhas no effect.parse_mode:HTML,MarkdownV2,Markdownare converted to Sensever markup. Bold, italic, strikethrough, code, code block, link, spoiler and quote are supported. Underline is dropped while keeping the text; mentions viatg://user?id=and custom emoji are not supported.
Webhook in Telegram format
If the webhook is set through the adapter (setWebhook), updates arrive in Telegram Update format:
the body is a Telegram Update,
Content-Type: application/json;if
secret_tokenis set, it arrives in theX-Telegram-Bot-Api-Secret-Tokenheader; there is no Sensever signature (X-Sensever-Signature);ordering, retries and 24-hour retention work as with a regular webhook.
After deleteWebhook, or after setWebhook through the native API (PUT /v1/chat/bot/webhook), updates arrive in Sensever format again.
Errors
| When |
|---|---|
400 | Invalid parameters, conversation not found or not accessible, unsupported feature |
401 | Invalid or revoked token |
403 | Action not allowed: |
404 | The method does not exist or is not supported |
409 | Conflict, for example |
429 | Limit exceeded; wait for |
500, 503 | Temporary server error: |
Limits are the same as for the native API. In addition, the adapter accepts no more than 1200 requests per minute from one IP address; beyond that you get 429 in the same Telegram format, with parameters.retry_after.
Komentarze