Sensever bots: bot management and the owner API
The bot's owner — the person who created the bot — creates it, changes its name, avatar and settings, issues a new token and deletes the bot. This is done in the Sensever interface or through the owner API. In Sensever, the role of BotFather is played by the "Bot settings" window: there are no chat commands for this.
In the interface
Create a bot: Chats → "Create" → "Bot". Enter a name, a username ending in _bot and, if you like, a webhook URL. After creation the window shows the token and the webhook secret once — save them.
Your bots: the "Bots" tab → "Mine". Above the list of bot chats there is an "All | Mine" switch. "All" shows your chats with bots; "Mine" shows the bots you own, each with its status line (webhook is working, a delivery error with its code, "Fetches messages with getUpdates", how many updates are queued). Tap a bot to open the chat with it.
Bot settings: the chat with your bot → "Info" → the pencil. Only the owner sees the pencil, as with a group. The "Bot settings" window has:
Block | What you can do |
|---|---|
Photo (at the top) | Tap the photo to upload a new one, pick one from Storage or remove it |
Name, description, about | The name, the description people see in an empty chat with the bot (up to 512 characters) and one line for the bot's page (up to 120 characters) |
Delivery | The webhook URL (empty — the bot works through |
Bot token | "New token" issues a new token and webhook secret; the old ones stop working immediately. They are shown once, with a "Copy" button |
In groups | "Receive all messages in groups" turns privacy mode off; the inline mode placeholder (empty — inline mode is off) |
Remove bot | Revokes the bot in all projects |
How people subscribe. A person opens the bot's page sensever.com/@your_bot (or finds the bot in chat search) and taps "Start". From then on the bot can write to them, also by their confirmed email or phone (see "Bot API: messages and files").
Owner API
These methods are called with the owner's user session (Authorization: Bearer <session access token>), without X-Tenant-ID. The bot token and account API keys do not work here (403 forbidden).
In these methods, {id} is the UUID of the bot record, not the bot_id.
Request | What it does |
|---|---|
| Check a username: |
| Create a bot |
| List your bots: |
| Change the name, webhook, privacy, inline mode |
| Change the description and short description |
| Upload an avatar |
| Remove the avatar |
| Issue a new token and webhook secret |
| Webhook state and a log of the last 100 updates |
| Queue a |
| Delete (revoke) the bot |
Create a bot
POST /v1/chat/bots{"id": "863c4667-5a4b-4f2f-810b-eecbb92830bf", "name": "Shop assistant", "username": "shop_bot", "webhook_url": "https://bot.example.com/sensever"}Parameter | Type | Required | Description |
|---|---|---|---|
| String (UUID) | Yes | Generate it yourself: a retry with the same |
| String | Yes | Name, 1–128 characters |
| String | Yes | The full username ending in |
| String | No | Webhook URL; without it, the bot works through |
Response: id, name, username, bot_id, webhook_url, token, webhook_secret. The token and secret are returned only in the first response; a repeated create does not include them.
Errors: 422 invalid_bot_username; 409 username_taken; 403 bot_owner_unverified — no verified email or phone number; 409 bot_limit_reached — you already have 20 bots; 409 idempotency_conflict — this id was already used with different parameters or for a deleted bot; 422 webhook_destination_forbidden.
Edit a bot
PATCH /v1/chat/bots/{id}Parameter | Type | Description |
|---|---|---|
| String | New name, 1–128 characters. Not allowed if a project configures the bot as an assistant on the Sensever model ( |
| String or null | New URL; |
| Boolean | Privacy mode in groups |
| String or null | Inline mode placeholder, 1–64 characters; |
All parameters are optional. Response: {"id", "name", "webhook": WebhookInfo}; if the bot got a webhook secret for the first time, webhook_secret is included too.
Description and avatar
PUT /v1/chat/bots/{id}/profile takes description and short_description, like PUT /v1/chat/bot/profile, and returns BotProfile.
POST /v1/chat/bots/{id}/avatar takes multipart/form-data with the file in the avatar field (JPEG, PNG or WebP, up to 10 MB). Response: {"avatar_url": "…"}. DELETE on the same URL removes the avatar: {"avatar_url": null}. The bot's avatar is public.
New token
POST /v1/chat/bots/{id}/tokenResponse: {"id", "token", "webhook_secret"}. Like BotFather's /revoke: the username, chats, groups and the bot's selection in projects are kept, and the old token and secret stop working immediately. Remember to update the secret in your webhook and Mini App signature verification.
Log and test
GET /v1/chat/bots/{id}/deliveries returns {"webhook": WebhookInfo, "items": [...]}; each record has update_id, type, state, attempts, last_error, thread_id, created_at, finished_at, next_attempt_at. The log does not include update contents.
POST /v1/chat/bots/{id}/test returns {"update_id": "…"} of the test update.
Delete a bot
DELETE /v1/chat/bots/{id}Response: {"revoked": true}. The token stops working, and the bot is turned off in every project where it was selected. Conversation history is kept. The username is not released, and the bot cannot be restored.
List bots
GET /v1/chat/bots returns all of the owner's bots, including deleted ones (they have revoked_at set). Record fields: id, bot_id, username, name, webhook_url, webhook_last_success_at, webhook_last_error_at, webhook_last_error, pending_updates, description, short_description, group_privacy, inline_placeholder, engine (external — your server, builtin — the Sensever model), created_at, revoked_at and the internal persona, persona_name.
A bot as a project assistant
To have the bot answer website visitors, select it in the project settings: Projects → widget installation → settings → "Custom bot". In the API, these are fields of the website widget settings (PUT /v1/chat/projects/{tenant}/sites/{site}/widget): assistant_enabled: true, assistant_mode: "external", assistant_bot_id — the UUID of the bot record. They are part of the full set of widget settings, not a separate request. How the bot works in requests is described in "Bot API: groups, channels and project requests".
Komen