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 |
|---|---|---|
| String | Conversation |
| String | Message number within the conversation |
| String | Signed reference to the message |
| String |
|
| Principal | Author. A channel post comes from the channel ( |
| Boolean | The message was sent by this bot |
| String or null | Text with markup; |
| Object | Data specific to the message kind: buttons, keyboard, poll, mentions, contact, inline mode marker |
| String or null | The UUID the author sent the message with |
| String or null | Topic in a group with topics |
| String or null | The message this one replies to |
| String or null | Reference to the original message if this is a forward |
| String | Time sent |
| String or null | Time of the last edit |
| String or null | Time deleted |
| String or null | When the message disappears, if it has an expiry |
| Object |
|
| Array | This bot's reactions: |
| Array of Attachment | Message files |
| Array | Links found in the text, with previews |
| Boolean | Internal counter flags |
| — | Internal fields of channel posts |
Payload fields
Field | Type | Where it appears |
|---|---|---|
| Array of Array of InlineKeyboardButton | Bot messages with inline buttons |
| ReplyKeyboard | Bot messages that set or remove the keyboard below the input field |
| Array of Mention | Mentions in the text |
| Object | The person shared their number with a |
| Object | The message was sent through inline mode: |
| — | Poll ( |
| Integer | Request rating ( |
Buttons and keyboards are described in "Bot API: buttons, keyboards and commands".
Attachment object
Field | Type | Description |
|---|---|---|
| String | Attachment number |
| Integer | Order within the message, starting from 0 |
| String | File name |
| String | Content type |
| String | Size in bytes |
| Integer or null | Image or video dimensions |
| Integer or null | Audio or video duration |
| String | Media processing state; |
| String or null | Temporary links for preview, playback and download |
| String | When the links expire; after that, read the message again |
| String | Bots only: an identifier for sending this file again without uploading it |
| String | Bots only: a permanent identifier of the file itself, the same across messages |
Send a message
POST /v1/chat/threads/{thread_id}/messagesParameter | Type | Required | Description |
|---|---|---|---|
| String (UUID) | Yes | Idempotency key: new for each message, the same on retry |
| String | Yes |
|
| String | For | Text with markup, up to 16,384 characters. For |
| Object | Yes |
|
| String | No | Only |
| String | No | Reply to the message with this |
| String | No | Group topic |
| Array of String | For | Up to 10 upload tokens, see "Files" |
| Array of String | For | Up to 10 |
| Boolean | No |
|
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=447700900123Response: 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%2Bstill 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_limitedwithRetry-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 inchat_idare 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 atextormediamessage.Mentions:
payload.mentionsis a list of{"ref": "p.1104", "offset": 0, "length": 5, "text": "@anna"}, up to 100.offsetandlengthare counted in UTF-16 code units, as in JavaScript;textmust 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 |
| italic |
| bold italic |
| strikethrough text |
| monospace fragment; markup inside has no effect |
triple backticks on separate lines | code block, line breaks are kept |
| link with text; |
| hidden text revealed on tap; shown as |
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/httpslinks in the text are detected automatically, without markup.A
/commandin 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=120Parameter | Type | Required | Description |
|---|---|---|---|
| Integer | No | From 1 to 100, default 50 |
| String | No | Messages older than this |
| String | No | Messages newer than this |
| 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 |
|---|---|---|---|
| String or null | No | New text, up to 16,384 characters |
| Object | No | The complete new |
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 |
|---|---|---|---|
| ReactionType | Yes |
|
| Boolean | No |
|
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/reactionsResponse: {"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 |
|---|---|---|---|
| String | Yes | The conversation the file will be sent to |
| String | Yes | File name, up to 255 characters, without |
| String | Yes | Content type, for example |
| String | Yes | Exact size in bytes |
| String | No |
|
Response 201 Created:
Field | Description |
|---|---|
| Token for |
| Where and how to upload the file: |
| For large files: |
| Media number |
| 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 |
|---|---|---|
| String | Question, up to 500 characters |
| Array | From 2 to 10 options |
| Boolean | Only |
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}/receiptsReturns the read state of messages in the conversation.
মন্তব্য