Bot API: basics
The Bot API is the HTTP interface through which a bot server receives updates and acts in Sensever. This article describes the general rules: URLs, authorization, request and response formats, errors and the full list of methods. The methods are described in detail in the articles of the "Bot API" series.
URLs
API | Base URL |
|---|---|
Native Sensever Bot API |
|
Telegram-compatible Bot API |
|
File downloads in Telegram format |
|
Bots and API keys share one address, https://api.sensever.com. Paths in these articles are written in full, for example GET /v1/chat/bot/me means https://api.sensever.com/v1/chat/bot/me. The old sensever.com/api addresses no longer accept bot tokens: they answer 404 with the new address.
All requests use HTTPS only. This article and the "Bot API" articles below describe the native API; the Telegram-compatible one is described separately.
Authorization
The bot token is passed in a header:
Authorization: Bearer b1.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXThe token consists of the b1. prefix and 43 characters from [A-Za-z0-9_-]. It is issued when the bot is created and when a new token is issued. The old token stops working as soon as a new one is issued or the bot is deleted: the response is 401 unauthenticated.
The bot token opens only the bot API. Creating and configuring bots (name, webhook URL, avatar, privacy, new token) is done by the owner in the Sensever interface or with their own user session — see "Sensever bots: bot management and the owner API". API keys from a Sensever account can't manage bots.
Project requests: the X-Tenant-ID header
When a bot is chosen as a project assistant and replies to a website visitor, requests about that conversation pass the project number:
X-Tenant-ID: 42The number arrives in the update in the tenant_id field. For direct chats, groups and channels, tenant_id is null and the header isn't sent. The /v1/chat/bot/* methods (the bot itself, updates, webhook, commands, profile, answers to buttons and inline queries) are called without the header.
With the header, the bot acts on behalf of the project: the request succeeds only while the bot is selected and enabled as this project's assistant and no agent has taken the request yet. Otherwise you get 403 forbidden or 409 conversation_owned.
Requests
The request body is a JSON object (
Content-Type: application/json), no larger than 256 KB. An array or other JSON instead of an object returns422 validation_failed; unparsable JSON returns400 invalid_json.Call methods documented without a body (
DELETEon a message) with no body or with{}.In many methods, an unknown field in the body is a
422 validation_failederror withdetails.fields. Don't send extra fields.GETparameters go in the query string.
Responses
A successful response is JSON with code 200 or 201, or an empty 204 No Content response. The shape depends on the method:
bot methods (
/v1/chat/bot/*) return the object directly:{"id":"812","username":"shop_bot",…};message and conversation methods return the object in the
datafield:{"data":{…message…},"replayed":false};history returns
{"messages":[…],"pending":[…],"page":{…}}.
Every response has an X-Request-ID header — include it when you contact support.
Identifiers
All numeric identifiers — update_id, thread_id, seq, bot_id, tenant_id, topic_id, size_bytes — are passed as strings. They can exceed 2^53 and lose precision in JavaScript. Store them as strings or parse them with BigInt.
Identifier | What it identifies |
|---|---|
| A conversation: a direct chat, a project request, a group or a channel |
| The message number within a conversation; it increases with every message |
| The update number in the bot's queue, unique within the bot |
| A reference to a participant: a person or a bot (for example, |
| An opaque reference to a visitor in a project request |
| The bot's number as a participant ( |
The owner's bot | The UUID of the bot record in the owner API; don't confuse it with |
Time
Time is an ISO 8601 string in UTC: 2026-09-24T18:00:00.000000Z in message objects, 2026-09-24T18:00:00+00:00 in update fields and webhook state.
Errors
An error is JSON with an HTTP 4xx or 5xx code:
{
"error": {
"code": "not_found",
"message": "not found",
"request_id": "151a7ab4-43e5-4ef6-ad7e-b86fd681b60d",
"details": {}
}
}Your program should rely on error.code, not on message. Common codes:
HTTP |
| What it means and what to do |
|---|---|---|
400 |
| The body can't be parsed as JSON |
401 |
| No token, the token is wrong or was replaced, or the bot was deleted |
403 |
| The bot can't do this in this conversation: it isn't a member, it lacks the role, the message belongs to someone else, or |
403 |
| The person blocked the bot, or the bot blocked the person |
403 |
| Only a bot can attach buttons and keyboards |
404 |
| The conversation, message or object doesn't exist, or the bot can't see it |
409 |
| An agent has taken the project request, it is closed, or AI is paused: the bot no longer replies in it |
409 |
|
|
409 |
| Another |
409 |
| The button tap has already been answered or 15 minutes have passed |
409 |
| The inline query has already been answered or 15 minutes have passed |
409 |
| The message has too many reactions |
410 |
| A message with this |
413 |
| The body is larger than 256 KB |
422 |
| Invalid parameters; details are in |
422 |
| The |
422 |
| The file couldn't be downloaded from the link |
422 |
| The webhook URL isn't allowed: not HTTPS, not port 443, an IP instead of a name, or a local or private address |
422 |
| A button that isn't in the message was tapped |
422 |
| The reaction isn't in the |
422 |
| The reaction type isn't supported: only |
429 |
| The request limit was exceeded; see below |
503 |
| Temporary failure; retry after |
Exceeding limits
A 429 response comes in two forms:
any limit — the general one, the sending one or a per-method one (for example,
getUpdatesor webhook changes) — returnserror.code: "rate_limited", aRetry-Afterheader and the same number of seconds inerror.details.retry_after. Wait the specified time and retry the request.
The limits are listed in "Sensever bots: features and limits".
Retries
Retry the request after 429, 503 and network errors. Retry sending a message with the same client_message_id: the server returns the already created message with "replayed": true and code 200 instead of a second message. Don't retry unchanged requests that returned 400, 401, 403, 404, 409 or 422.
All methods
Bot and updates
Method | Request | Telegram equivalent |
|---|---|---|
getMe |
| getMe |
getUpdates |
| getUpdates |
getWebhookInfo |
| getWebhookInfo |
setWebhook |
| setWebhook |
deleteWebhook |
| deleteWebhook |
Messages and files
Method | Request | Telegram equivalent |
|---|---|---|
Send a message |
| sendMessage, sendPhoto, sendDocument, sendPoll |
Read a message |
| — |
Read history |
| — |
Edit your own message |
| editMessageText, editMessageReplyMarkup |
Delete a message |
| deleteMessage |
Add or remove a reaction |
| setMessageReaction |
Allowed reactions |
| — |
"Typing…" |
| sendChatAction |
Reserve a file upload |
| — |
Upload a file from a link |
| sending a file by URL |
Conversation |
| getChat |
Read statuses |
| — |
Buttons, commands, profile
Method | Request | Telegram equivalent |
|---|---|---|
Answer a button tap |
| answerCallbackQuery |
Set commands |
| setMyCommands |
Read commands |
| getMyCommands |
Delete commands |
| deleteMyCommands |
Read the profile |
| getMyDescription, getMyShortDescription |
Change the description |
| setMyDescription, setMyShortDescription |
Groups, channels, inline mode
Method | Request | Telegram equivalent |
|---|---|---|
Change a member's role or remove them |
| banChatMember, restrictChatMember |
Leave a group or channel |
| leaveChat |
Answer an inline query |
| answerInlineQuery |
The bot token opens no other routes: a call outside this list returns 403 forbidden. A bot doesn't create conversations, vote in polls, add bookmarks or manage a project.
Comentarios