Документация API

🚀 ChatBoxAI REST API

Полное управление виджетами, диалогами, сообщениями, формами, шаблонами и API-ключами — по ключу X-API-Key, без авторизации в панели.

Ключ создаётся в панели → вкладка API и передаётся в заголовке X-API-Key.

Базовый URL: https://code.chatboxai.ru/api/v1

Авторизация: добавьте заголовок X-API-Key: cbk_... к каждому запросу. Формат ключа: cbk_ + 48 hex-символов. widget_id — числовой ID виджета (см. список виджетов), widget_code — 12-символьный код.

Проверка здоровья API

Публичный эндпоинт — не требует API-ключа. Возвращает статус, версию и состояние очереди.

GET/api/v1/health

Статус API: ok / версия / очередь

curl https://code.chatboxai.ru/api/v1/health

Виджеты

Список виджетов

GET/api/v1/integration/widgets

Список всех виджетов со счётчиками диалогов и сообщений

curl https://code.chatboxai.ru/api/v1/integration/widgets \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Создание виджета (все параметры)

POST/api/v1/integration/widgets

Создать виджет. Можно указать все параметры настройки виджета.

Параметр	Тип	Описание
`name`	string	Название виджета (обязательно)
`domain`	string	Домен сайта (обязательно)
`is_active`	boolean	Активен (по умолчанию true)
`max_tokens`	int	Максимум токенов ответа AI (по умолчанию 500)

curl -X POST https://code.chatboxai.ru/api/v1/integration/widgets \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name":"Интернет-магазин","domain":"shop.ru","is_active":true,"max_tokens":500}'

В ответе вернётся widget_code и готовый код вставки виджета.

Информация о виджете

GET/api/v1/integration/widgets/{code}

Информация о виджете по его коду

curl https://code.chatboxai.ru/api/v1/integration/widgets/Fvjw7Gcbb6kG \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Изменение настроек виджета

PATCH/api/v1/integration/widgets/{code}

Изменить название, домен, активность или max_tokens (передавайте только нужные поля)

curl -X PATCH https://code.chatboxai.ru/api/v1/integration/widgets/Fvjw7Gcbb6kG \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name":"Новое название","is_active":false}'

Удаление виджета

DELETE/api/v1/integration/widgets/{code}

Удалить виджет полностью: вместе с диалогами, сообщениями, формами, шаблонами и внешними API

Действие необратимо — удаляются все данные виджета.

curl -X DELETE https://code.chatboxai.ru/api/v1/integration/widgets/Fvjw7Gcbb6kG \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Диалоги и сообщения

Диалоги виджета за период

GET/api/v1/integration/widgets/{code}/sessions

Диалоги виджета (from, to, limit)

Параметр	Тип	Описание
`from`	date	Начало периода (YYYY-MM-DD)
`to`	date	Конец периода (YYYY-MM-DD)
`limit`	int	Лимит (1–100, по умолчанию 50)

curl "https://code.chatboxai.ru/api/v1/integration/widgets/Fvjw7Gcbb6kG/sessions?from=2026-08-01&to=2026-08-25&limit=20" \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Сообщения диалога

GET/api/v1/integration/sessions/{session_id}/messages

Сообщения конкретного диалога (limit, по умолчанию 100, максимум 200)

curl "https://code.chatboxai.ru/api/v1/integration/sessions/sess_1787655012770_oogat018m/messages?limit=100" \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Удаление сообщений диалога

DELETE/api/v1/integration/sessions/{session_id}/messages

Удалить все сообщения диалога и сам диалог

curl -X DELETE https://code.chatboxai.ru/api/v1/integration/sessions/sess_1787655012770_oogat018m/messages \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Удаление всех сообщений виджета

DELETE/api/v1/integration/widgets/{code}/messages

Удалить все диалоги и сообщения виджета (сам виджет остаётся)

Все диалоги и сообщения виджета будут удалены безвозвратно.

curl -X DELETE https://code.chatboxai.ru/api/v1/integration/widgets/Fvjw7Gcbb6kG/messages \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Формы

Список форм

GET/api/v1/integration/forms

Список всех форм с полями

curl https://code.chatboxai.ru/api/v1/integration/forms \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Создание формы (все параметры + поля)

POST/api/v1/integration/forms

Создать форму со всеми настройками и полями

Параметр	Тип	Описание
`widget_id`	int	ID виджета (обязательно)
`form_name`	string	Название формы (обязательно)
`search_keywords`	string	Ключевые слова через запятую
`email_to`	string	Email для отправки заявок
`email_subject`	string	Тема письма с заявкой
`success_message`	string	Сообщение после отправки
`privacy_link`	string	URL политики обработки данных
`is_active`	boolean	Активна (по умолчанию true)
`fields[]`	array	Поля: field_label, field_type (text/email/textarea/select/radio/checkbox/info/submit), is_required, field_placeholder, field_options[]

