Быстрый старт

Ключ, первый запрос, первый ответ посетителю и первое событие на ваш адрес — за пять шагов.

На этой странице

Адреса
1. Получить ключ
2. Первый запрос
3. Ответить посетителю
4. Подписаться на события
5. Что дальше

Адреса #

Что	Адрес
Публичное API	https://api.widgetchat.ru/api/v1
Файл виджета	https://api.widgetchat.ru/widget/bozex-support-widget.js
Кабинет	https://widgetchat.ru/cabinet
Приём событий Битрикс24	https://widgetchat.ru/b24/event
Приём событий amoCRM	https://widgetchat.ru/amocrm/hook/{scope_id}
Приём событий RetailCRM	https://widgetchat.ru/retailcrm/hook/{clientId}

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

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

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

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

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

GET /api/v1/conversations?status=open&limit=5 conversations:read

Пример вызова

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": "https://example.ru/pricing",
      "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. Ответить посетителю #

POST /api/v1/conversations/{id}/messages conversations:write

Пример вызова

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 секунд. Работу уводите в свою очередь: долгий ответ считается неудачей и приводит к повтору.