Sensever bots: bot management and the owner API

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

6 min de lectura

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 getUpdates), "Test delivery" (queues a test update) and "Delivery log" (recent updates: number, type, state, error)

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

GET /v1/chat/bots/username?username=shop_bot

Check a username: {"username", "valid", "available"}

POST /v1/chat/bots

Create a bot

GET /v1/chat/bots

List your bots: {"items": [...]}

PATCH /v1/chat/bots/{id}

Change the name, webhook, privacy, inline mode

PUT /v1/chat/bots/{id}/profile

Change the description and short description

POST /v1/chat/bots/{id}/avatar

Upload an avatar

DELETE /v1/chat/bots/{id}/avatar

Remove the avatar

POST /v1/chat/bots/{id}/token

Issue a new token and webhook secret

GET /v1/chat/bots/{id}/deliveries

Webhook state and a log of the last 100 updates

POST /v1/chat/bots/{id}/test

Queue a test update

DELETE /v1/chat/bots/{id}

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

id

String (UUID)

Yes

Generate it yourself: a retry with the same id and the same parameters does not create a second bot

name

String

Yes

Name, 1–128 characters

username

String

Yes

The full username ending in _bot; a leading @ and letter case do not matter

webhook_url

String

No

Webhook URL; without it, the bot works through getUpdates

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

name

String

New name, 1–128 characters. Not allowed if a project configures the bot as an assistant on the Sensever model (409 bot_name_managed_by_project)

webhook_url

String or null

New URL; null switches to getUpdates

group_privacy

Boolean

Privacy mode in groups

inline_placeholder

String or null

Inline mode placeholder, 1–64 characters; null turns the mode off

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}/token

Response: {"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".

Comentarios

Autores