sometimesrunning your bot
deploy your bot on your own server, protect its credentials and keep its approved installations working as you publish changes.
credentials and deployment
keep the bot token in your hosting provider’s secret store. the dashboard reveals it once and lists its prefix and last use afterward. create a replacement, deploy it, reconnect the gateway and revoke the old token. rotating a token does not require users to reinstall. run one gateway consumer per application and distribute its work inside your service. use process supervision to restart after a closed connection; keep durable cursors and idempotency keys for recovery.
publishing configuration changes
save profile, permission, scope and command changes in the developer dashboard, then publish. name, profile picture, banner and about-me changes update existing installations immediately. grants, commands and scope remain pinned to each user’s approved revision. users review the new configuration from settings → bots; old approvals keep working until renewed consent. unpublish prevents new installations while preserving existing ones. disable stops runtime access and hides commands; delete revokes credentials and installations.
testing with a private bot
keep a development bot private and add test accounts through the invite picker. test both optional-grant choices, account and single-chat scope, a group owner’s exclusion, revoked invites and token replacement. submit commands with the slash picker and verify that public replies reach the chat while private replies reach only their installer. test call receive, publish and leave paths with separate participants; close media sessions in your shutdown handler. removing a private invite immediately revokes that account’s installations.
handling interrupted work
use the same Idempotency-Key when a write’s outcome is uncertain. handle 412 by rereading the resource revision and reconciling the intended change. persist gateway cursors only after processing preceding events. after resync_required, rebuild authorized snapshots and reconnect with the supplied cursor. retain no private content after access is revoked. keep call negotiation serialized; close and recreate a session after ICE failure or an unanswered SDP offer.
troubleshooting
record the response request_id, status, error code and timing when diagnosing failures. keep tokens, message bodies, private command arguments and SDP out of logs. the installer can review delegated actions in settings → bots → activity.
scroll the table horizontally to see all columns.
| symptom | check |
|---|---|
| 401 invalid_token | use Authorization: Bot followed by a current token; browser requests with Origin are not accepted |
| 403 permission_denied | inspect this installation’s effective_permissions; publishing a grant does not authorize existing users automatically |
| 404 not_found | check the exact installation, chat scope, resource owner, blocks and group exclusions; hidden resources also return 404 |
| 409 configuration_changed | refresh the consent prompt or command list; a newer permission or scope choice needs human authorization |
| 412 revision_mismatch | read the latest ETag, then decide whether your edit still applies |
| 429 rate_limited | honor Retry-After and reduce concurrency; tokens and installations share application/account quotas |
| command absent | publish the draft command, authorize commands for the selected installation, and start the composer with / |
| command expired | ACK within three seconds; send the reply within 15 minutes and keep its acknowledged visibility |
| missing media track | check the receive grant, source state and participant access; screen audio needs both audio and screen grants |
| gateway 4009 / 4010 | another consumer replaced yours / authorized REST snapshots are required before resuming |
downloadable schemas
use the reference and machine-readable schemas when implementing a client. unknown response fields may be added within API 1. the four-language quickstart is intentionally small; a production bot should also implement durable recovery and application-specific error handling.