curl -X POST https://code.chatboxai.ru/api/v1/integration/forms \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_id": 1,
    "form_name": "Заявка на консультацию",
    "search_keywords": "заявка, консультация, обратный звонок",
    "email_to": "manager@shop.ru",
    "email_subject": "Новая заявка с сайта",
    "success_message": "Спасибо! Мы свяжемся с вами.",
    "is_active": true,
    "fields": [
      {"field_label":"Имя","field_type":"text","is_required":true,"field_placeholder":"Ваше имя"},
      {"field_label":"Телефон","field_type":"text","is_required":true,"field_placeholder":"+7..."},
      {"field_label":"Комментарий","field_type":"textarea","is_required":false},
      {"field_label":"Отправить","field_type":"submit"}
    ]
  }'

Изменение формы

PATCH/api/v1/integration/forms/{id}

Изменить настройки формы и/или полностью заменить её поля (передайте fields[] — поля будут заменены)

curl -X PATCH https://code.chatboxai.ru/api/v1/integration/forms/5 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"form_name":"Новая заявка","email_to":"new@shop.ru","is_active":false}'

Удаление формы

DELETE/api/v1/integration/forms/{id}

Удалить форму вместе с её полями

curl -X DELETE https://code.chatboxai.ru/api/v1/integration/forms/5 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Шаблоны сообщений

Список шаблонов

GET/api/v1/integration/templates

Список всех шаблонов с кнопками

curl https://code.chatboxai.ru/api/v1/integration/templates \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Создание шаблона (все параметры + кнопки)

POST/api/v1/integration/templates

Создать шаблон со всеми настройками и кнопками

Параметр	Тип	Описание
`widget_id`	int	ID виджета (обязательно)
`template_name`	string	Название шаблона (обязательно)
`search_keywords`	string	Ключевые слова через запятую
`message_text`	string	Текст ответа шаблона
`form_id`	int	ID формы, которая откроется вместе с шаблоном
`is_active`	boolean	Активен (по умолчанию true)
`priority`	int	Приоритет (больше = раньше)
`buttons[]`	array	Кнопки: button_text, button_url, form_id

curl -X POST https://code.chatboxai.ru/api/v1/integration/templates \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_id": 1,
    "template_name": "Приветствие",
    "search_keywords": "привет, здравствуйте",
    "message_text": "Здравствуйте! Чем можем помочь?",
    "is_active": true,
    "priority": 10,
    "buttons": [
      {"button_text":"Каталог","button_url":"https://shop.ru/catalog"},
      {"button_text":"Оставить заявку","form_id":3}
    ]
  }'

Информация о шаблоне

GET/api/v1/integration/templates/{id}

Шаблон с его кнопками

curl https://code.chatboxai.ru/api/v1/integration/templates/7 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Изменение шаблона

PATCH/api/v1/integration/templates/{id}

Изменить настройки шаблона и/или полностью заменить кнопки (передайте buttons[] — кнопки будут заменены)

curl -X PATCH https://code.chatboxai.ru/api/v1/integration/templates/7 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"message_text":"Новый текст ответа","priority":5}'

Удаление шаблона

DELETE/api/v1/integration/templates/{id}

Удалить шаблон вместе с его кнопками

curl -X DELETE https://code.chatboxai.ru/api/v1/integration/templates/7 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

API-ключи

Список ключей

GET/api/v1/api-keys

Список ваших API-ключей со статистикой использований

curl https://code.chatboxai.ru/api/v1/api-keys \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Создание ключа (все параметры)

POST/api/v1/api-keys

Создать новый ключ (показывается один раз)

Параметр	Тип	Описание
`name`	string	Название ключа (обязательно)
`description`	string	Описание
`scopes[]`	array	Права: read, write, admin, webhook
`ip_restrictions`	string	Разрешённые IP (через запятую)
`expires_at`	date	Дата истечения (YYYY-MM-DD)

curl -X POST https://code.chatboxai.ru/api/v1/api-keys \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name":"CRM-интеграция","description":"Синхронизация с CRM","scopes":["read","write"],"expires_at":"2027-01-01"}'

Изменение ключа

PATCH/api/v1/api-keys/{id}

Изменить name, description, scopes, ip_restrictions, expires_at

curl -X PATCH https://code.chatboxai.ru/api/v1/api-keys/3 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name":"Новое имя","scopes":["read"]}'

Ротация ключа

POST/api/v1/api-keys/{id}/rotate

Ротация ключа — старый перестаёт работать, новый показывается один раз

curl -X POST https://code.chatboxai.ru/api/v1/api-keys/3/rotate \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Отзыв ключа

POST/api/v1/api-keys/{id}/revoke

Отозвать ключ (можно вернуть в панели)

curl -X POST https://code.chatboxai.ru/api/v1/api-keys/3/revoke \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"

Удаление ключа

DELETE/api/v1/api-keys/{id}

Удалить ключ полностью

curl -X DELETE https://code.chatboxai.ru/api/v1/api-keys/3 \
  -H "X-API-Key: cbk_ВАШ_КЛЮЧ"