API ботов: сообщения и каналы
Какими запросами бот узнаёт каналы, пишет, меняет и удаляет сообщения, читает историю, открывает личные чаты и прикладывает файлы.
Эта страница описывает запросы, которыми бот работает с перепиской: узнаёт свои каналы, пишет сообщения, читает историю, открывает личные чаты и прикладывает файлы. Для них нужен ключ бота. Его выпускает владелец или администратор рабочего пространства: настройки пространства, вкладка «Боты», раздел «API-токены» на странице бота. Адрес API, заголовок с ключом и общие коды ошибок описаны на странице «API ботов».
Все пути записаны от адреса https://ai-syncra.ru/api/bot/v1.
Каналы
Бот читает и пишет только в каналах, где он состоит. В открытый канал он может вступить сам. В закрытый канал его добавляет владелец или администратор: раздел «Каналы» на странице бота.
GET /channels
Возвращает все открытые каналы рабочего пространства и все каналы и чаты, в которых бот уже состоит. Список отсортирован по имени.
Параметров нет.
curl "https://ai-syncra.ru/api/bot/v1/channels" \
-H "Authorization: Bearer skb_..."
Ответ 200:
[
{ "id": "3a4b5c6d7e8f90a1b2c3d4e5f6071829", "name": "deploys", "type": "public", "isMember": true },
{ "id": "7e8f90a1b2c3d4e5f60718293a4b5c6d", "name": "general", "type": "public", "isMember": false }
]
| Поле | Тип | Описание |
|---|---|---|
id |
string | Идентификатор канала. Его передают в channelId |
name |
string | Имя канала |
type |
string | public — открытый канал, private — закрытый, dm — личный чат, groupDm — групповой личный чат |
isMember |
boolean | Состоит ли бот в канале. Писать и читать можно только при true |
POST /channels/:channelId/join
Добавляет бота в открытый канал. Повторный запрос для канала, где бот уже состоит, тоже отвечает успехом.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
channelId |
путь | string | да | Идентификатор канала из GET /channels |
curl -X POST "https://ai-syncra.ru/api/bot/v1/channels/7e8f90a1b2c3d4e5f60718293a4b5c6d/join" \
-H "Authorization: Bearer skb_..."
Ответ 200:
{ "ok": true }
Ошибки:
| Код | Тело | Причина |
|---|---|---|
404 |
{"error":"Channel not found"} |
Канала нет в рабочем пространстве ключа |
403 |
{"error":"Only public channels can be joined"} |
Канал не открытый |
Сообщения
POST /messages
Публикует сообщение от имени бота в канале или личном чате. С полем parentMessageId публикует ответ в ветке.
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
channelId |
string | да | Канал или личный чат, в котором состоит бот |
text |
string | да | Текст сообщения, от 1 до 4000 символов |
parentMessageId |
string | нет | Сообщение, под которым открыта ветка. Это должно быть корневое сообщение из того же канала: не ответ в ветке и не удалённое |
clientNonce |
string | нет | Ваша метка сообщения, от 1 до 100 символов. Защищает от дублей при повторе запроса |
attachments |
array | нет | Файлы, до 10 штук. Формат описан ниже, в разделе «Файлы» |
curl -X POST "https://ai-syncra.ru/api/bot/v1/messages" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{
"channelId": "3a4b5c6d7e8f90a1b2c3d4e5f6071829",
"text": "Сборка 142 прошла",
"clientNonce": "build-142"
}'
Ответ 200:
{ "ok": true, "messageId": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40", "deduplicated": false }
| Поле | Тип | Описание |
|---|---|---|
messageId |
string | Идентификатор сообщения. Нужен, чтобы изменить или удалить сообщение и чтобы ответить в его ветке |
deduplicated |
boolean | true, если сообщение с таким clientNonce уже было опубликовано и запрос вернул его, а не создал новое |
Как работает clientNonce. Метка должна быть своей у каждого сообщения в пределах рабочего пространства. Повторите запрос с той же меткой, тем же каналом и той же веткой, и Syncra вернёт идентификатор уже опубликованного сообщения. Не используйте одну метку для разных сообщений: если она уже занята сообщением из другого канала или другой ветки или сообщение с ней удалено, запрос завершится ошибкой 500.
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
Тело запроса — некорректный JSON |
400 |
{"error":"invalid attachment"} |
Файл из attachments не найден в хранилище, загружен не этим ботом или описан неверно |
400 |
{"error":"attachment size exceeds limit"} |
Файл больше допустимого размера |
403 |
{"error":"Bot is not a member of this channel"} |
Бот не состоит в канале |
404 |
{"error":"Channel not found"} |
Канала нет в рабочем пространстве ключа |
404 |
{"error":"Parent message not found"} |
parentMessageId не подходит: сообщение из другого канала, удалено или само лежит в ветке |
422 |
{"error":"Validation error","details":{...}} |
Нет channelId или text, текст пустой или длиннее 4000 символов, файлов больше 10 |
PATCH /messages/:messageId
Меняет текст сообщения, которое отправил этот бот. Рядом с сообщением появляется пометка об изменении. Ограничения по времени нет: бот может изменить своё сообщение когда угодно, пока состоит в канале.
Так одно сообщение может показывать ход работы: сначала «Сборка идёт», затем «Сборка прошла».
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
messageId |
путь | string | да | Идентификатор сообщения бота |
text |
тело | string | да | Новый текст, от 1 до 4000 символов |
attachments |
тело | array | нет | Новый набор файлов, до 10 штук. Если поле передано, он заменяет прежний набор; пустой массив убирает все файлы. Если поля нет, файлы остаются как были |
curl -X PATCH "https://ai-syncra.ru/api/bot/v1/messages/9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{"text":"Сборка 142 прошла и выкачена"}'
Ответ 200:
{ "ok": true, "messageId": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40" }
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
Тело запроса — некорректный JSON |
403 |
{"error":"Bot is not a member of this channel"} |
Бот больше не состоит в канале сообщения |
404 |
{"error":"Message not found"} |
Сообщения нет, оно удалено или его написал не этот бот |
422 |
{"error":"Validation error","details":{...}} |
Нет text, текст пустой или длиннее 4000 символов |
DELETE /messages/:messageId
Удаляет сообщение, которое отправил этот бот. Удалить своё сообщение можно и после того, как бота убрали из канала.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
messageId |
путь | string | да | Идентификатор сообщения бота |
curl -X DELETE "https://ai-syncra.ru/api/bot/v1/messages/9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40" \
-H "Authorization: Bearer skb_..."
Ответ 200:
{
"id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40",
"deleted": true,
"deletedAt": "2026-11-10T09:31:12.480Z"
}
Повторный запрос для уже удалённого сообщения тоже отвечает 200, но с "deleted": false и прежним временем в deletedAt.
Ошибка: 404 с телом {"error":"Message not found"}, если сообщения нет в рабочем пространстве ключа или его написал не этот бот.
GET /messages
Читает историю канала, в котором состоит бот. Сообщения идут от новых к старым. Удалённых сообщений в ответе нет. Ответы в ветках приходят в том же списке, у них заполнено поле parentMessageId.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
channelId |
строка запроса | string | да | Канал или личный чат, в котором состоит бот |
limit |
строка запроса | number | нет | Сколько сообщений вернуть, от 1 до 100. По умолчанию 30 |
before |
строка запроса | string | нет | Идентификатор сообщения. В ответ попадут только сообщения старше него |
curl "https://ai-syncra.ru/api/bot/v1/messages?channelId=3a4b5c6d7e8f90a1b2c3d4e5f6071829&limit=50" \
-H "Authorization: Bearer skb_..."
Ответ 200:
[
{
"id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40",
"body": "Сборка 142 прошла",
"authorId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
"authorName": "Deploy bot",
"authorIsBot": true,
"parentMessageId": null,
"createdAt": "2026-11-10T09:30:00.000Z"
}
]
| Поле | Тип | Описание |
|---|---|---|
id |
string | Идентификатор сообщения |
body |
string | Текст сообщения |
authorId |
string | Идентификатор автора |
authorName |
string | Имя автора |
authorIsBot |
boolean | true, если автор — бот |
parentMessageId |
string или null | Корневое сообщение ветки, если это ответ в ветке |
createdAt |
string | Время отправки, ISO 8601 по UTC |
Как листать дальше. Ответ — это массив без общего числа сообщений и без ссылки на следующую страницу. Возьмите id последнего сообщения в массиве и передайте его в before. Когда массив пришёл короче, чем limit, история закончилась.
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"channelId is required"} |
В запросе нет channelId |
403 |
{"error":"Bot is not a member of this channel"} |
Бот не состоит в канале |
404 |
{"error":"Channel not found"} |
Канала нет в рабочем пространстве ключа |
404 |
{"error":"Cursor message not found"} |
Сообщения из before нет в этом канале |
Личные сообщения
POST /dms
Открывает личный чат бота с участником рабочего пространства. Если чат уже есть, возвращает его. С полем text сразу отправляет в чат сообщение.
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
userId |
string | да | Идентификатор участника. Это тот же идентификатор, что приходит в authorId сообщений и в assigneeId задач |
text |
string | нет | Первое сообщение, до 4000 символов |
curl -X POST "https://ai-syncra.ru/api/bot/v1/dms" \
-H "Authorization: Bearer skb_..." \
-H "Content-Type: application/json" \
-d '{"userId":"b2c3d4e5f60718293a4b5c6d7e8f90a1","text":"Ваш отчёт готов"}'
Ответ 200, если передан text:
{ "channelId": "c3d4e5f60718293a4b5c6d7e8f90a1b2", "messageId": "d4e5f60718293a4b5c6d7e8f90a1b2c3" }
Ответ 200 без text:
{ "channelId": "c3d4e5f60718293a4b5c6d7e8f90a1b2" }
Полученный channelId подходит для POST /messages и GET /messages: дальше личный чат работает как обычный канал.
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
Тело запроса — некорректный JSON |
404 |
{"error":"User not found"} |
Такого участника нет в рабочем пространстве или он деактивирован |
422 |
{"error":"Validation error","details":{...}} |
Нет userId или текст длиннее 4000 символов |
Списка участников в API ботов нет. Идентификатор человека бот узнаёт из сообщений (authorId), из задач (assigneeId, createdBy) и из событий, которые приходят по подпискам на события.
Файлы
Чтобы приложить файл к сообщению, сделайте три шага: получите адрес для загрузки, отправьте на него файл, передайте описание файла в поле attachments сообщения.
POST /uploads/presign
Выдаёт адрес и поля формы для загрузки одного файла. Адрес действует один час.
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
name |
string | да | Имя файла, от 1 до 255 символов |
contentType |
string | да | Тип содержимого, например application/pdf. До 255 символов. Если тип неизвестен, передайте application/octet-stream: Syncra определит его по расширению |
size |
number | да | Размер файла в байтах, целое число больше нуля |
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}'
Ответ 200:
{
"key": "uploads/a1b2c3d4e5f60718293a4b5c6d7e8f90/6f5e4d3c2b1a0f9e8d7c6b5a40392817/report.pdf",
"name": "report.pdf",
"contentType": "application/pdf",
"size": 482113,
"url": "https://...",
"fields": { "...": "..." }
}
| Поле | Тип | Описание |
|---|---|---|
key |
string | Ключ файла в хранилище. Его передают в attachments |
name |
string | Имя файла после очистки. Может отличаться от присланного |
contentType |
string | Тип, под которым Syncra сохранит файл. Может отличаться от присланного |
size |
number | Размер из запроса |
url |
string | Адрес, на который отправляют файл |
fields |
object | Поля формы, которые нужно отправить вместе с файлом |
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
Тело запроса — некорректный JSON |
422 |
{"error":"Invalid request"} |
Нет обязательного поля или значение не подошло |
422 |
{"error":"Unsupported file type"} |
Файлы такого типа Syncra не принимает |
422 |
{"error":"Attachment size exceeds limit"} |
Файл больше допустимого размера |
Допустимый размер зависит от вида файла и от настроек рабочего пространства. Больше 4 ГБ запрос не принимает ни при каких настройках.
Как загрузить файл и приложить его
Шаг 1. Получите url, fields и key запросом POST /uploads/presign.
Шаг 2. Отправьте файл на url запросом POST в формате multipart/form-data. Сначала добавьте в форму каждую пару из fields, последним полем — сам файл под именем file. Заголовок Authorization в этом запросе не нужен.
curl -X POST "<url из ответа>" \
-F "<имя поля из fields>=<его значение>" \
-F "file=@report.pdf"
Параметр -F для полей повторите столько раз, сколько пар в fields.
Шаг 3. Передайте файл в attachments запроса POST /messages или PATCH /messages/:messageId. Значения key, name и contentType возьмите из ответа шага 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": "Отчёт за неделю",
"attachments": [
{
"key": "uploads/a1b2c3d4e5f60718293a4b5c6d7e8f90/6f5e4d3c2b1a0f9e8d7c6b5a40392817/report.pdf",
"name": "report.pdf",
"contentType": "application/pdf",
"size": 482113
}
]
}'
Поля одного файла в attachments:
| Поле | Тип | Обязателен | Описание |
|---|---|---|---|
key |
string | да | Ключ из ответа POST /uploads/presign |
name |
string | да | Имя файла, от 1 до 255 символов |
contentType |
string | да | Тип содержимого |
size |
number | да | Размер в байтах |
width |
number | нет | Ширина изображения в пикселях |
height |
number | нет | Высота изображения в пикселях |
Бот может приложить только файл, который загрузил сам. Перед публикацией Syncra проверяет, что файл с таким key действительно лежит в хранилище. Если нет, POST /messages отвечает 400 с телом {"error":"invalid attachment"}.
Чего здесь нет
- Запрос
GET /messagesне возвращает файлы сообщений, и скачать файл с ключом бота нельзя. - Нет реакций, закрепления сообщений, поиска и списка участников.
- Бот не может изменить или удалить чужое сообщение.
- Создать канал через API ботов нельзя.
Чтобы узнавать о новых сообщениях без опроса истории, настройте подписки на события. Полный список ограничений — на странице «Что есть и чего нет».