Что есть и чего нет
Что в 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_.... |
Где читать подробности:
- Подключить свой ИИ и что умеет подключённое приложение
- Боты и API ботов
- Входящие вебхуки
- Подписки на события
- Слеш-команды
Служебные адреса
Два адреса открыты без ключа. Через них можно проверить, что сервер отвечает.
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-*ни на одном адресе.