#Серверный API диалогов

Статус: Доступно (чтение) / Планируется (запись). Три маршрута чтения — GET /conversations, GET /conversations/{id} и GET /conversations/{id}/messages — работают. Маршруты записи (POST …) описаны в проекте и ещё не работают: вызовы вернут 404. Для записи имена полей тел запросов и ответов, кроме ai_reply и конверта operation, помечены как предварительные и подлежат сверке с OpenAPI при выпуске.

Назначение: управлять диалогами с вашего сервера: заводить диалог из своего мессенджера, передавать реплики клиента ИИ-продажнику, получать его ответ, отвечать от имени оператора, перехватывать диалог и возвращать его ИИ, закрывать.

#Содержание

1. Когда использовать
2. Доступ
3. Общие правила
4. Объекты
5. GET /conversations
6. GET /conversations/{id}
7. GET /conversations/{id}/messages
8. POST /conversations
9. POST /conversations/{id}/messages
10. Причины отсутствия ответа ИИ
11. POST /conversations/{id}/operator-messages
12. Перехват, возврат ИИ и закрытие
13. События
14. Примеры на четырёх языках
15. Заметки
16. Открытые вопросы

#Когда использовать

• Ваши клиенты общаются в вашем мессенджере, приложении или стороннем виджете, а отвечать должен ИИ-продажник Sapport. Пошаговое руководство — ИИ-продажник в своём канале.
• Нужно показывать диалоги Sapport в вашей системе и отвечать оператором оттуда.
• Для чата на сайте без вашего сервера используйте виджет; для своего интерфейса в браузере — клиентский Chat API.

#Доступ

Области ключа:

Права запроса — пересечение областей ключа, роли интеграции, прав владельца и лицензии (как вычисляются). Для приёма сообщения клиента с ответом ИИ нужны обе области: conversations:write и ai_seller:invoke. Приём без ответа ИИ требует только conversations:write.

В ячейке RU для областей с ПДн (conversations:*) при подключении интеграции обязательны список разрешённых IP, страна размещения принимающей системы и основание передачи. ПДн передаются только получателям в РФ: если страна иная, область conversations:* не выдаётся (403 pii_transfer_not_allowed, Ячейки и данные).

#Общие правила

Подробно — Соглашения.

#Объекты

Поля объектов диалога и сообщения — фактические, как их отдаёт чтение (схемы Conversation и Message в OpenAPI). Идентификаторы — uuid. Набор значений status, channel и content_type может расширяться: не считайте списки закрытыми.

#Диалог

#Сообщение

Сообщения содержат персональные данные клиентов. Не записывайте их в журналы и не передавайте третьим лицам без основания.

Персональные данные и журнал выдач. Каждая выдача записывается в журнал выдач (см. ячейки и данные). На ячейке RU нужны узкий список разрешённых IP-адресов у ключа и страна получателя RU, иначе 403 pii_transfer_not_allowed приходит до чтения. Если строку журнала записать не удалось — 503, данные не отдаются. Диалоги личных ящиков и чаты кабинета ученика не отдаются; чужой, несуществующий или не-uuid идентификатор даёт 404 not_found.

Ответы чтения несут Cache-Control: private, no-store.

#GET /conversations

Статус: Доступно. Область conversations:read.

Список диалогов с фильтрами и курсором. Порядок возрастающий по (updated_at, id): чтобы синхронизироваться, запоминайте next_cursor и возвращайтесь с ним.

curl -sS "$SAPPORT_BASE_URL/conversations?channel=api&mode=operator&limit=50" \
  -H "Authorization: Bearer $SAPPORT_API_KEY"

{
  "data": [
    {
      "id": "7c1f0e52-3a4b-4d6e-9f10-2b8a5c3d9e01",
      "channel": "api",
      "contact_id": "0d94a7c8-5e2f-4b13-8a6c-91f4e7b02d35",
      "external_customer_id": "client-4815",
      "status": "open",
      "mode": "operator",
      "language": "ru",
      "created_at": "2026-10-11T08:00:00Z",
      "updated_at": "2026-10-11T08:15:30Z"
    }
  ],
  "next_cursor": null
}

Меняя фильтры, начинайте обход заново без cursor: курсор привязан к фильтрам. Недействительный, просроченный или чужой курсор — 422 validation_failed.

#GET /conversations/{id}

Статус: Доступно. Область conversations:read.

