Bot API: messages and files

SENSEVER

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

13 min czytania

Bot API: messages and files

The methods in this article work in any conversation where the bot can read and write: a direct chat with a person, a project request (with the X-Tenant-ID header), or a group or channel where the bot is a member. In other conversations the response is 404 not_found or 403 forbidden.

Message object

Field

Type

Description

thread_id

String

Conversation

seq

String

Message number within the conversation

message_ref

String

Signed reference to the message

kind

String

text, media (files with an optional caption), poll, review (request rating) and service kinds

sender

Principal

Author. A channel post comes from the channel (kind: "thread"); a project agent's reply comes from the project (kind: "tenant")

mine

Boolean

The message was sent by this bot

text

String or null

Text with markup; null for a deleted message

payload

Object

Data specific to the message kind: buttons, keyboard, poll, mentions, contact, inline mode marker

client_message_id

String or null

The UUID the author sent the message with

topic_id

String or null

Topic in a group with topics

reply_to_seq

String or null

The message this one replies to

forward_from_ref

String or null

Reference to the original message if this is a forward

created_at

String

Time sent

edited_at

String or null

Time of the last edit

deleted_at

String or null

Time deleted

expires_at

String or null

When the message disappears, if it has an expiry

counters

Object

reactions (reaction → count), poll_votes (option → number of votes), replies (number of replies)

my_interactions

Array

This bot's reactions: [{"kind": "reaction", "value": "👍"}]

attachments

Array of Attachment

Message files

links

Array

Links found in the text, with previews

unread_eligible, activity_eligible

Boolean

Internal counter flags

publication, content_url

—

Internal fields of channel posts

Payload fields

Field

Type

Where it appears

buttons

Array of Array of InlineKeyboardButton

Bot messages with inline buttons

reply_keyboard

ReplyKeyboard

Bot messages that set or remove the keyboard below the input field

mentions

Array of Mention

Mentions in the text

contact

Object

The person shared their number with a request_contact button: ref, phone, name

via_bot

Object

The message was sent through inline mode: ref, the bot's username

question, options, multiple

—

Poll (kind: "poll")

rating

Integer

Request rating (kind: "review"), from 1 to 5

Buttons and keyboards are described in "Bot API: buttons, keyboards and commands".

Attachment object

Field

Type

Description

attachment_id

String

Attachment number

position

Integer

Order within the message, starting from 0

file_name

String

File name

mime_type

String

Content type

size_bytes

String

Size in bytes

width, height

Integer or null

Image or video dimensions

duration_ms

Integer or null

Audio or video duration

state

String

Media processing state; blocked means blocked by moderation

thumbnail_url, preview_url, play_url, download_url

String or null

Temporary links for preview, playback and download

expires_at

String

When the links expire; after that, read the message again

file_id

String

Bots only: an identifier for sending this file again without uploading it

file_unique_id

String

Bots only: a permanent identifier of the file itself, the same across messages

Send a message

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

Parameter

Type

Required

Description

client_message_id

String (UUID)

Yes

Idempotency key: new for each message, the same on retry

kind

String

Yes

text, media or poll

text

String

For text

Text with markup, up to 16,384 characters. For media, an optional caption

payload

Object

Yes

{} for plain text; buttons, keyboard, mentions, poll

send_as

String

No

Only self

reply_to_seq

String

No

Reply to the message with this seq

topic_id

String

No

Group topic

attachment_tokens

Array of String

For media

Up to 10 upload tokens, see "Files"

attachment_file_ids

Array of String

For media

Up to 10 file_id values of files the bot has already seen, instead of attachment_tokens

disable_notification

Boolean

No

true sends without a push notification; the message still counts as unread

Response: 201 Created, {"data": Message, "replayed": false}. A retry with the same client_message_id returns the message already sent: 200 OK, "replayed": true.

Example: a reply with buttons to message 7:

{
  "client_message_id": "ab751eda-e773-486c-8f74-3699c78110c8",
  "kind": "text",
  "text": "Order #42 is **packed**. Deliver today?",
  "payload": {"buttons": [[{"text": "Yes", "callback_data": "order:42:yes"}, {"text": "Later", "callback_data": "order:42:later"}]]},
  "reply_to_seq": "7",
  "send_as": "self"
}

Errors: 403 forbidden — the bot cannot write in this conversation; 403 blocked — the person has blocked the bot; 409 conversation_owned — an agent has taken the project request; 404 not_found — the conversation does not exist or the bot cannot see it; 422 validation_failed — invalid content.

Find a subscriber by email or phone

Your server usually knows a customer's email or phone, not the Sensever chat number. A person becomes the bot's subscriber when they open the bot (for example sensever.com/@your_bot) and tap Start. After that, find their chat:

GET /v1/chat/bot/chat?email=anna@example.com
GET /v1/chat/bot/chat?phone=447700900123

