Bot API: Telegram-compatible adapter

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

9 মিনিটে পড়া

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: GET or POST to https://api.sensever.com/bot<token>/<method>. Method names are case-insensitive.

  • Parameters go in the query string, a form (application/x-www-form-urlencoded or multipart/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 with bot_id 812 and token b1.AbC…, it is 812:AbC…. Such a token passes the format check in libraries. The b1.… token itself is accepted too.

  • Response: {"ok": true, "result": …} or {"ok": false, "error_code": 400, "description": "Bad Request: …"}; on 429 and on a temporary server error (500, 503), "parameters": {"retry_after": N} is added.

Library

Setup

aiogram 3

Bot(token, session=AiohttpSession(api=TelegramAPIServer.from_base("https://api.sensever.com")))

python-telegram-bot

Application.builder().token(token).base_url("https://api.sensever.com/bot").base_file_url("https://api.sensever.com/file/bot").build()

grammY

new Bot(token, { client: { apiRoot: "https://api.sensever.com" } })

Telegraf

new Telegraf(token, { telegram: { apiRoot: "https://api.sensever.com" } })

Any HTTP client

POST https://api.sensever.com/bot812:AbC…/sendMessage

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 id, is_bot, first_name, username, can_join_groups (always true), can_read_all_group_messages (whether privacy mode is off), supports_inline_queries

getUpdates

offset, limit (1–100), timeout (0–25), allowed_updates

Negative offset is not supported; unknown types in allowed_updates are dropped

setWebhook

url, secret_token, allowed_updates, drop_pending_updates

An empty url is the same as deleteWebhook. certificate, ip_address, max_connections have no effect

deleteWebhook

drop_pending_updates

Returns the bot to getUpdates and to the Sensever update format

getWebhookInfo

—

url, has_custom_certificate (false), pending_update_count, last_error_date, last_error_message, allowed_updates

Messages

Method

Supported parameters

Notes

sendMessage

chat_id, text, parse_mode, reply_markup, reply_parameters.message_id or reply_to_message_id, message_thread_id, disable_notification, disable_web_page_preview or link_preview_options.is_disabled

entities are not supported: use parse_mode

sendPhoto, sendDocument, sendVideo, sendAudio, sendVoice, sendAnimation

chat_id, file, caption, parse_mode, reply_markup, reply_parameters.message_id or reply_to_message_id, disable_notification

The file is a file_id, an https://… link or the file itself in multipart/form-data, up to 20 MB (attach://name works too). The file kind in the response is determined by its content type, not by the method. message_thread_id is not supported

sendPoll

chat_id, question, options (strings or {"text": …})

Only a regular single-answer poll: allows_multiple_answers: true and type: "quiz" return error 400. Polls are never anonymous

editMessageText

chat_id, message_id, text, parse_mode, reply_markup

Without reply_markup, inline buttons are removed. inline_message_id is not supported

editMessageReplyMarkup

chat_id, message_id, reply_markup

Only the bot's own messages

deleteMessage

chat_id, message_id

Other people's messages only in a group or channel where the bot is an admin

sendChatAction

chat_id

Any action shows "typing…" for 5 seconds — both in the chat and to a visitor in the website widget

setMessageReaction

chat_id, message_id, reaction

The list replaces the bot's reactions on the message; an empty list removes all of them. Only {"type": "emoji", "emoji": …}

getFile

file_id

file_path is the same as file_id. The file is downloaded from https://api.sensever.com/file/bot<token>/<file_path>: the response is a redirect to a link valid for 5 minutes

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

callback_query_id, text, show_alert, url

Once, within 15 minutes

answerInlineQuery

inline_query_id, results

Only InlineQueryResultArticle with input_message_content.message_text

setMyCommands

commands, scope, language_code

scope: default and all_private_chats; others return error 400

getMyCommands, deleteMyCommands

scope, language_code

—

setMyDescription, getMyDescription

description

One description for all languages: language_code has no effect

setMyShortDescription, getMyShortDescription

short_description

Same

Groups and channels

Method

Supported parameters

Notes

getChat

chat_id

Chat: id, type, first_name or title, username of a channel or group with an address

leaveChat

chat_id

—

banChatMember

chat_id, user_id

Removes the member. There are no bans: they can come back if the community allows it

restrictChatMember

chat_id, user_id

Switches the member to "read only"; permissions are not parsed

unbanChatMember

—

Does nothing and returns true: there are no bans

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.id is the conversation's thread_id (a number); message_id is the message's seq in it.

  • chat.type: a direct chat and a project request are private, a group is supergroup, a channel is channel. There is no group type.

  • chat_id in requests is a number only; a channel's @username is not accepted.

  • In a project request, the adapter acts on behalf of the project by itself: you do not need the X-Tenant-ID header.

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

message_id, date, chat

Always

from

Author; in a channel, sender_chat (the channel itself) is used instead

text

Text without markup. entities are not passed

caption

Caption for files, without markup

photo, video, audio, voice, document

The first file of the message, by content type: an image is photo (one size), a GIF is document, audio/ogg is voice

sensever_attachments

All files of the message (up to 10) in Sensever format, with file_id

poll

Poll: id in the form <chat_id>_<message_id>, question, options with voter_count, is_anonymous: false, type: "regular"

contact

The number shared with a request_contact button: phone_number, first_name, user_id

reply_to_message

Only message_id, chat and date (the date of this message, not the original one)

message_thread_id

Group topic

edit_date

Edit time

reply_markup

The message's inline_keyboard

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_instance is the conversation's thread_id.

  • message_reaction describes a single change: new_reaction with one reaction if it was added, or old_reaction if it was removed. The person's full list of reactions is not passed.

  • poll_answer.poll_id is the poll's <chat_id>_<message_id>; option_ids are zero-based option numbers.

  • inline_query.offset is always empty.

  • The owner's test update arrives as an Update with only update_id.

Keyboards and markup

  • reply_markup.inline_keyboard: buttons with callback_data, url or web_app. Other kinds (switch_inline_query, login_url, pay, copy_text) return error 400.

  • reply_markup.keyboard: text buttons and request_contact; one_time_keyboard and input_field_placeholder work. resize_keyboard, is_persistent, selective have no effect; buttons with request_location, request_poll, request_users or web_app become plain text buttons.

  • reply_markup.remove_keyboard removes the keyboard; force_reply has no effect.

  • parse_mode: HTML, MarkdownV2, Markdown are converted to Sensever markup. Bold, italic, strikethrough, code, code block, link, spoiler and quote are supported. Underline is dropped while keeping the text; mentions via tg://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_token is set, it arrives in the X-Telegram-Bot-Api-Secret-Token header; 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

error_code

When

400

Invalid parameters, conversation not found or not accessible, unsupported feature

401

Invalid or revoked token

403

Action not allowed: description in the form Forbidden: <Sensever code>

404

The method does not exist or is not supported

409

Conflict, for example Conflict: webhook_active for getUpdates when a webhook is set

429

Limit exceeded; wait for parameters.retry_after

500, 503

Temporary server error: description in the form Internal Server Error: <code>; retry the request (libraries do this automatically)

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.

মন্তব্য

লেখকগণ