Один диалог. Если диалога нет или он принадлежит другому арендатору — 404 not_found.

curl -sS "$SAPPORT_BASE_URL/conversations/7c1f0e52-3a4b-4d6e-9f10-2b8a5c3d9e01" \
  -H "Authorization: Bearer $SAPPORT_API_KEY"

#GET /conversations/{id}/messages

Статус: Доступно. Область conversations:read.

Сообщения диалога постранично: limit (по умолчанию 25, максимум 100), cursor, include_deleted. Порядок возрастающий по (created_at, id) — от старых к новым.

С include_deleted=true удалённое сообщение приходит как «надгробие»: deleted: true, content: null, без вложений.

{
  "data": [
    { "id": "1a2b3c4d-0001-4000-8000-000000000001", "conversation_id": "7c1f0e52-3a4b-4d6e-9f10-2b8a5c3d9e01", "sender": "customer", "content_type": "text", "content": "Сколько стоит курс?", "attachments": [], "deleted": false, "created_at": "2026-10-11T08:15:30Z" },
    { "id": "1a2b3c4d-0002-4000-8000-000000000002", "conversation_id": "7c1f0e52-3a4b-4d6e-9f10-2b8a5c3d9e01", "sender": "ai", "content_type": "text", "content": "Курс стоит 9 900 ₽.", "attachments": [], "deleted": false, "created_at": "2026-10-11T08:15:33Z" }
  ],
  "next_cursor": null
}

#POST /conversations

Статус: Планируется. Область conversations:write. Idempotency-Key — рекомендуется.

Завести диалог из вашего канала (канал api). Один клиент вашей системы — один внешний идентификатор; повторный вызов с тем же внешним идентификатором должен возвращать тот же диалог (платформа ищет или создаёт диалог по внешнему идентификатору).

Имена полей предварительные.

curl -sS -X POST "$SAPPORT_BASE_URL/conversations" \
  -H "Authorization: Bearer $SAPPORT_API_KEY" \
  -H "Idempotency-Key: 6f3c1f3e-5b52-4a52-9e0b-0d8e3a2c9f11" \
  -H "Content-Type: application/json" \
  -d '{"external_customer_id":"client-4815","name":"Анна"}'

Ответ — объект диалога (201; повтор с тем же ключом — тот же диалог).

#POST /conversations/{id}/messages

Статус: Планируется. Области: conversations:write (приём) и ai_seller:invoke (ответ ИИ). Idempotency-Key обязателен. Платная операция при вызове ИИ.

Передать сообщение клиента. Если диалог ведёт ИИ, платформа запускает ИИ-продажника.

#Запрос

curl -sS -X POST "$SAPPORT_BASE_URL/conversations/cnv_EXAMPLE01/messages?wait=15" \
  -H "Authorization: Bearer $SAPPORT_API_KEY" \
  -H "Idempotency-Key: 8d4b2a40-1c63-4d4e-8f0a-6c2d3e1b7a90" \
  -H "Content-Type: application/json" \
  -d '{"content":"Сколько стоит курс?"}'

#Ответы

Ответ ИИ выполняется только асинхронно: запрос не держит соединение дольше wait. Формы ответа предварительные, кроме ai_reply и operation.

Принято, ответ ИИ готовится (202). ai_reply.status — queued, в operation — конверт асинхронной операции вида conversation.ai_reply:

{
  "message": {
    "id": "msg_EXAMPLE01",
    "conversation_id": "cnv_EXAMPLE01",
    "sender": "customer",
    "content": "Сколько стоит курс?",
    "created_at": "2026-10-11T08:15:30Z"
  },
  "ai_reply": { "status": "queued" },
  "operation": {
    "id": "op_EXAMPLE01",
    "type": "conversation.ai_reply",
    "status": "queued",
    "created_at": "2026-10-11T08:15:30Z",
    "resource": { "type": "message", "id": "msg_EXAMPLE01" }
  }
}

Ответ готов в пределах wait (200). ai_reply.status — replied, операция завершена, в ней стоимость:

