Bot API: messages and channels
Learn the requests a bot uses to list channels, post, edit and delete messages, read channel history, open direct chats and attach files.
This page describes the requests a bot uses for conversations: listing its channels, posting messages, reading history, opening direct chats and attaching files. Every request needs a bot key. A workspace owner or admin issues the key in the workspace settings: on the Bots tab, open the bot’s page and find the API tokens section. The API address, the header that carries the key and the common error codes are on the page Bot API.
Every path is relative to the address https://ai-syncra.ru/api/bot/v1.
Channels
A bot reads and posts only in channels it is a member of. It can join a public channel on its own. An owner or admin adds it to a private channel in the Channels section of the bot’s page.
GET /channels
Returns every public channel of the workspace, plus every channel and direct chat the bot is already in. The list is sorted by name.
No parameters.
curl "https://ai-syncra.ru/api/bot/v1/channels" \
-H "Authorization: Bearer skb_..."
Response 200:
[
{ "id": "3a4b5c6d7e8f90a1b2c3d4e5f6071829", "name": "deploys", "type": "public", "isMember": true },
{ "id": "7e8f90a1b2c3d4e5f60718293a4b5c6d", "name": "general", "type": "public", "isMember": false }
]
| Field | Type | Description |
|---|---|---|
id |
string | The channel id. Pass it as channelId |
name |
string | The channel name |
type |
string | public is a public channel, private a private one, dm a direct chat, groupDm a group direct chat |
isMember |
boolean | Whether the bot is a member. It can read and post only when this is true |
POST /channels/:channelId/join
Adds the bot to a public channel. If the bot is already in the channel, the request still succeeds.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channelId |
path | string | yes | A channel id from GET /channels |
curl -X POST "https://ai-syncra.ru/api/bot/v1/channels/7e8f90a1b2c3d4e5f60718293a4b5c6d/join" \
-H "Authorization: Bearer skb_..."
Response 200:
{ "ok": true }
Errors:
| Code | Body | Reason |
|---|---|---|
404 |
{"error":"Channel not found"} |
The channel does not exist in the key’s workspace |
403 |
{"error":"Only public channels can be joined"} |
The channel is not public |
Messages
POST /messages
Posts a message as the bot in a channel or a direct chat. With parentMessageId it posts a reply in a thread.
| Parameter | Type | Required | Description |
|---|---|---|---|
channelId |
string | yes | A channel or direct chat the bot is a member of |
text |
string | yes | The message text, 1 to 4,000 characters |
parentMessageId |
string | no | The message whose thread the reply goes into. It must be a top-level message of the same channel: not a thread reply and not deleted |
clientNonce |
string | no | Your own label for the message, 1 to 100 characters. It prevents duplicates when you retry |
attachments |
array | no | Files, up to 10. See the Files section below for the format |
curl -X POST "https://ai-syncra.ru/api/bot/v1/messages" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{
"channelId": "3a4b5c6d7e8f90a1b2c3d4e5f6071829",
"text": "Build 142 passed",
"clientNonce": "build-142"
}'
Response 200:
{ "ok": true, "messageId": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40", "deduplicated": false }
| Field | Type | Description |
|---|---|---|
messageId |
string | The message id. You need it to edit or delete the message and to reply in its thread |
deduplicated |
boolean | true when a message with this clientNonce was already posted and the request returned it instead of creating a new one |
How clientNonce works. Each message needs its own label, unique within the workspace. If you repeat the request with the same label, channel and thread, Syncra returns the id of the message it already posted. Do not reuse one label for different messages: if a message in another channel or another thread already holds it, or the message that holds it was deleted, the request fails with a 500 error.
Errors:
| Code | Body | Reason |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
The request body is not valid JSON |
400 |
{"error":"invalid attachment"} |
A file in attachments is not in storage, was uploaded by someone other than this bot, or is described wrongly |
400 |
{"error":"attachment size exceeds limit"} |
A file is over the allowed size |
403 |
{"error":"Bot is not a member of this channel"} |
The bot is not a member of the channel |
404 |
{"error":"Channel not found"} |
The channel does not exist in the key’s workspace |
404 |
{"error":"Parent message not found"} |
parentMessageId does not fit: the message is in another channel, is deleted, or sits inside a thread itself |
422 |
{"error":"Validation error","details":{...}} |
channelId or text is missing, the text is empty or longer than 4,000 characters, or there are more than 10 files |
PATCH /messages/:messageId
Changes the text of a message this bot posted. Members then see the message marked as edited. There is no time limit: a bot can edit its own message at any time while it is a member of the channel.
Use it to keep one status message up to date, for example “Build running” and later “Build passed”.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
messageId |
path | string | yes | The id of the bot’s message |
text |
body | string | yes | The new text, 1 to 4,000 characters |
attachments |
body | array | no | The new set of files, up to 10. When the field is sent, it replaces the previous set, and an empty array removes every file. When the field is absent, the files stay as they were |
curl -X PATCH "https://ai-syncra.ru/api/bot/v1/messages/9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{"text":"Build 142 passed and is deployed"}'
Response 200:
{ "ok": true, "messageId": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40" }
Errors:
| Code | Body | Reason |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
The request body is not valid JSON |
403 |
{"error":"Bot is not a member of this channel"} |
The bot is no longer a member of the message’s channel |
404 |
{"error":"Message not found"} |
The message does not exist, is deleted, or was not written by this bot |
422 |
{"error":"Validation error","details":{...}} |
text is missing, empty or longer than 4,000 characters |
DELETE /messages/:messageId
Deletes a message this bot posted. A bot can delete its own message even after it was removed from the channel.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
messageId |
path | string | yes | The id of the bot’s message |
curl -X DELETE "https://ai-syncra.ru/api/bot/v1/messages/9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40" \
-H "Authorization: Bearer skb_..."
Response 200:
{
"id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40",
"deleted": true,
"deletedAt": "2026-11-10T09:31:12.480Z"
}
Repeating the request for a message that is already deleted also answers 200, with "deleted": false and the earlier time in deletedAt.
Error: 404 with the body {"error":"Message not found"} when the message does not exist in the key’s workspace or was not written by this bot.
GET /messages
Reads the history of a channel the bot is a member of. Messages come newest first, and deleted messages are left out. Thread replies come in the same list, with parentMessageId filled in.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channelId |
query | string | yes | A channel or direct chat the bot is a member of |
limit |
query | number | no | How many messages to return, 1 to 100. The default is 30 |
before |
query | string | no | A message id. Only messages older than it are returned |
curl "https://ai-syncra.ru/api/bot/v1/messages?channelId=3a4b5c6d7e8f90a1b2c3d4e5f6071829&limit=50" \
-H "Authorization: Bearer skb_..."
Response 200:
[
{
"id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40",
"body": "Build 142 passed",
"authorId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
"authorName": "Deploy bot",
"authorIsBot": true,
"parentMessageId": null,
"createdAt": "2026-11-10T09:30:00.000Z"
}
]
| Field | Type | Description |
|---|---|---|
id |
string | The message id |
body |
string | The message text |
authorId |
string | The author’s id |
authorName |
string | The author’s name |
authorIsBot |
boolean | true when the author is a bot |
parentMessageId |
string or null | The top message of the thread, when this is a thread reply |
createdAt |
string | When it was sent, ISO 8601 in UTC |
How to page. The response is a bare array with no total count and no link to the next page. To get older messages, take the id of the last message in the array and pass it as before. When the array comes back shorter than limit, you have reached the start of the history.
Errors:
| Code | Body | Reason |
|---|---|---|
400 |
{"error":"channelId is required"} |
The request has no channelId |
403 |
{"error":"Bot is not a member of this channel"} |
The bot is not a member of the channel |
404 |
{"error":"Channel not found"} |
The channel does not exist in the key’s workspace |
404 |
{"error":"Cursor message not found"} |
The message from before is not in this channel |
Direct messages
POST /dms
Opens a direct chat between the bot and a member of the workspace. If the chat already exists, the request returns it. With text it also sends a message into the chat.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId |
string | yes | The member’s id. It is the same id that comes in authorId of messages and assigneeId of tasks |
text |
string | no | A first message, up to 4,000 characters |
curl -X POST "https://ai-syncra.ru/api/bot/v1/dms" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{"userId":"b2c3d4e5f60718293a4b5c6d7e8f90a1","text":"Your report is ready"}'
Response 200 when text is sent:
{ "channelId": "c3d4e5f60718293a4b5c6d7e8f90a1b2", "messageId": "d4e5f60718293a4b5c6d7e8f90a1b2c3" }
Response 200 without text:
{ "channelId": "c3d4e5f60718293a4b5c6d7e8f90a1b2" }
Pass the returned channelId to POST /messages and GET /messages: from then on the bot works with the direct chat as with any channel.
Errors:
| Code | Body | Reason |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
The request body is not valid JSON |
404 |
{"error":"User not found"} |
No such member in the workspace, or the member is deactivated |
422 |
{"error":"Validation error","details":{...}} |
userId is missing or the text is longer than 4,000 characters |
The bot API has no member list. A bot learns a person’s id from messages (authorId), from tasks (assigneeId, createdBy) and from the events that arrive through event subscriptions.
Files
Attaching a file to a message takes three steps: get an upload address, send the file to it, then describe the file in attachments of the message.
POST /uploads/presign
Returns an upload address and form fields for one file. The address is valid for one hour.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The file name, 1 to 255 characters |
contentType |
string | yes | The content type, for example application/pdf. Up to 255 characters. If you do not know the type, send application/octet-stream and Syncra works it out from the file extension |
size |
number | yes | The file size in bytes, a whole number above zero |
curl -X POST "https://ai-syncra.ru/api/bot/v1/uploads/presign" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{"name":"report.pdf","contentType":"application/pdf","size":482113}'
Response 200:
{
"key": "uploads/a1b2c3d4e5f60718293a4b5c6d7e8f90/6f5e4d3c2b1a0f9e8d7c6b5a40392817/report.pdf",
"name": "report.pdf",
"contentType": "application/pdf",
"size": 482113,
"url": "https://...",
"fields": { "...": "..." }
}
| Field | Type | Description |
|---|---|---|
key |
string | The file’s key in storage. Pass it in attachments |
name |
string | The file name as Syncra stores it. It can differ from the one you sent |
contentType |
string | The type Syncra stores the file under. It can differ from the one you sent |
size |
number | The size from the request |
url |
string | The address to send the file to |
fields |
object | Form fields to send together with the file |
Errors:
| Code | Body | Reason |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
The request body is not valid JSON |
422 |
{"error":"Invalid request"} |
A required field is missing or a value does not fit |
422 |
{"error":"Unsupported file type"} |
Syncra does not accept files of this type |
422 |
{"error":"Attachment size exceeds limit"} |
The file is over the allowed size |
The allowed size depends on the kind of file and on the workspace settings. Whatever the settings, the request never accepts a file over 4 GB.
Upload the file and attach it
Step 1. Get url, fields and key with POST /uploads/presign.
Step 2. Send the file to url with a POST request in multipart/form-data format. Add every pair from fields to the form first, and the file itself as the last field, named file. This request needs no Authorization header.
curl -X POST "<url from the response>" \
-F "<field name from fields>=<its value>" \
-F "file=@report.pdf"
Add one -F option for each pair in fields.
Step 3. Pass the file in attachments of POST /messages or PATCH /messages/:messageId. Take key, name and contentType from the response of step 1.
curl -X POST "https://ai-syncra.ru/api/bot/v1/messages" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{
"channelId": "3a4b5c6d7e8f90a1b2c3d4e5f6071829",
"text": "Weekly report",
"attachments": [
{
"key": "uploads/a1b2c3d4e5f60718293a4b5c6d7e8f90/6f5e4d3c2b1a0f9e8d7c6b5a40392817/report.pdf",
"name": "report.pdf",
"contentType": "application/pdf",
"size": 482113
}
]
}'
Fields of one file in attachments:
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | The key from the POST /uploads/presign response |
name |
string | yes | The file name, 1 to 255 characters |
contentType |
string | yes | The content type |
size |
number | yes | The size in bytes |
width |
number | no | Image width in pixels |
height |
number | no | Image height in pixels |
A bot can attach only a file it uploaded itself. Before posting, Syncra checks that a file with this key is really in storage. If it is not, POST /messages answers 400 with the body {"error":"invalid attachment"}.
What is not here
GET /messagesdoes not return the files of messages, and a bot key cannot download a file.- There are no reactions, pinned messages, search or member list.
- A bot cannot edit or delete someone else’s message.
- The bot API cannot create a channel.
To learn about new messages without requesting the history again and again, set up event subscriptions. The full list of limits is on the page What exists and what does not.