SectionBot API: messages and channels

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 /messages does 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.