Быстрый старт: ключ, запросы, ошибки

Адреса #

Только HTTPS. Тестового контура нет: заведите отдельный проект в кабинете и работайте с ним. Он изолирован от боевого рабочим пространством.

1. Получить ключ #

Кабинет → карточка сайта → "API и вебхуки" → "Выдать ключ". Ключ показывается один раз: в базе лежит только его отпечаток.

Права выбираются при выдаче: conversations:read, conversations:write, media:read. Метод без права отвечает 403 insufficient_scope, остальные продолжают работать тем же ключом.

2. Первый запрос #

curl -s https://api.widgetchat.ru/api/v1/conversations?status=open&limit=5 \
  -H "Authorization: Bearer wck_ваш_ключ"

{
  "data": [
    {
      "id": "6c82f8e2-2ee2-4387-8c9b-34d164b18176",
      "status": "open",
      "channel": "app",
      "visitor": {"id": "u_8f1c…", "name": "Иван", "email": "ivan@example.ru"},
      "source": "widget",
      "createdAt": "2026-08-22T09:14:58.113Z",
      "lastMessageAt": "2026-08-22T09:15:04.281Z",
      "lastReadAt": null
    }
  ],
  "nextCursor": "2026-08-22T09:14:58.113Z",
  "hasMore": true
}

3. Ответить посетителю #

curl -s -X POST https://api.widgetchat.ru/api/v1/conversations/6c82f8e2-…/messages \
  -H "Authorization: Bearer wck_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-4417" \
  -d '{"content": "Заказ уже в пути, доставим завтра до 14:00"}'

201 {"data": {"id": "7735af47-…", "status": "queued", "direction": "outgoing",
                "createdAt": "2026-08-22T09:15:04.281Z"}}

Idempotency-Key делает повтор безопасным: тот же ключ вернёт 200 и duplicate: true вместо второго сообщения в переписке.

4. Подписаться на события #

Кабинет → "API и вебхуки" → "Добавить адрес". Секрет подписи показывается один раз. Кнопка "Проверить" шлёт событие webhook.test: на нём видно свою же подпись и код ответа обработчика.

Обработчик обязан ответить 2xx в течение 20 секунд. Работу уводите в свою очередь: долгий ответ считается неудачей и приводит к повтору.

Ключ: где хранить и как отзывать #

Каждый запрос несёт заголовок Authorization: Bearer wck_… Ключ выдаётся на один подключённый сайт и открывает переписку только этого сайта: разговор соседнего подключения по нему не найдётся даже по точному номеру.

В базе хранится только отпечаток ключа. Потерянный ключ не восстанавливается: он отзывается и выдаётся заново. Отозванный перестаёт открывать что-либо сразу, а запись остаётся с отметкой revokedAt.

Authorization: Bearer wck_cZLLSCqi7pQ2m4E1vN…

Ключ серверный. В код страницы его класть нельзя: оттуда его прочитает любой посетитель и получит доступ ко всей переписке сайта.

Права ключа #

Запросы из браузера и CORS #

Заголовков CORS публичное API не выдаёт намеренно, и обращение из браузера посетителя не пройдёт. Виджет работает по другому входу: по подписанному токену окна, который выдаёт шлюз.

Отказы аутентификации #

Конверт ответа #

Удачный ответ всегда кладёт содержимое в data, даже когда это один объект. У списков рядом появляются nextCursor и hasMore. Отказ приходит в том же конверте полем error с машинным кодом и пояснением на английском.

Все ответы идут с Cache-Control: no-store: в них чужая переписка.

{"data": { … }}
{"data": [ … ], "nextCursor": "2026-08-22T09:15:04.281Z", "hasMore": true}
{"error": {"code": "validation_error", "message": "content must not exceed 4096 characters"}}

Все коды отказов #

Постраничная выборка #

Выборка курсорная, а не по номерам страниц: пока читается первая страница, посетители пишут, и нумерация сдвинула бы часть разговоров мимо читающего. Курсором служит время последнего показанного элемента в формате RFC 3339 с наносекундами.

Берите nextCursor из ответа и передавайте его параметром cursor, пока hasMore истинно.

Пределы #

Что дальше #

Полные сигнатуры методов собраны на странице "Разговоры, сообщения и вложения". Формат событий и проверка подписи описаны в "Вебхуках". Если нужен не API, а готовый коннектор к CRM, смотрите страницы Битрикс24 и RetailCRM. Подключение amoCRM описано отдельно: оно заработает, когда техподдержка amoCRM выдаст сервису канал.