РазделДокументация для разработчиков

Документация для разработчиков

Как подключить свою программу к Syncra — через свой ИИ, бота, вебхуки или слеш-команды, — какие ключи для этого нужны и как отправить первый запрос одной командой cURL.

Syncra — рабочее приложение, в котором у команды чат, задачи, база знаний и созвоны. Эта документация для разработчика, который хочет, чтобы его программа читала и писала в рабочем пространстве: присылала уведомления в канал, заводила задачи, отвечала на команды или давала ИИ-приложению доступ к чатам. Своё ИИ-приложение подключает любой участник: окно «Настройки», раздел «Подключённые приложения». Ботов, ключи и вебхуки создаёт владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты».

Способы подключиться

Способ Что происходит Чем подтверждается запрос Когда подходит
Свой ИИ Приложение работает от имени человека, который его подключил Человек входит в браузере и нажимает «Разрешить». Ключ создавать не нужно Claude, ChatGPT, Cursor или ваш агент должен работать с чатами, задачами и базой знаний
Бот и его API Программа работает от имени бота. Бот — отдельный участник рабочего пространства Ключ skb_... в заголовке Authorization Программа пишет и читает сообщения, меняет задачи
Входящий вебхук Бот публикует ваш текст в одном выбранном канале Секрет whk_... прямо в адресе Нужно отправить текст в канал одним запросом
Подписки на события Syncra сама шлёт запрос на ваш адрес, когда что-то произошло Подпись секретом whsec_... Программа должна узнавать о новых сообщениях, задачах и страницах
Слеш-команды Человек пишет команду в канале, Syncra шлёт запрос на ваш адрес Подпись секретом whsec_... Команда вида /deploy должна запускать ваш код

Свой ИИ подключается по MCP. MCP (Model Context Protocol) — открытый стандарт, по которому ИИ-приложения вызывают действия внешних сервисов. Syncra даёт для этого один адрес, https://ai-syncra.ru/api/mcp. Что именно умеет подключённое приложение, описано на странице Инструменты для ИИ.

Первый запрос

Проще всего начать со входящего вебхука. Вы получаете секретный адрес, отправляете на него текст, и бот публикует этот текст в канале.

  1. Откройте настройки рабочего пространства, вкладку «Боты». Нужна роль владельца или администратора.
  2. Нажмите «Новый бот», заполните «Имя» и нажмите «Создать бота».
  3. На странице бота найдите раздел «Входящие вебхуки». В поле «Канал» выберите канал и нажмите «Создать вебхук». Бот сам вступит в этот канал.
  4. Скопируйте адрес вебхука и подставьте его в запрос ниже.

POST /api/webhooks/:token

Публикует сообщение от имени бота в канале, к которому привязан вебхук.

Параметр Где Тип Обязателен Описание
token путь строка да Секрет вебхука, начинается с whk_. Заголовок Authorization не нужен
text тело строка да Текст сообщения, от 1 до 4000 символов
curl -X POST "https://ai-syncra.ru/api/webhooks/whk_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Сборка 142 прошла"}'

Ответ 200:

{
  "ok": true,
  "messageId": "..."
}

Сообщение сразу видят все участники канала, обновлять страницу им не нужно.

Код Тело ответа Что случилось
400 {"error":"Invalid JSON"} Тело запроса не разбирается как JSON
404 {"error":"Not found"} Такого вебхука нет, либо вебхук или бот выключен
422 {"error":"Validation error","details":{...}} Поля text нет, оно пустое или длиннее 4000 символов
429 {"error":"Too many requests"} Больше 60 запросов за 60 секунд на один вебхук

Адрес вебхука — это секрет: тот, кто его знает, может писать в канал. Не кладите его в открытый код. Подробности и ограничения — на странице Входящие вебхуки.

Ключи и секреты

У каждого способа свой ключ. По началу строки видно, что это за ключ.

Начало Что это Где взять Куда передавать
skb_ Ключ бота Страница бота, раздел «API-токены», кнопка «Создать токен». Полный ключ показывается один раз Заголовок Authorization: Bearer skb_... в запросах к /api/bot/v1
whk_ Секрет входящего вебхука Страница бота, раздел «Входящие вебхуки» В адресе запроса
whsec_ Секрет подписи Свой у каждой подписки на события и у каждой слеш-команды Никуда: им вы проверяете подпись запросов, которые прислала Syncra
syncat_ Ключ доступа ИИ-приложения Приложение получает его само, когда человек нажал «Разрешить» Заголовок Authorization: Bearer syncat_... в запросах к /api/mcp

Общие правила

  • Адрес для всех запросов: https://ai-syncra.ru.
  • Тела запросов и ответов — JSON. Исключения — POST /api/oauth/token и POST /api/oauth/revoke: по правилам OAuth, стандарта входа приложений от имени человека, их отправляют формой, JSON они тоже принимают. POST /api/oauth/revoke отвечает пустым телом.
  • Версия в адресе есть только у API ботов: /api/bot/v1.
  • Ошибка приходит как JSON с полем error. У некоторых ошибок есть поле code.
  • Бот работает в одном рабочем пространстве: в том, где его создали.

Чего нет

  • Личных API-токенов нет. Внешняя программа работает от имени человека через подключение по MCP, после того как человек нажал «Разрешить».
  • Готовой библиотеки для разработчиков (SDK) и пакета в npm нет. Примеры в этой документации написаны на cURL.
  • Отдельного канала с событиями в реальном времени для внешних программ нет. О событиях бот узнаёт через подписки.

Полный список — на странице Что есть и чего нет.

Куда дальше

Вопросы по подключению пишите команде Syncra в Telegram: https://t.me/morzac.