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 |
|
| Read and write |
Group |
|
| Also delete other people's messages, change roles and remove members, hear reactions and membership changes |
Group |
|
| Only read |
Channel |
|
| Receive posts |
Channel |
|
| Post on behalf of the channel |
Channel |
|
| 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:
/statusgoes to all bots in the group,/status@shop_botonly to this bot;mentions:
@shop_botin the text or a mention of the bot viapayload.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/membersParameter | Type | Required | Description |
|---|---|---|---|
| String | Yes | Member: |
| String or null | Yes | New role: |
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}/leaveThe 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
messageupdate 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 theX-Tenant-IDheader in every request about this conversation.The visitor appears as
tu1.…, an opaque reference without the account number;avatar_urlisnull.
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.
Komentarze