Bot API: groups, channels and project requests

SENSEVER

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

6 min lezen

Bot API: groups, channels and project requests

Besides direct chats, a bot works where there are many participants: in groups, in channels, and in website visitors' requests if a project has chosen it as its assistant. This article describes how the bot gets there, what it hears and what it can do.

How to add a bot to a group or channel

An admin of the group or channel opens the community settings, finds @shop_bot in the member search and clicks "Add". In the API, this is the same method as for people, called with the admin's session:

PUT /v1/chat/threads/{thread_id}/community/members
{"ref": "p.812", "role": "member"}

The bot learns that it was added from a my_chat_member update (old_status: "left", new_status: "member"). Roles:

Where

Role

Status in updates

What the bot can do

Group

member — member

member

Read and write

Group

admin — admin

administrator

Also delete other people's messages, change roles and remove members, hear reactions and membership changes

Group

read_only — read only

restricted

Only read

Channel

read_only — reader

restricted

Receive posts

Channel

editor — author

member

Post on behalf of the channel

Channel

admin — admin

administrator

Post, delete other people's posts, manage followers

Only the community owner can appoint an admin.

Privacy mode in groups

By default, a bot in a group works in privacy mode and receives only messages addressed to it:

  • commands: /status goes to all bots in the group, /status@shop_bot only to this bot;

  • mentions: @shop_bot in the text or a mention of the bot via payload.mentions;

  • replies to this bot's messages.

Messages from other bots never arrive. The owner turns the mode off in the bot menu "Actions" → "Privacy in groups" (or PATCH /v1/chat/bots/{id} with "group_privacy": false). The bot then receives all messages from people, and group members see the label "Bot · sees all messages" next to it.

Privacy mode limits only updates. As a group member, the bot can read the history through GET /v1/chat/threads/{thread_id}/messages from the moment it joined (or the full history if the group shows history to new members). Keep this in mind when you add someone else's bot to a private group.

Channels

A bot that is a channel member receives every post as a channel_post update and every edit as edited_channel_post. The author of a post in the message is the channel itself (sender.kind: "thread").

A bot with the "Author" or "Admin" role posts with the regular send message method; the post always comes from the channel. Polls (kind: "poll") work in channels and groups too.

Administration

A bot that is an admin of a group or channel:

  • deletes other people's messages: DELETE /v1/chat/threads/{thread_id}/messages/{seq}. The bot can never edit other people's messages;

  • changes a member's role or removes them:

PUT /v1/chat/threads/{thread_id}/community/members

Parameter

Type

Required

Description

ref

String

Yes

Member: p.<number>

role

String or null

Yes

New role: member or read_only in a group, editor or read_only in a channel; null removes the member

Response: the community description with the member list. The bot cannot change the owner's role or its own (409 owner_protected), or appoint or remove an admin (403 forbidden).

  • hears members' reactions to messages (message_reaction) and membership changes (chat_member): who joined, left or got a different role.

Leave a group or channel

POST /v1/chat/threads/{thread_id}/leave

The bot leaves the conversation and receives a my_chat_member update with new_status: "left"; admin bots of that conversation receive chat_member.

Topics

In groups with topics, a message has a topic_id. Reply in the same topic by passing topic_id when sending. To read one topic: GET /v1/chat/threads/{thread_id}/messages?topic_id=….

Project requests (website widget)

A Sensever project can choose a bot as its assistant. A website visitor then writes in the widget, and your bot answers — until an agent takes the request.

Connecting

The bot owner selects it in the project settings: Projects → widget installation → settings → "Custom bot". You can select only your own active bot; one bot can work in several of the owner's projects.

What the bot receives

  • A message update for every visitor message while the request is open, not assigned to an agent, AI is not paused, and the request is not marked closed or spam. Edits (edited_message), reactions and the visitor's button taps arrive too.

  • The update contains tenant_id, the project number. Pass it in the X-Tenant-ID header in every request about this conversation.

  • The visitor appears as tu1.…, an opaque reference without the account number; avatar_url is null.

How the bot replies

POST /v1/chat/threads/901/messages
Authorization: Bearer b1.XXXX
X-Tenant-ID: 42
Content-Type: application/json
{"client_message_id": "2b4c6d8e-0f1a-4b3c-9d5e-7f8091a2b3c4", "kind": "text", "text": "Yes, we deliver to Austin, 2–3 days.", "payload": {}, "reply_to_seq": "7", "send_as": "self"}

The message is sent from the bot (sender.kind: "bot"), and sender.tenant_ref points to the project. The bot does not moderate the visitor's messages: it does not edit or delete them; its reactions are set on behalf of the project.

As soon as an agent takes the request, closes it or pauses AI, updates stop arriving, and reading and sending return 409 conversation_owned. Do not try to work around this response: it means a person is handling the conversation.

In the widget, the visitor sees buttons, the keyboard, the command menu and "typing…", and can open the bot's Mini App. Inline mode is not available in the widget.

When the bot stops working in a project

If the owner turns off the assistant, selects another bot, issues a new token for the bot or deletes the bot, updates stop arriving; requests with X-Tenant-ID return 403 forbidden. After a new token, the project keeps working with the bot: you only need to replace the token on the bot's server.

Reacties

Auteurs