Bot API: receiving updates
Everything the bot needs to know becomes an update in its own queue. Each update gets an update_id number that increases by one. The queue is read in two ways: with the getUpdates request (long polling) or through a webhook. Both work with the same queue, so switching from one to the other loses nothing.
How the queue works
Updates are kept for 24 hours. An update not received within that time expires (
expired) and isn't delivered.Order is preserved: updates arrive in ascending
update_idorder.An update doesn't contain a copy of the data made in advance. The message is read at delivery time, with the bot's permissions at that moment. If the message was deleted, hidden or restricted by an access policy, the bot was removed from the conversation, or an agent took the request, the update is skipped (
skipped) rather than delivered from a stale copy.A bot doesn't receive its own actions: its messages, edits and reactions don't create updates.
A person deleting a message is not an update (same as in Telegram).
If the bot owner's account is blocked, updates wait and expire after 24 hours.
If updates have expired, the bot owner gets a message about it once every 24 hours from the "Sensever Bots" service bot (@senseverbots_bot): how many updates were lost and the last webhook error, or a hint that the bot on getUpdates isn't running.
The Update object
Fields common to all updates:
Field | Type | Description |
|---|---|---|
| Integer | Update format version, currently |
| String | Update number, unique within the bot; the deduplication key |
| String | Update type, see below |
| String | When the update occurred, ISO 8601 |
| String | Number of the bot the update is addressed to |
Message updates (message, edited_message, channel_post, edited_channel_post, message_reaction, poll_answer, callback_query) also contain:
Field | Type | Description |
|---|---|---|
| String or null | Project number for a website visitor's request; |
| String | Conversation |
| String | Message number in the conversation |
| Message | The message in its current form, as |
Update types
| When it arrives | Additional field |
|---|---|---|
| A person messaged the bot in a direct chat; a visitor wrote in a project request; a group message the bot should hear | — |
| A person edited such a message | — |
| A post in a channel where the bot is a member | — |
| A post was edited | — |
| A person added or removed a reaction |
|
| A person voted in the bot's poll or retracted their vote |
|
| A person tapped an inline button on the bot's message |
|
| The bot was added to a group or channel, had its role changed or was removed |
|
| In a group or channel where the bot is an admin, someone joined, left or got a different role |
|
| A person typed |
|
| A person chose an inline query result |
|
| The owner clicked "Test delivery" | — |
Which messages the bot hears:
Direct chat. The person's text messages and messages with files (
kindtextormedia).Project request. The same from the visitor, while the request is open, isn't assigned to an agent, AI isn't paused, and the request isn't marked closed or spam. Staff replies on behalf of the project don't create updates.
Group. Messages from people. In privacy mode (the default) — only those addressed to the bot: a command (
/statusgoes to all bots in the group,/status@shop_botonly to this one), a@shop_botmention, or a reply to the bot's message. Messages from other bots don't arrive.Channel. Every post, including those from other bots, as
channel_post.
The reaction field
In the message_reaction update. In a direct chat and a project request, the bot receives reactions to any message in the conversation, including its own. In a group or channel, only an admin bot receives reactions.
Field | Type | Description |
|---|---|---|
| String | The reaction |
| Boolean |
|
| Principal | Who added or removed it |
The poll_answer field
In the poll_answer update; message is the poll itself. It arrives only for polls the bot sent, in direct chats, groups and channels.
Field | Type | Description |
|---|---|---|
| Array of String | Identifiers of the chosen options; an empty list means the vote was retracted |
| Principal | Who voted |
The callback_query field
In the callback_query update; message is the bot's message with the button.
Field | Type | Description |
|---|---|---|
| String | UUID of the tap; pass it to answerCallbackQuery |
| String |
|
| Principal | Who tapped |
The my_chat_member field
The my_chat_member update contains thread_id and my_chat_member, but not tenant_id, seq or message.
Field | Type | Description |
|---|---|---|
| Object |
|
| Principal or null | Who made the change |
| String | The bot's status before the change |
| String | The bot's status after the change |
Statuses: creator (owner), administrator, member, restricted (read-only), left (not a member). The "Author" role in a channel arrives as member.
The chat_member field
The chat_member update contains thread_id and chat_member: the same fields as my_chat_member, plus user (Principal) — whose role changed. It arrives only to an admin bot of the group or channel, and only while it is an admin.
The inline_query field
Field | Type | Description |
|---|---|---|
| String | UUID of the query; pass it to answerInlineQuery |
| Principal | Who is asking |
| String | Text after |
| String | Where the query was typed: |
The conversation in which the query was typed isn't disclosed to the bot: the bot may not be a member of it.
The chosen_inline_result field
Field | Type | Description |
|---|---|---|
| String |
|
| Principal | Who chose it |
| String | The original query |
The Principal object
A conversation participant: a person, a bot, a project or a channel.
Field | Type | Description |
|---|---|---|
| String |
|
| String |
|
| String | Name; a group member's hidden name is |
| String or null | Avatar; |
| String | Optional: name color |
| String | Optional, only for a sending bot in a project request: |
Example
{
"version": 2,
"update_id": "58",
"type": "callback_query",
"occurred_at": "2026-09-24T18:02:10+00:00",
"bot_id": "812",
"tenant_id": null,
"thread_id": "901",
"seq": "8",
"message": {"thread_id": "901", "seq": "8", "kind": "text", "text": "Confirm the order?", "payload": {"buttons": [[{"text": "Yes", "callback_data": "order:42:yes"}]]}, "...": "..."},
"callback_query": {
"id": "0b8f4c56-2f0e-4a51-9d7c-2d0e1c7a9e11",
"data": "order:42:yes",
"user": {"kind": "user", "ref": "p.1104", "display_name": "Anna", "avatar_url": null}
}
}getUpdates
GET /v1/chat/bot/updates?offset=58&limit=100&timeout=25Fetches updates from the queue. Not available while a webhook is set.
Parameter | Type | Required | Description |
|---|---|---|---|
| String | No | Acknowledges all updates with |
| Integer | No | From 1 to 100, 100 by default |
| Integer | No | Wait time in seconds (long polling), from 0 to 25; the default 0 means an immediate response |
| String | No | Comma-separated update types, for example |
Response: {"updates": [Update, …]} in ascending update_id order; an empty list if nothing arrived within timeout.
Updates that were returned but not acknowledged arrive again. Acknowledge them by passing offset in the next request.
If too many bots are waiting at once, the server responds immediately without waiting for timeout. Just repeat the request.
Errors: 409 webhook_active — a webhook is set; 409 polling_conflict — another getUpdates call for this bot is already running (don't run several copies of the bot with one token); 422 validation_failed — invalid parameters.
allowed_updates
Allowed types:
message,edited_message,message_reaction,poll_answer,callback_query,my_chat_member,chat_member,channel_post,edited_channel_post,inline_query,chosen_inline_result.The choice is saved for the bot and applies to both
getUpdatesand the webhook until it is changed. You can pass the parameter once.The filter is applied when an update occurs: updates that occurred before the list changed are either already in the queue or already left out of it.
An empty list means all types. Unlike Telegram, "all" includes
chat_memberandmessage_reaction.The
testupdate always arrives.
Webhook
With a webhook, Sensever sends each update to the bot's address as a POST request.
getWebhookInfo
GET /v1/chat/bot/webhookResponse — a WebhookInfo object:
Field | Type | Description |
|---|---|---|
| String or null | Webhook URL; |
| String |
|
| Integer | How many updates are waiting for delivery |
| Array of String or null | Selected types; |
| String or null | Time of the last successful delivery |
| String or null | Time of the last error |
| String or null | Code of the last error, for example |
setWebhook
PUT /v1/chat/bot/webhook{"url": "https://bot.example.com/sensever", "allowed_updates": ["message", "callback_query"], "drop_pending_updates": false}Parameter | Type | Required | Description |
|---|---|---|---|
| String | Yes | An HTTPS URL, up to 2048 characters |
| Array of String | No | Any of the 11 update types; an empty list means all types. Saved for the bot |
| Boolean | No |
|
Response: WebhookInfo. If the bot didn't have a webhook secret yet, the response includes it once in the webhook_secret field.
URL requirements: the https scheme, a domain name (not an IP address), port 443, no username or password in the URL and no #fragment, not localhost and not .local, .internal, .test or .invalid domains. All addresses the name resolves to must be public; this is checked on every delivery. A violation returns 422 webhook_destination_forbidden.
deleteWebhook
DELETE /v1/chat/bot/webhookSwitches the bot to getUpdates. The optional drop_pending_updates parameter (Boolean), in the body as {"drop_pending_updates": true} or in the query string, drops pending updates. Response: WebhookInfo.
How updates are delivered
Method
POST,Content-Type: application/json, the body is an Update object (up to 256 KB).Order is preserved: the bot has one update in flight; the next one waits until the previous one is delivered or expires.
Success is any
2xxresponse. The response body isn't read beyond 64 KB and has no meaning.The connection timeout is 2 seconds, and the whole response timeout is 5 seconds. Redirects aren't followed.
On error, the update is retried with pauses of 5, 10, 20, 40 seconds and so on, but no more than 10 minutes, until it expires after 24 hours. The error code is shown in
last_error_messageand in the delivery log:webhook_delivery_failed(no2xxresponse, timeout, TLS error),webhook_destination_forbidden(the address became non-public),webhook_dns_unavailable(the name doesn't resolve).A slow or failing webhook delays the bot's entire queue. Respond with
200right after saving the update, and process it after responding.
Headers and signature
POST /sensever HTTP/1.1
Content-Type: application/json
X-Sensever-Event-Id: 58
X-Sensever-Timestamp: 1790283730
X-Sensever-Signature: v1=5f2c…Header | Value |
|---|---|
| The update's |
| Time of this delivery attempt, Unix time in seconds |
|
|
The signed byte string is timestamp + "." + update_id + "." + request_body. The key is the bot's webhook_secret as is, a 64-character string (don't decode it from hex). Take the body exactly as received, before parsing JSON.
What to check on the bot server:
The signature, using a constant-time comparison (
hmac.compare_digest,crypto.timingSafeEqual).Freshness:
X-Sensever-Timestampis within ±5 minutes of your clock. It is the attempt time, so a repeated delivery of an old update also arrives with a fresh time.That
X-Sensever-Event-Idmatchesupdate_idin the body, and thatbot_idandversionare as expected.Duplicates: save the update with a unique key
(bot_id, update_id)and acknowledge a repeat without processing it again.
Verification example in Python:
import hashlib
import hmac
import time
def valid(raw_body: bytes, timestamp: str, update_id: str, signature: str, secret: str) -> bool:
signed = timestamp.encode() + b"." + update_id.encode() + b"." + raw_body
expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
fresh = timestamp.isdigit() and abs(time.time() - int(timestamp)) < 300
return fresh and hmac.compare_digest(expected, signature)In JavaScript:
import { createHmac, timingSafeEqual } from "node:crypto";
function valid(rawBody, timestamp, updateId, signature, secret) {
const expected = Buffer.from("v1=" + createHmac("sha256", secret)
.update(`${timestamp}.${updateId}.`).update(rawBody).digest("hex"));
const given = Buffer.from(String(signature ?? ""));
const fresh = /^\d+$/.test(timestamp ?? "") && Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
return fresh && given.length === expected.length && timingSafeEqual(given, expected);
}If the webhook was set with the Telegram-compatible setWebhook, updates arrive in Telegram format with the X-Telegram-Bot-Api-Secret-Token header instead of the Sensever signature — see "Bot API: Telegram-compatible adapter".
Delivery check and log
"Test delivery" in the bot menu (or
POST /v1/chat/bots/{id}/testby the owner) queues atestupdate with the common fields. It goes through the same webhook orgetUpdates."Delivery log" (
GET /v1/chat/bots/{id}/deliveries) shows the last 100 updates without their content: number, type, state, number of attempts, error code.
Update states: pending — waiting, delivered — delivered or acknowledged with offset, skipped — skipped because the bot can no longer read the message, expired — not received within 24 hours, dropped — dropped by drop_pending_updates. Completed updates are removed from the log after 7 days.
Комментарийлер