Интеграция по API

Если вам нужно встроить ассистента в собственный интерфейс, а не использовать готовую hosted-страницу, используйте эндпоинты /integration/v1/*. Никакой JWT-авторизации не требуется — вместо неё используется ключ ассистента.

Заголовки

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

Один запрос одновременно продолжает существующий чат (если передан X-Chat-Token) или лениво создаёт новый (если заголовок не передан).

curl -X POST https://<ваш-домен>/integration/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Assistant-Key: pk_ваш_ключ" \
  -d '{
    "text": "Здравствуйте! Расскажите про тарифы.",
    "context": { "url": "https://example.com/support" }
  }'

Ответ:

{
  "meta": { "request": "...", "unique": "...", "timestamp": "...", "milliseconds": 0 },
  "data": {
    "chatToken": "ct_...",
    "chat": { "kind": "Guest", "title": null, "messageCount": 2 },
    "userMessage": { "id": "...", "role": "User", "text": "...", "sequence": 0, "createdAt": "..." },
    "assistantMessage": { "id": "...", "role": "Assistant", "text": "...", "sequence": 1, "createdAt": "..." }
  },
  "errors": []
}

chatToken присутствует в ответе только когда чат был создан этим же запросом — сохраните его и передавайте в X-Chat-Token во всех следующих сообщениях этого разговора.

Продолжение и история

curl https://<ваш-домен>/integration/v1/chats/current/messages?page=1&pageSize=50 \
  -H "X-Assistant-Key: pk_ваш_ключ" \
  -H "X-Chat-Token: ct_..."

История отдаётся постранично, от самых старых сообщений к новым. Обратите внимание: элементы истории не содержат id — при сопоставлении с уже показанными на экране сообщениями ориентируйтесь на поле sequence, а не на id (он есть только в ответе на отправку сообщения).

Приватные чаты (sk_)

Если используете приватный ключ, при создании чата обязательно передайте личность покупателя:

{
  "text": "Здравствуйте!",
  "customer": { "externalId": "user-42", "email": "user@example.com" }
}

С публичным ключом поле customer передавать нельзя — сервер ответит ошибкой 422 (подробнее — «Публичные и приватные ключи»).

Пример на JavaScript (fetch)

const ASSISTANT_KEY = "pk_ваш_ключ";
let chatToken = localStorage.getItem("chatToken"); // null при первом сообщении

async function sendMessage(text) {
  const response = await fetch("https://<ваш-домен>/integration/v1/messages", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Assistant-Key": ASSISTANT_KEY,
      ...(chatToken ? { "X-Chat-Token": chatToken } : {}),
    },
    body: JSON.stringify({ text }),
  });

  const { data, errors } = await response.json();
  if (!response.ok) {
    throw new Error(errors[0]?.message ?? "Request failed");
  }

  if (data.chatToken) {
    chatToken = data.chatToken;
    localStorage.setItem("chatToken", chatToken);
  }

  return data.assistantMessage.text;
}

Сколько ждать ответа

Ответ ассистента — это синхронный вызов, который может занимать 5–25 секунд (модель может делать до 10 внутренних раундов с инструментами перед финальным ответом). Потоковой передачи (streaming) сейчас нет — ответ приходит целиком одним запросом. В интерфейсе обязательно покажите индикатор ожидания дольше обычного спиннера — например, циклический текст статуса («Думаю…», «Проверяю данные…») вместо голого спиннера на 20+ секунд.

Rate limiting

При 429 ответ не содержит заголовка Retry-After — не стройте точный обратный отсчёт, просто сообщите пользователю «попробуйте чуть позже» и, если нужно, повторите запрос через несколько секунд. Помните, что лимит requestsPerMinute общий на всех посетителей ассистента сразу (см. «Ассистенты и лимиты») — при высокой посещаемости 429 может происходить и без проблем на стороне конкретного пользователя.

Ошибки

Все ошибки возвращаются в едином формате:

{ "meta": { ... }, "data": null, "errors": [{ "code": "...", "message": "..." }] }

Основные коды состояния:

• 401 — ключ отсутствует, недействителен или отозван.
• 403 — тенант заблокирован, домен не входит в разрешённые для ключа, либо гостевые чаты отключены у ассистента.
• 404 — X-Chat-Token не найден, просрочен или принадлежит другому ассистенту.
• 422 — ошибка валидации запроса.
• 429 — превышен лимит запросов в минуту для ассистента.