{
  "message": {
    "id": "msg_EXAMPLE01",
    "conversation_id": "cnv_EXAMPLE01",
    "sender": "customer",
    "content": "Сколько стоит курс?",
    "created_at": "2026-10-11T08:15:30Z"
  },
  "ai_reply": { "status": "replied" },
  "reply": {
    "id": "msg_EXAMPLE02",
    "content": "Курс «Основы гидролатов» стоит 9 900 ₽. Хотите, расскажу, что входит?"
  },
  "operation": {
    "id": "op_EXAMPLE01",
    "type": "conversation.ai_reply",
    "status": "succeeded",
    "created_at": "2026-10-11T08:15:30Z",
    "completed_at": "2026-10-11T08:15:33Z",
    "resource": { "type": "message", "id": "msg_EXAMPLE01" },
    "usage": { "cost": { "amount": "0.42", "currency": "RUB" }, "model": "model-EXAMPLE" }
  }
}

Не дождались — вернётся 202 с текущим состоянием операции. Дальше выберите способ получения ответа (Асинхронные операции):

1. опросите GET /operations/{id} — по resource прочитайте сообщения диалога;
2. прочитайте GET /conversations/{id}/messages;
3. подпишитесь на событие message.created и operation.completed (вебхуки) — предпочтительный способ.

Повтор того же запроса с тем же Idempotency-Key возвращает ту же операцию, новая не запускается.

ИИ не отвечал по причине — это успешный ответ 200, а не ошибка. Операция не создаётся, деньги не списываются:

{
  "message": {
    "id": "msg_EXAMPLE01",
    "conversation_id": "cnv_EXAMPLE01",
    "sender": "customer",
    "content": "Сколько стоит курс?",
    "created_at": "2026-10-11T08:15:30Z"
  },
  "ai_reply": { "status": "skipped", "reason": "operator_active" }
}

Объект ai_reply приходит и в событии message.created для сообщения клиента. См. следующий раздел.

#Ошибки

Общий разбор классов — Соглашения.

#Причины отсутствия ответа ИИ

Платформа принимает сообщение клиента всегда, когда запрос корректен. ИИ может не ответить — и это не сбой. Состояние ответа ИИ возвращается полем ai_reply в теле успешного ответа на сообщение клиента и в событии message.created.

ai_reply — объект {status, reason?}:

Для канала api суточный предел работает так же, как у виджета: значение берётся из настройки канала ai_daily_limit (по умолчанию 200 в сутки, максимум 10 000); в событии conversation.handoff_requested диалог попадает к оператору (События).

#POST /conversations/{id}/operator-messages

Статус: Планируется. Область conversations:write. Idempotency-Key — рекомендуется.

Ответ оператора, введённый в вашей системе. Сообщение пишется в диалог от имени оператора и уходит клиенту событием message.created через ваш вебхук.

curl -sS -X POST "$SAPPORT_BASE_URL/conversations/cnv_EXAMPLE01/operator-messages" \
  -H "Authorization: Bearer $SAPPORT_API_KEY" \
  -H "Idempotency-Key: 0a1f6f7b-8e0d-47c5-9f53-5a1b27c9d3e4" \
  -H "Content-Type: application/json" \
  -d '{"content":"Здравствуйте! Меня зовут Анна."}'

#Перехват, возврат ИИ и закрытие

Статус: Планируется. Область conversations:write.

Тела запросов в проекте не описаны. Повтор вызова должен быть безопасным; Idempotency-Key передавайте в любом случае. Действие, недопустимое в текущем состоянии диалога (например, takeover закрытого диалога), возвращает 409 invalid_state.

curl -sS -X POST "$SAPPORT_BASE_URL/conversations/cnv_EXAMPLE01/takeover" \
  -H "Authorization: Bearer $SAPPORT_API_KEY" \
  -H "Idempotency-Key: c2d6f3a9-4b0e-4a8b-8b7f-2d9a6e1f0c55"

#События

Получайте результат вебхуками вместо опроса (Вебхуки). Конверт события — {id, type, api_version, created_at, livemode, data}.

Событие передачи оператору одно — conversation.handoff_requested; имя handoff.requested относится к вебхукам версии 1 и в v2 не используется.

Событие message.created «тонкое» всегда: текст сообщения в него не входит, даже при include_pii: true. Содержимое получайте запросом GET /conversations/{id}/messages. Флаг include_pii подписки добавляет ПДн в conversation.created, conversation.handoff_requested и conversation.summary_ready; для него у интеграции нужны conversations:read и leads:read (Вебхуки).

Событие message.created приходит и на сообщения оператора, и на ответы ИИ. Чтобы не отправить клиенту собственное сообщение дважды, сравнивайте message_id с тем, что вы уже обработали.