Response: 200 OK, {"chat_id": "901"} — send to it with POST /v1/chat/threads/901/messages.

  • Only the email or phone the person confirmed in their Sensever account counts. Write the phone in international format with digits only, without +: 447700900123. A + in a URL turns into a space unless it is written as %2B, so it is easier to leave it out (a leading + or %2B still works).

  • Limits per bot: up to 1,000 new addresses per 10 minutes and up to 300 "not a subscriber" answers per hour; beyond that 429 rate_limited with Retry-After. A mailing to people who did subscribe stays within them.

  • 404 subscriber_not_found — no such confirmed contact, the person has not tapped Start, has left the chat or has blocked the bot. All these cases give the same answer, so a bot learns nothing about people who did not subscribe to it.

  • In the Telegram-compatible API, put the email or phone directly into chat_id: {"chat_id": "anna@example.com", "text": "Your order is ready"}. There a phone keeps its + ("+447700900123"): digits alone in chat_id are a chat number.

Details

  • The bot never writes first. A bot token cannot create a conversation: the bot writes in a direct chat the person opened, and in groups and channels it was added to.

  • In a channel, the bot posts on behalf of the channel if its role is "Admin" or "Author".

  • No link previews: "payload": {"link_preview": false} on a text or media message.

  • Mentions: payload.mentions is a list of {"ref": "p.1104", "offset": 0, "length": 5, "text": "@anna"}, up to 100. offset and length are counted in UTF-16 code units, as in JavaScript; text must match that slice of the text and start with @. You can mention only a visible member of the conversation.

Text formatting

Markup goes directly into text, the same way the Sensever input field saves it:

Markup

Result

**bold**

bold

*italic*

italic

***bold italic***

bold italic

~~strikethrough~~

strikethrough text

`code`

monospace fragment; markup inside has no effect

triple backticks on separate lines

code block, line breaks are kept

