РазделЧто есть и чего нет

Что есть и чего нет

Что в Syncra доступно разработчику сегодня, какие лимиты и сроки действуют и чего нет: личных API-токенов, SDK, файла OpenAPI и другого.

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

Что работает сегодня

Способов пять. Первый работает по протоколу MCP. MCP (Model Context Protocol) — это открытый протокол, по которому ИИ-приложение узнаёт, какие действия доступны в другом сервисе, и выполняет их.

Способ Что даёт Чем подтверждается доступ
Подключить свой ИИ Claude, ChatGPT или Cursor читает и пишет в Syncra от имени человека и с его правами. Адрес сервера — https://ai-syncra.ru/api/mcp. Вход через OAuth — стандартный протокол, по которому приложение получает доступ без пароля. Человек сам нажимает «Разрешить».
API ботов Бот пишет и читает сообщения, открывает личные сообщения, работает с задачами. Адреса начинаются с /api/bot/v1. Ключ бота skb_... в заголовке Authorization.
Входящие вебхуки Один POST-запрос публикует текст в канале. Секрет whk_... прямо в адресе.
Подписки на события Syncra отправляет запрос на ваш адрес, когда что-то произошло. Syncra подписывает запрос секретом whsec_....
Слеш-команды Команда из поля сообщения отправляет запрос на ваш адрес. Syncra подписывает запрос секретом whsec_....

Где читать подробности:

Служебные адреса

Два адреса открыты без ключа. Через них можно проверить, что сервер отвечает.

GET /api/health

Отвечает, что сервер работает. Параметров нет.

curl "https://ai-syncra.ru/api/health"

Ответ 200 OK:

{
  "ok": true
}

GET /api/version

Возвращает сборку, которая сейчас работает. Параметров нет.

curl "https://ai-syncra.ru/api/version"

Ответ 200 OK:

{
  "sha": "...",
  "builtAt": "..."
}

sha — номер версии кода, builtAt — время сборки.

Лимиты на число запросов

Лимит считается отдельно для каждого адреса. Общего лимита на весь API нет. Окно начинается с первого запроса и длится указанное время.

Адрес Лимит На что считается
POST /api/webhooks/:token 60 запросов за 60 секунд На один вебхук
POST /api/oauth/register 20 запросов в час На IP-адрес
GET /api/oauth/authorize 60 запросов в минуту На IP-адрес
POST /api/oauth/token 120 запросов в минуту На IP-адрес
POST /api/oauth/revoke 60 запросов в минуту На IP-адрес
/api/bot/v1/* Лимита нет
POST /api/mcp Своего лимита нет

Когда лимит превышен, сервер отвечает 429 с телом {"error":"Too many requests"}. Заголовков Retry-After и X-RateLimit-* в ответе нет. Подождите до конца окна и повторите запрос.

Длины и сроки

Что Значение
Текст сообщения в API ботов и во входящем вебхуке От 1 до 4000 символов
Ответ вашего сервиса на слеш-команду Обрезается до 4000 символов
Вложений в одном сообщении бота До 10
Сообщений в одном запросе истории, GET /api/bot/v1/messages От 1 до 100, по умолчанию 30
Имя слеш-команды От 1 до 32 символов: a-z, 0-9, -, _
Описание слеш-команды До 200 символов
Адрес подписки на события или слеш-команды До 2048 символов
Время на ответ вашего сервиса на событие или команду 5 секунд
Попыток доставить событие До 5
Попыток отправить слеш-команду 1
Срок жизни токена доступа ИИ-приложения 1 час
Срок жизни токена обновления ИИ-приложения 90 дней
Срок жизни ссылки на страницу, где человек разрешает доступ 15 минут
Срок жизни кода авторизации OAuth 10 минут

Ключ бота показывается целиком один раз, при создании. Секреты подписок и команд можно посмотреть в настройках позже.

Формат ошибок

Тело ошибки — JSON с полем error. У части ошибок есть поле code с постоянным значением: по нему ваш код решает, как обработать ошибку. Текст в error по умолчанию английский. Если запрос несёт заголовок Accept-Language: ru, известные тексты приходят по-русски, поэтому в своём коде опирайтесь на статус и code, а не на текст.

Статус Тело Когда
401 {"error":"Unauthorized"} Ключа бота нет, он отозван или бот выключен.
422 {"error":"Validation error","details":{...}} Тело запроса не прошло проверку. В details.fieldErrors перечислены поля и причины.
429 {"error":"Too many requests"} Превышен лимит на число запросов.
500 {"error":"Internal server error","errId":"..."} Непредвиденная ошибка сервера.

Значение errId из ответа 500 помогает найти ошибку. Пришлите его в поддержку в Telegram: https://t.me/morzac. Ошибки каждого адреса перечислены на его странице.

Чего нет

Ключи и доступ

  • Нет личных API-токенов и API-ключей пользователя. Ключ есть только у бота.
  • Нет доступа по ключу к внутреннему API приложения. Адреса под /api, которыми пользуется само приложение Syncra, принимают только сессию браузера. У них нет версии, и они меняются вместе с приложением. Единственный API с версией в адресе — /api/bot/v1.
  • Нет адреса, который создаёт ботов, ключи, вебхуки, подписки и команды по ключу бота. Это делается в настройках рабочего пространства.
  • Нет каталога ботов и установки одного бота в несколько рабочих пространств. Бот принадлежит одному рабочему пространству.

Подключение своего ИИ

  • Уровень доступа один, mcp. Нет доступа «только чтение» и нет доступа к одному рабочему пространству. Приложение получает всё, что может сам человек, во всех его рабочих пространствах.
  • Из сценариев OAuth работает только код авторизации с PKCE и обновление токена. Сценариев client credentials, implicit и device нет.
  • Нет кабинета разработчика для регистрации приложений. Приложение регистрирует себя запросом POST /api/oauth/register.
  • Токен, полученный через OAuth, открывает только /api/mcp. Другие адреса его не принимают.
  • Сервер отдаёт только инструменты. Ресурсов и подсказок MCP нет. Потока событий от сервера, сессий и уведомлений по инициативе сервера тоже нет.

API ботов

  • Нет лимита на число запросов и заголовков лимита.
  • Нет постраничной выдачи с общим числом записей total.
  • Бот не создаёт задачи, не работает со страницами базы знаний, не ставит реакции, не закрепляет сообщения, не участвует в созвонах, не читает файлы, не получает список участников и не ищет по рабочему пространству. Большую часть этого умеет подключённое ИИ-приложение от имени человека: что умеет подключённое приложение.

Вебхуки, события и команды

  • Входящий вебхук публикует только текст. Вложений, ответов в ветке и своего имени автора нет.
  • Нет событий о реакциях, составе каналов, созвонах, встречах и CRM.
  • Нет ручной повторной отправки события и гарантии порядка событий.
  • Нет интерактивных сообщений: кнопок, форм, модальных окон.
  • Нет отложенных ответов на слеш-команду и ответов, которые видит только вызвавший.
  • Нет API реального времени (WebSocket) для сторонних сервисов. О событиях бот узнаёт только через подписки.

Инструменты разработчика

  • Нет опубликованного SDK и пакета в npm.
  • Нет файла OpenAPI или Swagger.
  • Нет заголовков Retry-After и X-RateLimit-* ни на одном адресе.