#Примеры на четырёх языках

Во всех примерах ключ и адрес берутся из переменных окружения; идентификатор диалога — условный.

#curl

curl -sS -X POST "$SAPPORT_BASE_URL/conversations/cnv_EXAMPLE01/messages?wait=15" \
  -H "Authorization: Bearer $SAPPORT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"content":"Сколько стоит курс?"}'

#JavaScript (Node.js 18+)

import { randomUUID } from 'node:crypto';

const BASE = process.env.SAPPORT_BASE_URL;   // https://formula-cream.pro/api/public/v1
const KEY = process.env.SAPPORT_API_KEY;

export async function sendCustomerMessage(conversationId, text, idempotencyKey = randomUUID()) {
  const res = await fetch(`${BASE}/conversations/${conversationId}/messages?wait=15`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ content: text })
  });

  const body = await res.json();
  if (!res.ok) {
    // application/problem+json: ветвимся по code
    const err = new Error(`${body.code}: ${body.detail}`);
    err.code = body.code;
    err.requestId = body.request_id;
    throw err;
  }
  // 202 — ответ ещё готовится (body.operation): ждите вебхук message.created
  // или опрашивайте GET /operations/{id}
  return { status: res.status, body, idempotencyKey };
}

#Python (httpx)

import os
import uuid

import httpx

BASE = os.environ["SAPPORT_BASE_URL"]  # https://formula-cream.pro/api/public/v1
KEY = os.environ["SAPPORT_API_KEY"]


def send_customer_message(conversation_id: str, text: str, idempotency_key: str | None = None):
    key = idempotency_key or str(uuid.uuid4())
    res = httpx.post(
        f"{BASE}/conversations/{conversation_id}/messages",
        params={"wait": 15},
        headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": key},
        json={"content": text},
        timeout=30,
    )
    body = res.json()
    if res.status_code >= 400:
        # application/problem+json
        raise RuntimeError(f'{body.get("code")}: {body.get("detail")} (request {body.get("request_id")})')
    return res.status_code, body, key

#PHP

<?php
function sapport_send_customer_message(string $conversationId, string $text, ?string $idempotencyKey = null): array
{
    $base = getenv('SAPPORT_BASE_URL'); // https://formula-cream.pro/api/public/v1
    $key  = getenv('SAPPORT_API_KEY');
    $idempotencyKey ??= bin2hex(random_bytes(16));

    $ch = curl_init("$base/conversations/$conversationId/messages?wait=15");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer $key",
            "Idempotency-Key: $idempotencyKey",
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode(['content' => $text], JSON_UNESCAPED_UNICODE),
    ]);

    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $body = json_decode($raw, true);
    if ($status >= 400) {
        throw new RuntimeException(($body['code'] ?? 'error') . ': ' . ($body['detail'] ?? ''));
    }
    return [$status, $body, $idempotencyKey];
}

#Заметки

• Не повторяйте с новым ключом. После сетевого сбоя повторяйте запрос с тем же Idempotency-Key, иначе клиент получит два ответа, а кошелёк спишет два раза.
• Один ключ — одна реплика. Не используйте один Idempotency-Key для разных реплик.
• Клиентские сообщения из вашего канала не должны быть длиннее предела. Предел для серверного API проектом не определён; ориентируйтесь на 4000 знаков виджета.
• Канал api изолирован. Для него никогда не используется общий промпт площадки; ИИ отвечает по настройкам вашего агента и базе знаний арендатора.
• ПДн. Содержимое диалогов — персональные данные. В ячейке RU подключение интеграции с областями conversations:* требует списка IP, страны размещения принимающей системы (только РФ; иначе pii_transfer_not_allowed) и основания передачи; передача выдач фиксируется в журнале выдач, который арендатор видит в кабинете и по GET /disclosures (Ячейки и данные).
• Журнал изменений: 90-changelog.

#Открытые вопросы

• Полные схемы тел запросов и ответов (имена полей, перечень значений status, mode, sender) — только в OpenAPI при выпуске; здесь поля предварительные. Техническое.
• Предельная длина реплики клиента и формат вложений в серверном API. Техническое.
• Правила слияния диалогов при повторном POST /conversations с тем же внешним идентификатором клиента: что возвращается, если диалог закрыт. Техническое.
• Тела и коды 409 invalid_state для takeover, release, close в закрытом диалоге. Техническое.