Sensever bots: features and limits

SENSEVER

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

6 min read

Sensever bots: features and limits

A reference for anyone designing a bot: how much is allowed, what the bot sees, and how to protect the bot and people. All numbers are current platform limits.

Owner and bots

What

Limit

Who can create a bot

A person with a Sensever account and a verified email or phone number; otherwise 403 bot_owner_unverified

How many bots

Up to 20 active bots per person; deleted bots do not count. Beyond that: 409 bot_limit_reached

Username

5–32 characters: a Latin letter first, then Latin letters, digits and single _, ending in _bot. Converted to lowercase

Username availability

A username is unique across bots, people and channel addresses. A deleted bot's username is not released. The reserved names sensever_bot, eva_bot, leo_bot, leia_bot, senseverbots_bot, senseverflow_bot are taken

The _bot ending

Bots only: people and channels cannot take such a name (reserved_username, reserved_slug)

Bot name

1–128 characters

Token

b1. plus 43 characters. Shown once; a new token disables the old one immediately

Webhook secret

64 hexadecimal characters. Changes together with the token

If the owner's account is blocked, the bot stops working: the API does not respond, updates are not delivered and expire after 24 hours.

Updates

What

Limit

Update retention

24 hours; then expired

Delivery log

The last 100 updates; completed ones are deleted after 7 days

getUpdates

limit up to 100, timeout up to 25 seconds; one concurrent request per bot

Webhook

HTTPS, port 443, a domain name, a public address, no redirects

Webhook response time

2 seconds to connect, 5 seconds to respond

Update size

Up to 256 KB

Delivery retries

5 s, 10 s, 20 s … at least once every 10 minutes until the update expires

allowed_updates

Any of the 11 update types; an empty list means all

Messages

What

Limit

Text

Up to 16,384 characters

Files per message

Up to 10

File size

Up to 2 GB; over 50 MB only via tus upload

File from a URL

https only, a public address, up to 20 MB

File in a Telegram-compatible request

Up to 20 MB

File links in a message

Temporary, valid for minutes; read the message again to get new ones

Mentions

Up to 100 per message

Reaction

Up to 64 characters; up to 12 reactions per member on a message; up to 32 distinct reactions per message

Poll

Question up to 500 characters, 2–10 options of up to 200 characters, a single answer

Request body

Up to 256 KB of JSON

Subscribers by email or phone

Up to 1,000 new addresses per 10 minutes per bot (an address already looked up is remembered for 10 minutes and does not count), and up to 300 "not a subscriber" answers per hour. Beyond that: 429 rate_limited with Retry-After (Telegram format: retry_after)

Buttons, commands, profile

What

Limit

Inline buttons

Up to 8 rows of 8 buttons; label up to 64 characters; callback_data up to 64 bytes; link up to 2048 characters

Answer to a tap

Once, within 15 minutes; text up to 200 characters. The person waits up to 10 seconds for the answer

Keyboard below the input field

Up to 12 rows of 8 buttons; label up to 64 characters; placeholder up to 64 characters

Commands

Up to 100 in a list; a command is 1–32 characters of [a-z0-9_]; description 1–256 characters

Description

Up to 512 characters

Short description

Up to 120 characters

Avatar

JPEG, PNG or WebP, up to 10 MB and up to 20 megapixels

start parameter

1–64 characters of [A-Za-z0-9_-]

Inline query

Up to 256 characters; answer with up to 50 results, once, within 15 minutes; the person waits up to 8 seconds

Inline query result

id up to 64 bytes, title up to 256, description up to 512, text up to 4096 characters

Inline mode placeholder

Up to 64 characters

Rate limits

Limits are counted per bot per minute unless stated otherwise.

What

Limit

All API requests

600 per minute

Sending messages

120 per minute and 60 per minute per conversation

Editing and deleting messages

120 per minute and 60 per minute per conversation

Uploading files

120 per minute and 60 per minute per conversation

getUpdates

120 per minute

setWebhook, deleteWebhook

20 per minute

"Typing…"

120 per minute; no more than 2 times per 2 seconds per conversation

Answers to taps and inline queries

120 per minute each

Changing commands and descriptions

30 per minute each

File from a URL

30 per minute

Telegram-compatible adapter

An additional 1200 requests per minute from one IP address; file downloads, 600 per minute

When a limit is exceeded, you get 429. How to find out how long to wait is described in "Bot API: basics", section "Exceeding limits".

What the bot sees

  • Direct chat: everything the person writes, their edits, reactions, taps and votes.

  • Project request: the visitor's messages until an agent takes the request. The visitor is anonymous: tu1.… instead of an account number, no avatar. Once an agent has taken the request, the bot no longer reads or writes in it.

  • Group: in privacy mode, only messages addressed to the bot; without it, all messages from people. The bot reads group history as a member, from the moment it joined, regardless of privacy mode.

  • Channel: all posts.

  • Inline mode: only the query text, the author and the chat type, but not the chat itself.

  • Phone number: only if the person tapped the request_contact button and confirmed sending; the number is verified in the Sensever account.

The bot does not see: people's chat lists and contacts, conversations it is not a member of, messages hidden by an access policy, deleted messages. Permissions are checked when each update is delivered and on every request: if the bot was removed, updates about past messages are skipped.

What the bot cannot do

  • Start a conversation: write to a person who has not opened a chat with the bot, or create a group.

  • Edit other people's messages — even as an admin.

  • Vote in polls, bookmark messages or hide messages.

  • Appoint admins or change the owner's role.

  • Manage a project, widget settings or other bots.

  • Reply in a request an agent has taken.

Security

For the bot server

  • Keep the token and webhook secret on the server only. Do not put them in page code, mobile apps or Mini Apps. If they leak, issue a new token — the webhook secret changes with it.

  • Verify the webhook signature against the raw body bytes and reject requests whose X-Sensever-Timestamp is more than ±5 minutes off. See the example in "Bot API: receiving updates".

  • Store updates with the unique key (bot_id, update_id): delivery may repeat.

  • Send messages with a client_message_id that stays the same on retry, so a network failure does not create a duplicate.

  • Verify Mini App data on the server: the hash signature and the freshness of auth_date.

  • Store identifiers as strings: they do not fit into JavaScript numbers.

  • Do not work around refusals. A 409 conversation_owned, 403 or 401 response is a signal to stop, not to retry the request another way.

For people

  • The bot sees only what a member in its place would see, and only while it is a member.

  • In groups with a bot that has privacy mode off, members see the label "Bot · sees all messages".

  • A message sent through inline mode is marked "via @bot"; the marker cannot be forged or removed.

  • A person can block the bot: the bot stops receiving updates from this person and cannot write to them (403 blocked).

Comments

Authors