SMeet Bot API

API reference

The reference below the first sections is generated from the machine-readable contract, which you can also download as openapi.json. Method names, JSON fields and error codes are the same in every language of this documentation.

Requests#

• Base URL: https://messenger.scrile.com/bot-api/v1. A method is called as POST https://messenger.scrile.com/bot-api/v1/<method> with a JSON body in UTF-8 and Content-Type: application/json.
• Read-only methods (getMe, getMyCommands, getFile, getDeliveryInfo, getWebhookInfo) also accept GET with query parameters.
• uploadFile takes multipart/form-data. File bytes are downloaded with GET /files/<file_id>/content.
• A request body may be at most 21 MiB; a larger one is refused with 413 PAYLOAD_TOO_LARGE and limit in bytes before it is read.
• A path that is not a method answers 404 METHOD_NOT_FOUND.

Authentication#

Every call carries the bot token in a header:

POST /bot-api/v1/getUpdates HTTP/1.1
Host: messenger.scrile.com
Authorization: Bearer sbt1_EXAMPLE_REPLACE_WITH_YOUR_TOKEN
Content-Type: application/json

A missing, malformed, unknown or revoked token, or the token of a deleted bot, gets the same answer: 401 INVALID_TOKEN with the header WWW-Authenticate: Bearer. A request that was already on its way when the bot was deleted may get 404 BOT_NOT_FOUND instead; the token does not work after that either. The token is never accepted in the URL, and SMeet never sends it anywhere, including your webhook.

Answers and errors#

Every answer is JSON. A success:

{"ok": true, "result": {"message_id": "7301", "chat": {"id": "550", "type": "private"}}}

A failure has a matching HTTP status and this shape:

{
  "ok": false,
  "error": {"code": "RATE_LIMITED", "message": "Too many requests; wait retry_after seconds", "retry_after": 2},
  "request_id": "3f1c2a7e-8b1d-4c52-9a55-0c7e1f7a1b90"
}

• error.code is stable and is what your program checks. error.message is English text for people; do not parse it.
• retry_after (seconds) is present only when a retry makes sense, and then the Retry-After header carries the same value. SMeet sends it with every 429 and 503, and with every 409 CONSUMER_CONFLICT and 409 FILE_NOT_READY.
• Some codes add fields to error: field names the parameter at fault with INVALID_REQUEST, confirmed_offset and max_issued_update_id come with the offset errors, reason with FILE_REJECTED, limit (the largest accepted size in bytes) with PAYLOAD_TOO_LARGE.
• request_id, also sent as the X-Request-Id header, identifies the request. Quote it when you contact support.
• The proxy in front of the API answers its own limits in the same shape: 429 RATE_LIMITED with retry_after 1, and 413 PAYLOAD_TOO_LARGE, both with an empty request_id. The proxy's 413 may come without limit.

Every code with its HTTP status is in the table of error codes.

Identifiers#

All identifiers (update_id, chat_id, message_id, epoch, offsets) are decimal strings of up to 20 digits. They can exceed 2^53, so never convert them to floating point numbers; you never need arithmetic on them either, because the server returns next_offset with every batch. file_id and the id of a callback query are opaque strings, and event_id is a UUID.

Idempotency-Key#

Methods that change something take an Idempotency-Key header: 1 to 128 characters of A-Z a-z 0-9 . _ : -.

• Same key, same parameters: the result of the first call comes back, and nothing is done twice. Before answering, SMeet checks the token and the chat again, so a repeat after the user pressed Stop fails with BOT_STOPPED_OR_BLOCKED.
• Same key, other parameters: 409 IDEMPOTENCY_CONFLICT. Parameters are compared as JSON, so key order and spacing do not matter.
• A failure before the action (FILE_NOT_READY, 429, 503, a validation error) does not use up the key. Repeat the same request with the same key.
• A repeat that arrives while the first call is still running waits for it, at most 2 seconds, and then returns its result; after 2 seconds it gets 503 TEMPORARILY_UNAVAILABLE with retry_after 1.
• A conditional request repeated with the same key and body returns the result of the first success without checking the chat and the conditions again: they were checked together with the first call. So an outbox learns the outcome within the 7 days even after a Stop. A conditional repeat with another value of a condition is another body: 409 IDEMPOTENCY_CONFLICT. A refusal, a conflict included, uses up no key.
• Keys belong to one bot and one method: the same key in sendMessage and in editMessageText are two different keys. uploadFile keys are unique per bot. SMeet keeps keys for 7 days.

