Bot API: receiving updates

SENSEVER

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

12 хв читання

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_id order.

  • 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

version

Integer

Update format version, currently 2

update_id

String

Update number, unique within the bot; the deduplication key

type

String

Update type, see below

occurred_at

String

When the update occurred, ISO 8601

bot_id

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

tenant_id

String or null

Project number for a website visitor's request; null for direct chats, groups and channels

thread_id

String

Conversation

seq

String

Message number in the conversation

message

Message

The message in its current form, as GET /v1/chat/threads/{thread_id}/messages/{seq} would return it

Update types

type

When it arrives

Additional field

message

A person messaged the bot in a direct chat; a visitor wrote in a project request; a group message the bot should hear

—

edited_message

A person edited such a message

—

channel_post

A post in a channel where the bot is a member

—

edited_channel_post

A post was edited

—

message_reaction

A person added or removed a reaction

reaction

poll_answer

A person voted in the bot's poll or retracted their vote

poll_answer

callback_query

A person tapped an inline button on the bot's message

callback_query

my_chat_member

The bot was added to a group or channel, had its role changed or was removed

my_chat_member

chat_member

In a group or channel where the bot is an admin, someone joined, left or got a different role

chat_member

inline_query

A person typed @bot_name query in any chat

inline_query

chosen_inline_result

A person chose an inline query result

chosen_inline_result

test

The owner clicked "Test delivery"

—

Which messages the bot hears:

  • Direct chat. The person's text messages and messages with files (kind text or media).

  • 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 (/status goes to all bots in the group, /status@shop_bot only to this one), a @shop_bot mention, 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

emoji

String

The reaction

added

Boolean

true — added, false — removed

user

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

option_ids

Array of String

Identifiers of the chosen options; an empty list means the vote was retracted

user

Principal

Who voted

The callback_query field

In the callback_query update; message is the bot's message with the button.

Field

Type

Description

id

String

UUID of the tap; pass it to answerCallbackQuery

data

String

callback_data of the tapped button

user

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

chat

Object

thread_id, kind (group or channel), title

from

Principal or null

Who made the change

old_status

String

The bot's status before the change

new_status

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

id

String

UUID of the query; pass it to answerInlineQuery

from

Principal

Who is asking

query

String

Text after @bot_name, up to 256 characters

chat_type

String

Where the query was typed: private, supergroup (group) or channel

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

result_id

String

id of the chosen result

from

Principal

Who chose it

query

String

The original query

The Principal object

A conversation participant: a person, a bot, a project or a channel.

Field

Type

Description

kind

String

user — a person, bot — a bot, tenant — a project, thread — a channel (the author of channel posts)

ref

String

p.<number>; a visitor in a project request is tu1.<43 characters>

display_name

String

Name; a group member's hidden name is User

avatar_url

String or null

Avatar; null for visitors in project requests

name_color

String

Optional: name color #rrggbb, if the person chose one

tenant_ref

String

Optional, only for a sending bot in a project request: p.<project number>

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=25

Fetches updates from the queue. Not available while a webhook is set.

Parameter

Type

Required

Description

offset

String

No

Acknowledges all updates with update_id lower than this value: they won't be returned again. Usually the number of the last received update plus one

limit

Integer

No

From 1 to 100, 100 by default

timeout

Integer

No

Wait time in seconds (long polling), from 0 to 25; the default 0 means an immediate response

allowed_updates

String

No

Comma-separated update types, for example message,callback_query. An empty string means all types. The choice is saved for the bot, see below

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 getUpdates and 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_member and message_reaction.

  • The test update always arrives.

Webhook

With a webhook, Sensever sends each update to the bot's address as a POST request.

getWebhookInfo

GET /v1/chat/bot/webhook

Response — a WebhookInfo object:

Field

Type

Description

url

String or null

Webhook URL; null means the bot uses getUpdates

delivery

String

webhook or polling

pending_update_count

Integer

How many updates are waiting for delivery

allowed_updates

Array of String or null

Selected types; null means all

last_success_date

String or null

Time of the last successful delivery

last_error_date

String or null

Time of the last error

last_error_message

String or null

Code of the last error, for example webhook_delivery_failed

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

url

String

Yes

An HTTPS URL, up to 2048 characters

allowed_updates

Array of String

No

Any of the 11 update types; an empty list means all types. Saved for the bot

drop_pending_updates

Boolean

No

true drops updates waiting for delivery

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/webhook

Switches 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 2xx response. 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_message and in the delivery log: webhook_delivery_failed (no 2xx response, 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 200 right 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

X-Sensever-Event-Id

The update's update_id

X-Sensever-Timestamp

Time of this delivery attempt, Unix time in seconds

X-Sensever-Signature

v1= followed by the HMAC-SHA256 in hexadecimal

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:

  1. The signature, using a constant-time comparison (hmac.compare_digest, crypto.timingSafeEqual).

  2. Freshness: X-Sensever-Timestamp is 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.

  3. That X-Sensever-Event-Id matches update_id in the body, and that bot_id and version are as expected.

  4. 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}/test by the owner) queues a test update with the common fields. It goes through the same webhook or getUpdates.

  • "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.

Коментарі

Автори