Bot API: basics

SENSEVER

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

8 min de lectura

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

https://api.sensever.com/v1/chat

Telegram-compatible Bot API

https://api.sensever.com/bot<token>/<method>

File downloads in Telegram format

https://api.sensever.com/file/bot<token>/<file_path>

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.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The 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: 42

The 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 returns 422 validation_failed; unparsable JSON returns 400 invalid_json.

  • Call methods documented without a body (DELETE on a message) with no body or with {}.

  • In many methods, an unknown field in the body is a 422 validation_failed error with details.fields. Don't send extra fields.

  • GET parameters 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 data field: {"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

thread_id

A conversation: a direct chat, a project request, a group or a channel

seq

The message number within a conversation; it increases with every message

update_id

The update number in the bot's queue, unique within the bot

p.<number>

A reference to a participant: a person or a bot (for example, p.1104)

tu1.<43 characters>

An opaque reference to a visitor in a project request

bot_id

The bot's number as a participant (p.<bot_id>)

The owner's bot id

The UUID of the bot record in the owner API; don't confuse it with bot_id

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

error.code

What it means and what to do

400

invalid_json

The body can't be parsed as JSON

401

unauthenticated

No token, the token is wrong or was replaced, or the bot was deleted

403

forbidden

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 X-Tenant-ID is wrong

403

blocked

The person blocked the bot, or the bot blocked the person

403

buttons_bots_only

Only a bot can attach buttons and keyboards

404

not_found

The conversation, message or object doesn't exist, or the bot can't see it

409

conversation_owned

An agent has taken the project request, it is closed, or AI is paused: the bot no longer replies in it

409

webhook_active

getUpdates isn't available while a webhook is set

409

polling_conflict

Another getUpdates call for this bot is already running

409

callback_already_answered_or_expired

The button tap has already been answered or 15 minutes have passed

409

inline_query_already_answered_or_expired

The inline query has already been answered or 15 minutes have passed

409

reaction_limit

The message has too many reactions

410

message_purged

A message with this client_message_id was sent and has already been permanently deleted

413

request_too_large

The body is larger than 256 KB

422

validation_failed

Invalid parameters; details are in details.fields

422

invalid_file_id

The file_id is corrupted or forged

422

file_download_failed

The file couldn't be downloaded from the link

422

webhook_destination_forbidden

The webhook URL isn't allowed: not HTTPS, not port 443, an IP instead of a name, or a local or private address

422

unknown_button

A button that isn't in the message was tapped

422

reaction_not_allowed

The reaction isn't in the GET /v1/chat/reactions list

422

unsupported_reaction_type

The reaction type isn't supported: only {"type": "emoji"} for now

429

rate_limited

The request limit was exceeded; see below

503

service_unavailable

Temporary failure; retry after Retry-After seconds

Exceeding limits

A 429 response comes in two forms:

  • any limit — the general one, the sending one or a per-method one (for example, getUpdates or webhook changes) — returns error.code: "rate_limited", a Retry-After header and the same number of seconds in error.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

GET /v1/chat/bot/me

getMe

getUpdates

GET /v1/chat/bot/updates

getUpdates

getWebhookInfo

GET /v1/chat/bot/webhook

getWebhookInfo

setWebhook

PUT /v1/chat/bot/webhook

setWebhook

deleteWebhook

DELETE /v1/chat/bot/webhook

deleteWebhook

Messages and files

Method

Request

Telegram equivalent

Send a message

POST /v1/chat/threads/{thread_id}/messages

sendMessage, sendPhoto, sendDocument, sendPoll

Read a message

GET /v1/chat/threads/{thread_id}/messages/{seq}

—

Read history

GET /v1/chat/threads/{thread_id}/messages

—

Edit your own message

PATCH /v1/chat/threads/{thread_id}/messages/{seq}

editMessageText, editMessageReplyMarkup

Delete a message

DELETE /v1/chat/threads/{thread_id}/messages/{seq}

deleteMessage

Add or remove a reaction

PUT /v1/chat/threads/{thread_id}/messages/{seq}/reactions

setMessageReaction

Allowed reactions

GET /v1/chat/reactions

—

"Typing…"

POST /v1/chat/threads/{thread_id}/typing

sendChatAction

Reserve a file upload

POST /v1/chat/uploads

—

Upload a file from a link

POST /v1/chat/threads/{thread_id}/uploads/url

sending a file by URL

Conversation

GET /v1/chat/threads/{thread_id}

getChat

Read statuses

GET /v1/chat/threads/{thread_id}/receipts

—

Buttons, commands, profile

Method

Request

Telegram equivalent

Answer a button tap

POST /v1/chat/bot/callbacks/{id}/answer

answerCallbackQuery

Set commands

PUT /v1/chat/bot/commands

setMyCommands

Read commands

GET /v1/chat/bot/commands

getMyCommands

Delete commands

DELETE /v1/chat/bot/commands

deleteMyCommands

Read the profile

GET /v1/chat/bot/profile

getMyDescription, getMyShortDescription

Change the description

PUT /v1/chat/bot/profile

setMyDescription, setMyShortDescription

Groups, channels, inline mode

Method

Request

Telegram equivalent

Change a member's role or remove them

PUT /v1/chat/threads/{thread_id}/community/members

banChatMember, restrictChatMember

Leave a group or channel

POST /v1/chat/threads/{thread_id}/leave

leaveChat

Answer an inline query

POST /v1/chat/bot/inline-queries/{id}/answer

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

Autores