[text](https://example.com)

link with text; http and https only

||spoiler||

hidden text revealed on tap; shown as ▒▒▒▒ in the chat list, push notifications and search

lines starting with >

quote

  • Emphasis works within a single line; the markup character must touch the text (**like this**, not ** like this **).

  • There is no escaping. To show markup characters literally, put them in `code`.

  • There is no underline.

  • http/https links in the text are detected automatically, without markup.

  • A /command in a bot message becomes a button that sends that command.

Read a message and history

GET /v1/chat/threads/{thread_id}/messages/{seq}

Response: {"data": Message}.

GET /v1/chat/threads/{thread_id}/messages?limit=30&before_seq=120

Parameter

Type

Required

Description

limit

Integer

No

From 1 to 100, default 50

before_seq

String

No

Messages older than this seq

after_seq

String

No

Messages newer than this seq

topic_id

String

No

Only this group topic

Response: {"messages": [Message, …], "pending": […], "page": {"has_more": true, "next_before_seq": "90", "next_after_seq": null}}. For the next page, pass page.next_before_seq as before_seq.

The bot reads history as a member: from the moment it joined, unless the group shows history to new members. Privacy mode in a group limits only updates, not reading history (see "Bot API: groups, channels and project requests").

Edit a message

PATCH /v1/chat/threads/{thread_id}/messages/{seq}

Parameter

Type

Required

Description

text

String or null

No

New text, up to 16,384 characters

payload

Object

No

The complete new payload: without buttons, the buttons disappear

At least one parameter is required. If you pass only text, payload stays the same. Response: {"data": Message}.

The bot can edit only its own messages; editing someone else's returns 403 forbidden, even if the bot is an admin. You cannot edit a poll (409 poll_definition_immutable) or the via_bot marker.

Delete a message

DELETE /v1/chat/threads/{thread_id}/messages/{seq}

No body. Response: 204 No Content; deleting again also succeeds.

The bot deletes its own messages. It can delete other people's messages only in a group or channel where it is an admin (or has the right to delete messages). In a project request, the bot does not moderate the visitor's messages.

Reactions

PUT /v1/chat/threads/{thread_id}/messages/{seq}/reactions
{"reaction": {"type": "emoji", "emoji": "👍"}}

Parameter

Type

Required

Description

reaction

ReactionType

Yes

{"type": "emoji", "emoji": "👍"} — like reaction in Telegram's setMessageReaction

active

Boolean

No

false removes the reaction; default true

Repeating a request with the same body gives the same result. Response: 204 No Content.

Only emoji from the GET /v1/chat/reactions list are allowed; otherwise you get 422 reaction_not_allowed. Spellings with and without U+FE0F count as one reaction ("❤" and "❤️"): the server stores the spelling from the list. {"type": "custom_emoji", …} is reserved and currently returns 422 unsupported_reaction_type.

One member can set up to 12 reactions on a message, and a message can have up to 32 distinct reactions; beyond that you get 409 reaction_limit. In a project request, the reaction is set on behalf of the project. The bot cannot vote in polls, bookmark messages or hide them.

Allowed reactions

GET /v1/chat/reactions

Response: {"data": {"available_reactions": [{"type": "emoji", "emoji": "👍"}, …], "max_per_member": 12, "max_distinct": 32}}. The list is in the order the chat shows reactions.

Legacy endpoint

PUT and DELETE /v1/chat/threads/{thread_id}/messages/{seq}/interactions/reaction/{emoji} (emoji in the path) still work but are deprecated: their responses carry the headers Deprecation: true, Sunset: Tue, 01 Dec 2026 00:00:00 GMT and a Link to the new endpoint. After December 1, 2026, the legacy endpoint may be turned off — switch to PUT …/reactions.

"Typing…"

POST /v1/chat/threads/{thread_id}/typing
{"active": true}

Shows "typing…" to members for 5 seconds; to keep the indicator longer, repeat the request every 4 seconds. {"active": false} removes the indicator immediately. The active parameter is optional and defaults to true. Response: 204 No Content. No more than 2 requests per 2 seconds per conversation. A visitor in the website widget sees the project bot's indicator.

Files

A file is sent as a kind: "media" message using one way of specifying files: upload tokens or file_id.

Option 1. Upload in three steps

1. Reserve an upload:

POST /v1/chat/uploads
{"thread_id": "901", "file_name": "invoice.pdf", "mime_type": "application/pdf", "size_bytes": "48213", "mode": "file"}

Parameter

Type

Required

Description

thread_id

String

Yes

The conversation the file will be sent to

file_name

String

Yes

File name, up to 255 characters, without / or \

mime_type

String

Yes

Content type, for example image/jpeg

size_bytes

String

Yes

Exact size in bytes

mode

String

No

media (default) — photos and videos are shown in the message at chat size; file — send as a document; hd — photos and videos in higher quality

Response 201 Created:

Field

Description

upload_token

Token for attachment_tokens

upload_url, method, headers

Where and how to upload the file: PUT to upload_url with these headers

tus

For large files: endpoint, metadata, chunk_bytes — resumable upload over the tus protocol

media_id

Media number

expires_at

The deadline for sending the message

Files larger than 50 MB can be uploaded only over the tus protocol: the response has no upload_url. The limit is 2 GB.

2. Upload the file with a PUT request to upload_url, using the headers from headers and the file bytes as the body.

3. Send the message:

{"client_message_id": "0a3c9d0e-5b3f-4d7c-8a1e-7f2b6c4d5e6f", "kind": "media", "text": "Invoice for September", "payload": {}, "attachment_tokens": ["<upload_token>"], "send_as": "self"}

Up to 10 files in one message; the caption goes in text.

Option 2. File from a URL

POST /v1/chat/threads/{thread_id}/uploads/url
{"url": "https://shop.example/files/catalog.pdf", "name": "catalog.pdf"}

Sensever downloads the file itself: https:// only, a public address, up to 20 MB. name is optional (by default, the name from the URL). Response: {"upload_token": "…"} for attachment_tokens. If the download fails: 422 file_download_failed.

Option 3. Resend by file_id

Attachments in messages the bot receives have a file_id. Pass it in attachment_file_ids (up to 10, without attachment_tokens), and the same file goes into a new message without uploading:

{"client_message_id": "5d6e7f80-91a2-4b3c-8d4e-5f6071829304", "kind": "media", "payload": {}, "attachment_file_ids": ["f1.901.7.0.Qm9ndXNTaWduYXR1cmUxMjM"], "send_as": "self"}

Permissions are checked on every send: the bot must still be able to see the message the file came from. Otherwise you get 404 not_found; a corrupted or forged file_id returns 422 invalid_file_id; a file blocked by moderation or deleted returns 422 attachment_failed.

Polls

A poll is a kind: "poll" message:

{
  "client_message_id": "7c1d2e3f-4a5b-4c6d-8e7f-8091a2b3c4d5",
  "kind": "poll",
  "payload": {"question": "When should we deliver?", "multiple": false, "options": [{"id": "today", "text": "Today"}, {"id": "later", "text": "Later"}]},
  "send_as": "self"
}

Payload field

Type

Description

question

String

Question, up to 500 characters

options

Array

From 2 to 10 options {"id", "text"}: id is 1–32 characters of [a-z0-9_-], unique; text is up to 200 characters

multiple

Boolean

Only false: a single answer

Votes arrive as a poll_answer update with option_ids. Polls are not anonymous: the bot sees who voted. Vote counts per option are in the message's counters.poll_votes.

Conversation and read receipts

GET /v1/chat/threads/{thread_id}

Returns {"data": {…}}, a description of the conversation: kind (dialog, group, channel), purpose, title, peer_ref and peer_kind for a direct chat, last_seq, capabilities (send, typing and others), and the bot's membership.

GET /v1/chat/threads/{thread_id}/receipts

Returns the read state of messages in the conversation.

Komentarze

Autorzy