Build keys from the update you are answering and the action, for example <event_id>:reply: a repeated or replayed update then produces the same key, and SMeet returns the reply it already sent. Your own side effects (a database row, a payment) need the same protection on your side, keyed by event_id (Deduplication).

Capabilities#

getMe lists in capabilities what this server promises beyond version 1.1.0. Skip values you do not know.

A server that promises none of them answers getMe without capabilities, as version 1.1.0 did. Rules for your program:

1. Send a condition only when its value is in capabilities of the last getMe. A server without it does not check the condition: an older server skips the parameter silently and performs the action without the condition, and a 1.2.0 server with conditions switched off refuses the call with 400 INVALID_REQUEST and the parameter in field, without performing it.
2. Call getMe when you start and at least every 5 minutes; at once after 404 METHOD_NOT_FOUND from getChatContext or setMyConditionsMode, after an answer of rule 3 and after an update of rule 5.
3. Every success of a 1.2.0 server to sendMessage, sendPhoto, sendDocument, editMessageText, deleteMessage, pinChatMessage, unpinChatMessage and restrictChatMember carries result.chat.access_revision, also the answer to a repeat by key. Without it the conditions were not checked: stop the actions that depend on them and tell an operator.
4. After any time without the capability (the server rolled back, the platform switched conditions off), treat every stored revision as invalid: the older code may have changed access and messages without new revisions.
5. A fresh update with a chat but without chat.access_revision while access_revisions is listed means the server rolled back: call getMe at once and apply rule 4. Fresh means a date later than the moment you first saw the capability, with a margin for clock drift. Replays from FAILED and updates without a chat are no such sign.

Conditional requests#

A changing call can carry conditions. The server checks them and performs the action in one transaction: a Stop, a new installation or an edit at the same moment either waits for the call or has happened already and is seen by it. Checking with getChatContext first does not do that, because its answer is out of date at once.

• A condition a method does not take, expected_installation_generation in a private chat, an unknown field whose name starts with expected_ and an unknown field inside initiator get 400 INVALID_REQUEST with field: a misspelt condition never turns into an unconditional call. answerCallbackQuery, rejectUpdate and setMyCommands take no conditions.
• A value is a string of 1 to 64 characters, compared with the stored one as a string; null is the same as no parameter. A value that is not a string gets 400 INVALID_REQUEST.
• Take every value from the update the decision was made on, and pass it on unchanged. Never refresh it from a later update, a result or getChatContext: that would revive an action after Stop and Start or after the bot was installed again. A button press carries the revisions of the moment of the press; when the press carries out a decision taken when the card was made, keep the revisions of that event with the card (Revisions in updates).

The errors never carry the current values, so that no library slips them into an old task. After a Stop a conditional send gets 403 BOT_STOPPED_OR_BLOCKED, after Stop and a new Start 409 ACCESS_REVISION_CONFLICT; both are final for the task. The rate limit is checked before the locks, so a 429 may come first and the retry after retry_after gets the conflict. A changing call waits for a revocation running at the same moment for at most 2 seconds, then answers 503 TEMPORARILY_UNAVAILABLE with retry_after 1; nothing was done, and the same key is safe to repeat.

POST /bot-api/v1/deleteMessage HTTP/1.1
Host: messenger.scrile.com
Authorization: Bearer sbt1_EXAMPLE_REPLACE_WITH_YOUR_TOKEN
Idempotency-Key: 0b7c9a52-51f4-4c55-9a55-7e1f0c7a1b90:delete
Content-Type: application/json

{"chat_id": "90020", "message_id": "880123", "expected_message_revision": "2",
 "expected_installation_generation": "184505", "expected_access_revision": "184510"}

If the person edited the message in between:

{
  "ok": false,
  "error": {"code": "MESSAGE_REVISION_CONFLICT", "message": "The message changed after expected_message_revision",
            "field": "expected_message_revision"},
  "request_id": "5d0e7c1a-2f8b-4d6e-9a31-1c2b3d4e5f60"
}

