SMeet Bot API

Operations

What to watch and what to do when something goes wrong. The two situations that look alike but are not, a technical pause of the platform and an organisation switching bots off, have a section each.

Keeping secrets#

A bot has two secrets: the token its program uses to call the Bot API, and in webhook mode the webhook secret SMeet uses to sign deliveries.

• Keep them in environment variables or a secret store. A .env file must be readable only by the service user and must never reach git.
• Send the token only in the Authorization header. Never put it into a URL, a log, a chat, a screenshot or a support ticket. The examples log update ids, chat ids and error codes, never the token, the secret or message text.
• SMeet shows each secret once and keeps only a hash of the token and an encrypted copy of the webhook secret. The API never returns either of them, and the token is never sent to your webhook.
• Rotating the token: issue a new one on the protected screen of My bots; the old one stops at once, so put the new one into the program and restart it right away.
• Rotating the webhook secret: save the webhook again on the Connection screen; every time webhook mode is set, a new secret is created and shown once. Until your program has it, deliveries signed with the new secret fail your check, your 401 pauses delivery and the updates wait (A paused endpoint). Put the new secret into the program, restart it and press Resume delivery; nothing is lost.
• If a secret may have leaked, use the emergency reset: a new token, the long polling lease taken away and, in webhook mode, a new webhook secret, in one step.

Health checks#

• getMe answers even while the bot is paused and during a technical pause of the platform. Call it at start: it confirms the token and shows status (active, paused_by_owner, suspended_by_admin) and delivery_mode.
• getDeliveryInfo is the one call for monitoring (Queue diagnostics). It never returns a secret, and it also answers during a technical pause, with "maintenance": true.
• My bots and the card of the bot in BotFather show one of four statuses:

"Working" means only that the program is connected. It says nothing about whether its logic is right, and a webhook that refuses updates with 400, 413 or 422 gets no error status for that: watch the FAILED list and failed_update_count. In webhook mode SMeet BotFather also writes to you when delivery pauses or an update goes to FAILED (Notices to the owner).

Queue diagnostics#

{
  "ok": true,
  "result": {
    "mode": "polling",
    "config_version": "3",
    "pending_update_count": 12,
    "failed_update_count": 1,
    "oldest_pending_date": "2026-09-26T09:58:10Z",
    "confirmed_offset": "1840",
    "lease": {"consumer_id": "poller-host1", "epoch": "7", "expires_at": "2026-09-26T10:01:00Z"},
    "webhook": {"url": "", "state": "none", "pending_update_count": 12, "max_connections": 1},
    "maintenance": false,
    "retention_seconds": 604800
  }
}

If the bot is silent#

1. Is the program running? Its log should show Running as @<address> and no errors.
2. Does the token work? getMe with the token. 401 INVALID_TOKEN means it was revoked or mistyped: issue a new one in My bots.
3. Is the bot running? getMe status: paused_by_owner means /resume in BotFather; suspended_by_admin means the platform suspended the bot or its owner left the organisation: contact support.
4. Is the mode right? getMe delivery_mode. A polling program against a bot in webhook mode gets 409 DELIVERY_MODE_CONFLICT: switch the bot to long polling, or run your webhook receiver.
5. Is another copy receiving? getDeliveryInfo lease.consumer_id. CONSUMER_CONFLICT that does not go away means a second copy holds the lease (A stuck lease).
6. Did the person press Start? Nothing reaches the bot before Start or after Stop. In an organisation, the person must still be a member.
7. Is it the platform or the organisation? 503 BOTS_MAINTENANCE is a technical pause: wait. 403 SPACE_BOTS_DISABLED means the organisation switched bots off.
8. Webhook: getWebhookInfo state and last_error (Webhook problems), and the FAILED list. paused means your endpoint gave an answer only you can fix; fix it and press Resume delivery in My bots.
9. Replies fail: 403 BOT_STOPPED_OR_BLOCKED (the person stopped the bot), 400 INVALID_REQUEST with error.field, 429 RATE_LIMITED. Keep the request_id of a failing call.

Errors by HTTP status#

The full list is in the table of error codes.

Webhook problems#

getWebhookInfo shows the state of your endpoint:

next_attempt_date also shows a wait after a failed connection or a 429. last_error.code tells what happened last:

New codes may appear; treat an unknown one by the state that comes with it.

Technical pause: BOTS_MAINTENANCE#

The operators of SMeet can pause the whole bot platform, for example while a release is rolled back or during an incident. It is a pause, not a revocation: everything is kept.

During the pause:

• data methods of the Bot API answer 503 BOTS_MAINTENANCE with retry_after (30 seconds) and the same Retry-After header; waiting long polls end with this error;
• getMe, getMyCommands, getDeliveryInfo and getWebhookInfo still answer, and getDeliveryInfo shows "maintenance": true;
• a webhook delivery already under way finishes and counts; no new deliveries or file checks start;
• people's messages to bots are not sent: their app says that bots are paused for maintenance and keeps the text in the input field;
• the queue, FAILED updates, Idempotency-Keys, offsets, the long polling lease and Start permissions are kept;
• Stop, Block, leaving a space and deletions still take effect and still cancel what they cancel;
• the retention clock keeps running: an update whose 7 days end during the pause expires.

What your program does:

• wait retry_after, then repeat the same request with the same key and the same offset; never drop or reset the saved position because of this error;
• after the pause, getUpdates with the same consumer_id, epoch and offset continues under the same lease. If the pause outlasted the lease, the call gets a new one, and the saved offset still confirms, because nobody took the lease in between. Nothing is lost;
• a webhook receiver does nothing: deliveries resume by themselves, in order.

The client of the examples does exactly this: BOTS_MAINTENANCE is one of the codes smeet.py retries with the same body and key.

An organisation revokes its permission#

An owner or administrator of an organisation can switch Running bots off (Organisations and permissions). This is a decision about the organisation's data, not a technical pause, and it cancels:

• every bot of the organisation gets 403 SPACE_BOTS_DISABLED, and people see that bots are turned off in this organisation;
• every undelivered update of these bots is cancelled, FAILED updates included; they cannot be replayed and do not come back when running is switched on again;
• chats and Start permissions stay.

What your program does: stop calling in a loop (the examples exit with code 2 and a message), and talk to the organisation's administrators. When running is switched on again, start the program: it receives only what happens from then on, and the cancelled range is reported as skipped with the reason cancelled.

Pause and suspension#

A stuck lease#

When a long polling program dies, its lease lives on for up to 60 seconds after the server's last answer to it, and a long poll it left open counts until its timeout. A restarted program that kept its epoch continues at once; one that lost it gets CONSUMER_CONFLICT until the lease expires. getDeliveryInfo shows the holder in lease.

If you are sure no other copy runs, press Reset the connection on the Connection screen of My bots. The old epoch then becomes foreign: a copy that still sends it confirms nothing with it, and the updates it had not confirmed come again. The next call gets a new lease from the confirmed position.

Getting help#

Write to support@scrile.com with the bot's address, the time, the method and the request_id of a failing call (it is in every error body and in the X-Request-Id header). Never send the token or the webhook secret.