РазделAPI ботов: сообщения и каналы

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 ботов нельзя.

Чтобы узнавать о новых сообщениях без опроса истории, настройте подписки на события. Полный список ограничений — на странице «Что есть и чего нет».