Strict mode#

setMyConditionsMode with {"mode": "strict"} makes the server refuse a new changing call that lacks the conditions it needs, with 400 INVALID_REQUEST naming the missing parameter in field; {"mode": "optional"} switches it off. The mode is shown in getMe.conditions_mode and is off by default.

initiator is never required. A repeat by key of a call made before the mode was switched on returns its result. The mode works only while strict_conditions is listed: on a server without it nothing is refused, so keep checking capabilities (rule 1 above).

Limits#

Requests over a limit get 429 RATE_LIMITED with retry_after. A short burst above the rate is allowed up to the number in the last column.

Other limits: text up to 4096 characters and buttons as in Messages and buttons; photos up to 10 MiB, documents up to 20 MiB and 200 MiB of uploads per bot per UTC day (Photos and documents); a queue of up to 10,000 updates or 50 MiB per bot (Receiving updates). The platform may set other limits for a single bot, and another total rate for all bots of one owner.

Versions and compatibility#

• The major version is part of the path: /bot-api/v1. A change that could break a working program gets a new path; v1 keeps working.
• Within v1 SMeet adds things: new fields in objects, new update types, new values of reason and status, new error codes. Your program must ignore fields and update types it does not know and treat unknown values as "other".
• Every change of the contract is listed in the API changelog. The current version is 1.2.0; what it adds is listed by capabilities, so a program can tell a server that has it from an older one.
• The contract itself is published as openapi.json (OpenAPI 3.1); generate a client from it or use it in your tests.

Methods#

Every method is called as POST https://messenger.scrile.com/bot-api/v1/<method> with a JSON body; read-only methods also accept GET with query parameters. Authentication: The bot token shown once in "My bots" / SMeet BotFather. Format sbt1_<key id>_<secret>; treat it as opaque. SMeet stores only a hash. A revoked token fails with 401 INVALID_TOKEN on every node immediately.

getMe#

GET POST /getMeBot

Check the token and return the bot's public profile.

Result#

The result field holds Bot. The bot.

On failure the answer is an error object with a code from the table of error codes.

getMyCommands#

GET POST /getMyCommandsBot

Read the command menu.

Parameters#

With GET pass them as query parameters, with POST as fields of a JSON body.

Result#

The result field holds array of BotCommand. The commands.

On failure the answer is an error object with a code from the table of error codes.

setMyCommands#

POST /setMyCommandsBot

Replace the command menu shown when the user types "/".

Headers#

Request body (JSON)#

Result#

The result field holds true. Saved.

On failure the answer is an error object with a code from the table of error codes.

setMyConditionsMode#

POST /setMyConditionsModeBot

Switch the strict conditions mode on or off.

In the strict mode a new call of a changing method without the conditions it needs fails with 400 INVALID_REQUEST naming the missing parameter: expected_access_revision in a private chat; expected_access_revision and expected_installation_generation in a group, topic or channel, and expected_message_revision too for deleteMessage. A repeat by key of a call made before the switch still returns its result. The mode is shown in getMe.conditions_mode. Available when capabilities lists strict_conditions; otherwise 404 METHOD_NOT_FOUND.

Headers#

Request body (JSON)#

Result#

The result field holds true. Saved.

On failure the answer is an error object with a code from the table of error codes.

getUpdates#

POST /getUpdatesUpdates

Receive pending updates with long polling.

Returns pending updates starting at the confirmed position. Passing offset confirms every update with update_id < offset; confirmed updates are never returned again. Unconfirmed updates are returned again on the next call (after a lost response or a restart), so the program must tolerate repeats.

The request waits up to timeout seconds and returns as soon as an update arrives, not at the end of the timeout. An empty result after a timeout changes nothing.

