Справочник Chat API

Аутентификация

Каждый запрос аутентифицируется с помощью ключа API вашего рабочего пространства, передаваемого в заголовке X-API-Key (или в параметре api_key). Ключи выглядят как ck_live_.... Относитесь к ключу как к паролю - любой, у кого он есть, может отправлять сообщения, которые тарифицируются на ваше рабочее пространство. Меняйте его в любое время в разделе Настройки -> Доступ к API; предыдущий ключ немедленно перестаёт работать.

Отправка сообщения

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Параметры:

• message (строка) - сообщение посетителя. Обязательно, если не прикреплены files.
• ticket_id (строка, необязательно) - продолжение существующего диалога. Опустите, чтобы начать новый.
• visitor_email / visitor_name (строка, необязательно) - прикрепить контактные данные к заявке.
• files (multipart, необязательно) - вложения посетителя. Требуется план с загрузкой файлов.

Ответ

Вызов возвращает 202 Accepted, как только сообщение сохранено; ответ ИИ генерируется асинхронно.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Передайте data.ticket_id обратно как ticket_id в следующем вызове, чтобы продолжить диалог. Чтобы получить ответ ИИ, подпишитесь по WebSocket (ActionCable) на канал, привязанный к data.id - тот же хеш посетителя, который использует встроенный виджет.

Чтение обращений

Получайте тикеты и их сообщения с тем же X-API-Key. Каждая конечная точка чтения ограничена вашим рабочим пространством и доступна на плане Business.

• GET /api/v1/chat/tickets - список тикетов, сначала новые. Параметры запроса: status, limit (максимум 100), offset. Возвращает tickets и pagination.
• GET /api/v1/chat/tickets/:id - один тикет.
• GET /api/v1/chat/tickets/:id/messages - сообщения тикета по порядку, каждое с role, content и attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Ограничения частоты и квота

Запросы ограничены примерно 20 в минуту на ключ (и на IP). Каждый сгенерированный ответ также расходует месячный лимит сообщений вашего плана; как только он исчерпан, конечная точка возвращает 200 с data.limit_reached: true вместо генерации ответа.

Ошибки

• 401 - ключ API не предоставлен.
• 404 - ключ не соответствует ни одному рабочему пространству (например, после смены).
• 403 plan_upgrade_required - рабочее пространство не на плане Business.
• 403 - подписка неактивна или запрос пришёл с домена, не разрешённого настройками виджета.
• 422 - сообщение отсутствует (и файлы не прикреплены).