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 and then returns its result.
• 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).

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

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 a chat the user has started with this bot.

The sender is always the bot identified by the token; there is no sender_id parameter. The chat must be a private chat in which the user pressed Start and has not stopped or blocked the bot.

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.

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.

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.

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.

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#

InlineKeyboardButton#

InlineKeyboardMarkup#

Attachment#

Message#

CallbackQuery#

ChatAccess#

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.

Lease#

SkipRange#

GetUpdatesResult#

BotCommand#

DeliveryError#

DeliveryInfo#

WebhookInfo#

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#