Документация для разработчиков
Как подключить свою программу к 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. Что именно умеет подключённое приложение, описано на странице Инструменты для ИИ.
Первый запрос
Проще всего начать со входящего вебхука. Вы получаете секретный адрес, отправляете на него текст, и бот публикует этот текст в канале.
- Откройте настройки рабочего пространства, вкладку «Боты». Нужна роль владельца или администратора.
- Нажмите «Новый бот», заполните «Имя» и нажмите «Создать бота».
- На странице бота найдите раздел «Входящие вебхуки». В поле «Канал» выберите канал и нажмите «Создать вебхук». Бот сам вступит в этот канал.
- Скопируйте адрес вебхука и подставьте его в запрос ниже.
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.
- Отдельного канала с событиями в реальном времени для внешних программ нет. О событиях бот узнаёт через подписки.
Полный список — на странице Что есть и чего нет.
Куда дальше
- Подключить свой ИИ: адрес сервера, вход, шаги для Claude, ChatGPT и Cursor.
- Инструменты для ИИ: что подключённое приложение может делать в Syncra.
- Боты: что такое бот, как его создать и получить ключ.
- API ботов: адрес, авторизация, ошибки, первый вызов.
- Сообщения и задачи в API ботов.
- Входящие вебхуки, подписки на события, слеш-команды.
Вопросы по подключению пишите команде Syncra в Telegram: https://t.me/morzac.