One active consumer per bot. The first call names a consumer_id and receives a lease with an epoch; later calls pass the same consumer_id and epoch and extend the lease (TTL 60 seconds). A second concurrent call, even with the same consumer_id, is rejected with CONSUMER_CONFLICT. A call carrying a foreign epoch (another consumer, the owner's lease reset or a mode switch took the lease since) gets a new lease but confirms nothing: its offset is ignored and unconfirmed updates come again. If your own lease expired and nobody took it in between, your next call gets a new lease and its offset still confirms.

Offset rules (confirmed_offset = position after the confirmed prefix, max_issued_update_id = highest update_id ever returned):

• offset = confirmed_offset is always accepted (a no-op confirmation).
• confirmed_offset < offset <= max_issued_update_id + 1 confirms the prefix.
• offset < confirmed_offset fails with 409 CURSOR_BEHIND; the error carries the current confirmed_offset. Nothing is re-sent.
• offset > max_issued_update_id + 1 fails with 400 OFFSET_NOT_ISSUED unless it equals the next_offset the server returned for the current lease.
• Omitting offset continues from the position stored by the server.

Example: after update 42 was returned, offset=43 confirms it; offset=44 is rejected; once 43 is confirmed, offset=42 gets CURSOR_BEHIND.

Updates that were cancelled, expired or moved to FAILED before being confirmed are reported in skipped; next_offset then jumps over them. Always confirm with the returned next_offset after durably storing the whole batch.

Request body (JSON)#

Result#

The result field holds GetUpdatesResult. A batch of updates (possibly empty).

On failure the answer is an error object with a code from the table of error codes.

rejectUpdate#

POST /rejectUpdateUpdates

Move one issued, unconfirmed update to FAILED.

Use when the program cannot process one specific update and does not want it to block the rest of the batch. The update leaves the active sequence, keeps its payload for the original retention window, and appears in the owner's FAILED list where it can be replayed or skipped. Only updates already returned to the current lease and not yet confirmed can be rejected.

Headers#

Request body (JSON)#

Result#

The update is FAILED. The result field holds an object with these fields.

On failure the answer is an error object with a code from the table of error codes.

sendMessage#

POST /sendMessageMessages

Send a text message to an allowed private, group, topic or channel chat.

The sender is always the bot identified by the token; there is no sender_id parameter. A private chat must still be started. A group or topic needs can_send_messages; a channel needs can_post_messages. Takes the conditions expected_access_revision, expected_installation_generation (groups, topics and channels) and initiator. A mini_app button needs a private chat of a bot with a Mini App.

Headers#

Request body (JSON)#

Result#

The result field holds Message. The sent message.

On failure the answer is an error object with a code from the table of error codes.

editMessageText#

POST /editMessageTextMessages

Edit the text and buttons of a message this bot sent.

Only messages sent by this bot can be edited. If reply_markup is omitted, the message has no buttons after the edit. Takes the conditions of sendMessage and expected_message_revision. A mini_app button needs a private chat of a bot with a Mini App, as in sendMessage.

Headers#

Request body (JSON)#

Result#

The result field holds Message. The edited message.

On failure the answer is an error object with a code from the table of error codes.

deleteMessage#

POST /deleteMessageMessages

Delete a message.

In a private chat a bot can delete only its own message. In a group, topic or channel the installation needs can_delete_messages. Takes the conditions expected_access_revision, expected_installation_generation (groups, topics and channels), expected_message_revision and initiator.

Headers#

Request body (JSON)#

Result#

The deleted message identity. The result field holds an object with these fields.

On failure the answer is an error object with a code from the table of error codes.

pinChatMessage#

POST /pinChatMessageMessages

Pin a message in a group, topic or channel.

The installation needs can_pin_messages. Takes the conditions expected_access_revision, expected_installation_generation, expected_message_revision and initiator.

Headers#

Request body (JSON)#

Result#

The message is pinned. The result field holds an object with these fields.

On failure the answer is an error object with a code from the table of error codes.

unpinChatMessage#

POST /unpinChatMessageMessages

Unpin a message in a group, topic or channel.

The installation needs can_pin_messages. Takes the conditions expected_access_revision, expected_installation_generation, expected_message_revision and initiator.

Headers#

Request body (JSON)#

Result#

The message is unpinned. The result field holds an object with these fields.

On failure the answer is an error object with a code from the table of error codes.

restrictChatMember#

POST /restrictChatMemberMessages

Remove a member from a group or channel.

The installation needs can_restrict_members. The group owner and the bot itself cannot be removed by this method. Takes the conditions expected_access_revision, expected_installation_generation and initiator.

Headers#

Request body (JSON)#

Result#

The member is removed. The result field holds an object with these fields.

On failure the answer is an error object with a code from the table of error codes.

getChatContext#

GET POST /getChatContextMessages

Read the current state of one chat of this bot, with its revisions.

For a private chat: the person and the conversation's status, also when it is stopped, blocked or removed. For a group, topic or channel: the group's owner, the installation's permissions and when it was installed. With user_id, whether that person is the chat's person, or, in a group, known to the bot there, a member and the owner. The answer is a snapshot that is out of date at once: what makes an action safe is the condition of the changing call, not a read before it. Available when capabilities lists chat_context; otherwise 404 METHOD_NOT_FOUND. Limited to 5 calls a second per bot, bursts of 10.

Parameters#

With GET pass them as query parameters, with POST as fields of a JSON body.

Result#

The result field holds ChatContext. The chat as it is now.

On failure the answer is an error object with a code from the table of error codes.

answerCallbackQuery#

POST /answerCallbackQueryMessages

Confirm that a button press was handled.

Stops the user's pending indicator and optionally shows a short notice. A press that is not answered within 15 seconds shows "The bot did not respond" to the user; the bot can still answer later and edit its message. A callback query can be answered once, within 1 hour; a repeated identical answer returns the same result, and a different second answer fails with 409 IDEMPOTENCY_CONFLICT.

Headers#

Request body (JSON)#

Result#

The result field holds true. Answered.

On failure the answer is an error object with a code from the table of error codes.

uploadFile#

POST /uploadFileFiles

Upload a photo or document for later sending.

The file is stored in quarantine and scanned. The returned file_id has status scanning; it can be sent only after getFile reports ready. Limits: photos up to 10 MiB (JPEG, PNG, WebP, HEIC), documents up to 20 MiB, plus a daily volume quota per bot. The same Idempotency-Key never creates a second file.

Headers#

Request body (multipart/form-data)#

Result#

The result field holds File. The stored file (usually scanning).

On failure the answer is an error object with a code from the table of error codes.

sendPhoto#

POST /sendPhotoFiles

Send a ready photo file to a chat.

The file must have kind photo (a JPEG, PNG, WebP or HEIC by its content). Any other ready file fails with 400 INVALID_REQUEST, field: file_id; send it with sendDocument instead. Takes the conditions of sendMessage. A mini_app button needs a private chat of a bot with a Mini App, as in sendMessage.

Headers#

Request body (JSON)#

Result#

The result field holds Message. The sent message.

On failure the answer is an error object with a code from the table of error codes.

sendDocument#

POST /sendDocumentFiles

Send a ready document file to a chat.

Takes the conditions of sendMessage. A mini_app button needs a private chat of a bot with a Mini App, as in sendMessage.

Headers#

Request body (JSON)#

Result#

The result field holds Message. The sent message.

On failure the answer is an error object with a code from the table of error codes.

getFile#

GET POST /getFileFiles

Read a file's metadata and processing status.

Works for files the bot uploaded and for attachments of messages it received. The download_path is present only while the status is ready and access is still allowed. For scanning, the response carries retry_after.

Parameters#

With GET pass them as query parameters, with POST as fields of a JSON body.

Result#

The result field holds File. The file.

On failure the answer is an error object with a code from the table of error codes.

downloadFile#

GET /files/{file_id}/contentFiles

Download the bytes of a ready file.

Requires the bot token and current access rights on every call. There is no public or permanent storage URL. Access ends when the source message is deleted, the user stops or blocks the bot, or the user leaves the space.

Parameters#

Path parameters are part of the address.

Result#

The answer is the file itself, not JSON. The file bytes. Response headers: Content-Disposition.

On failure the answer is an error object with a code from the table of error codes.

getDeliveryInfo#

GET POST /getDeliveryInfoDelivery

Read the delivery mode, queue sizes and the last error.

Never returns the webhook secret.

Result#

The result field holds DeliveryInfo. Delivery state.

On failure the answer is an error object with a code from the table of error codes.

getWebhookInfo#

GET POST /getWebhookInfoDelivery

Read the webhook state (a subset of getDeliveryInfo).

Result#

The result field holds WebhookInfo. Webhook state.

On failure the answer is an error object with a code from the table of error codes.

Webhook request#

POST your HTTPS address

SMeet delivers one update to the owner's HTTPS endpoint.

Sent only when the bot's delivery mode is webhook. One request in flight per bot; network timeout 10 seconds; redirects are not followed.

Verify X-SMeet-Signature before trusting the body: t is a Unix timestamp and v1 is the lowercase hex HMAC-SHA256 of "<t>.<raw request body>" keyed with the webhook secret shown once in "My bots". Reject timestamps more than 5 minutes away from your clock. The API token is never sent to the webhook.

Store the update durably (unique by event_id) and answer any 2xx quickly; run long business logic afterwards. A 2xx confirms receipt, not business success. Lost responses cause repeats with the same update_id and event_id.

Response handling: 2xx confirms. 400, 413 or 422 marks this update FAILED and moves on. 401, 403, 404, 410, a certificate that does not validate, an address webhooks may not reach, a redirect and any other unsupported answer pause the endpoint until the owner fixes it and resumes delivery in "My bots" (state paused, the cause in last_error); nothing is retried meanwhile, no update is charged and the queue is kept. 429 slows down and honours Retry-After. DNS and connection errors, and connect or TLS handshake timeouts before the request is sent, keep the update pending and back off (5 seconds, doubling up to 5 minutes). 5xx, 408 and failures after the request started share a budget of 5 attempts or 10 minutes per update, after which it becomes FAILED; three such updates in a row open a circuit breaker that probes with the current update before continuing.

Headers#

Body#

An Update object in JSON.

Your answer#

Accepted. Any 2xx is treated the same way; the body is ignored.

Update types#

The type field of an Update names exactly one payload field that is present. Consumers must ignore unknown values.

Types#

Simple types#

Strings with a fixed format. Fields refer to them by name.

User#

Only what the chat needs. E-mail, phone, other chats, other accounts and sessions are never included.

Chat#

Space#

Bot#

BotMiniApp#

The Mini App of a bot, as getMe describes it.

MiniAppButton#

Opens the bot's Mini App in the person's SMeet app, the published version only.

InlineKeyboardButton#

InlineKeyboardMarkup#

Attachment#

Message#

CallbackQuery#

ChatAccess#

GroupBotPermissions#

MyChatMember#

DeliveryGap#

A summary emitted after group-message backpressure ends. It says that new messages were deliberately not queued; it never contains the dropped message bodies.

DeletedMessage#

FileStatusChange#

Sent when a check ends: for attachments the bot received (with message_id and chat), and for the bot's own uploads (without them). Never sent into a chat the user has stopped or left. scan_failed is not always final: a file the scanner could not check (scanner_unavailable, scanner_outdated, scan_timeout) is checked again about an hour later, up to three rounds, and another file_status_changed follows; meanwhile getFile reports scanning again.

Update#

Exactly one payload field is present, chosen by type:

Editing an old message is not a new command: treat message_edited as a correction. The revisions in a payload are those of the moment the event happened, and a replay from FAILED hands them over unchanged; updates written before 1.2.0 have none.

MiniAppSubmission#

A person sent a form of the bot's Mini App to the bot and confirmed it in SMeet. SMeet fixes the application, the environment, the person and the chat; the page sends only data. One submission is one update, whatever the page retries.

Lease#

SkipRange#

GetUpdatesResult#

BotCommand#

DeliveryError#

DeliveryInfo#

WebhookInfo#

Initiator#

The person on whose decision the bot acts, and the role they must hold now. Checked in the parent group of chat_id together with the action; failing it gives 403 INITIATOR_NOT_AUTHORIZED, the same answer for "not a member", "not the owner" and "not known to the bot". An unknown field inside the object gives 400 INVALID_REQUEST.

ChatContext#

One chat as it is now. Exactly one of private and group is present.

ChatContextPrivate#

ChatContextGroup#

UserCheck#

File#

Errors#

Any failure. See ErrorCode for the meaning of each code and the HTTP status it comes with. The Retry-After header is set whenever the body carries retry_after (429, 503, and 409 CONSUMER_CONFLICT and FILE_NOT_READY).

Headers of an error answer: Retry-After, X-Request-Id.

Error object#

Every failed call answers with this envelope and a matching HTTP status.

The error field:

Error codes#