Диалоги

#Список диалогов

Диалоги арендатора по возрастанию updated_at, постранично по курсору: чтобы забрать изменения, храните updated_at последнего увиденного и передавайте его в updated_after. Диалогов с мягким удалением нет, поэтому include_deleted сейчас ничего не добавляет. Ответ содержит персональные данные клиентов: каждая выдача записывается в журнал выдач, на RU нужны список разрешённых IP и страна получателя RU (иначе 403 pii_transfer_not_allowed). Диалоги личных ящиков и чаты кабинета ученика не отдаются. Поля с персональными данными (у диалога — external_customer_id, у сообщения — content и attachments) приходят, только если названы в fields=.

Области

conversations:read

Предел частоты

чтение

Идемпотентность

не требуется

Успешный ответ

200 Страница диалогов.

Параметры

Тело ответа

Примеры

curl -X GET 'https://formula-cream.pro/api/public/v1/conversations' \
  -H 'Authorization: Bearer '"$API_KEY"

{
  "data": [
    {
      "id": "EXAMPLE_ID",
      "channel": null,
      "contact_id": null,
      "external_customer_id": null,
      "status": "string",
      "mode": "ai",
      "language": null,
      "created_at": null,
      "updated_at": "2026-10-11T09:00:00Z"
    }
  ],
  "next_cursor": "EXAMPLE_CURSOR"
}

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed validation_failed encryption_key_required

#Найти или завести диалог

Диалог клиента вашего канала (канал api интеграции) по внешнему идентификатору: есть активный — он же (200), нет — новый (201) и событие conversation.created. Один и тот же external_customer_id двух разных интеграций — разные клиенты. Имя, почта и телефон пишутся только в пустые поля контакта. Канал подключается в кабинете (Настройки → API); без него — 409 channel_not_configured. Повтор с тем же Idempotency-Key — тот же диалог. Ответ содержит персональные данные клиентов: каждая выдача записывается в журнал выдач, на RU нужны список разрешённых IP и страна получателя RU (иначе 403 pii_transfer_not_allowed). Диалоги личных ящиков и чаты кабинета ученика не отдаются.

Области

conversations:write

Предел частоты

запись

Идемпотентность

обязателен Idempotency-Key

Успешный ответ

201 Диалог (новый — 201, найденный — 200).

Параметры

Тело запроса Клиент вашего канала.

Тело ответа

Примеры

curl -X POST 'https://formula-cream.pro/api/public/v1/conversations' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Idempotency-Key: '"$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "external_customer_id": "EXAMPLE_ID",
  "name": "string",
  "email": "user@example.com",
  "phone": "string",
  "language": "string"
}'

{
  "id": "EXAMPLE_ID",
  "channel": "string",
  "contact_id": "EXAMPLE_ID",
  "external_customer_id": "EXAMPLE_ID",
  "status": "string",
  "mode": "ai",
  "language": "string",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z"
}

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed validation_failed bad_request payload_too_large channel_not_configured idempotency_key_required idempotency_conflict operation_in_progress invalid_state

#Получить диалог

Один диалог. Чужой, несуществующий и недоступный публичному API диалог одинаково отвечает not_found. Ответ содержит персональные данные клиентов: каждая выдача записывается в журнал выдач, на RU нужны список разрешённых IP и страна получателя RU (иначе 403 pii_transfer_not_allowed). Диалоги личных ящиков и чаты кабинета ученика не отдаются. Поля с персональными данными (у диалога — external_customer_id, у сообщения — content и attachments) приходят, только если названы в fields=.

Области

conversations:read

Предел частоты

чтение

Идемпотентность

не требуется

Успешный ответ

200 Диалог.

Параметры

Тело ответа

Примеры

curl -X GET 'https://formula-cream.pro/api/public/v1/conversations/EXAMPLE_ID' \
  -H 'Authorization: Bearer '"$API_KEY"

{
  "id": "EXAMPLE_ID",
  "channel": "string",
  "contact_id": "EXAMPLE_ID",
  "external_customer_id": "EXAMPLE_ID",
  "status": "string",
  "mode": "ai",
  "language": "string",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z"
}

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed not_found validation_failed encryption_key_required

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

Сообщения диалога от старых к новым, постранично по курсору (created_at, id). Внутренние заметки операторов не отдаются. Вложения — временные подписанные ссылки; внешние адреса файлов мессенджеров не раскрываются. Ответ содержит персональные данные клиентов: каждая выдача записывается в журнал выдач, на RU нужны список разрешённых IP и страна получателя RU (иначе 403 pii_transfer_not_allowed). Диалоги личных ящиков и чаты кабинета ученика не отдаются. Поля с персональными данными (у диалога — external_customer_id, у сообщения — content и attachments) приходят, только если названы в fields=.

Области

conversations:read

Предел частоты

чтение

Идемпотентность

не требуется

Успешный ответ

200 Страница сообщений.

Параметры

Тело ответа

Примеры

curl -X GET 'https://formula-cream.pro/api/public/v1/conversations/EXAMPLE_ID/messages' \
  -H 'Authorization: Bearer '"$API_KEY"

{
  "data": [
    {
      "id": "EXAMPLE_ID",
      "conversation_id": "EXAMPLE_ID",
      "sender": "customer",
      "content_type": "string",
      "content": null,
      "attachments": [
        null
      ],
      "cards": [
        null
      ],
      "deleted": false,
      "created_at": "2026-10-11T09:00:00Z"
    }
  ],
  "next_cursor": "EXAMPLE_CURSOR"
}

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed not_found validation_failed encryption_key_required

#Сообщение клиента и ответ ИИ

Записывает сообщение клиента в диалог канала интеграции (conversations:write) и, при ai_reply=auto и области ai_seller:invoke, запускает ответ ИИ-продажника асинхронно: 202 с message_id, ai_reply.status=queued и операцией conversation.ai_reply. ?wait=N (0–20 с) ждёт ТО ЖЕ задание: успело — 200 с итогом (ai_reply, reply.id, operation.usage.cost в валюте кошелька), нет — 202. Без ai_seller:invoke или с ai_reply=none — 201, ai_reply.status=skipped, reason=not_requested, ИИ не вызывается и ничего не списывается. Текста ответа ИИ здесь нет — читайте GET /conversations/{id}/messages или ждите message.created. Повтор того же Idempotency-Key во время выполнения — тот же 202, после — итог; повторно сообщение не пишется и не оплачивается. Платная часть: не больше 5 одновременных операций на интеграцию (429 concurrency_limit), максимум стоимости одной операции и суточный предел интеграции (402 spend_limit_reached) — проверяются до записи, отказ ничего не записывает и освобождает Idempotency-Key. Диалог другого канала или арендатора — 404, закрытый — 409 invalid_state.

Области

conversations:write

Предел частоты

запись

Идемпотентность

обязателен Idempotency-Key

Успешный ответ

202 Принято; ответ ИИ готовится (202), готов в пределах wait (200) или не запрашивался (201).

Параметры

Тело запроса Сообщение клиента.

Тело ответа

Примеры

curl -X POST 'https://formula-cream.pro/api/public/v1/conversations/EXAMPLE_ID/messages' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Idempotency-Key: '"$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "string",
  "ai_reply": "auto"
}'

{
  "message_id": "EXAMPLE_ID",
  "conversation_id": "EXAMPLE_ID",
  "ai_reply": {
    "status": "replied",
    "reason": "operator_active"
  },
  "reply": {
    "id": "EXAMPLE_ID"
  },
  "operation": {
    "id": "EXAMPLE_ID",
    "type": "string",
    "status": "queued",
    "created_at": "2026-10-11T09:00:00Z",
    "completed_at": "2026-10-11T09:00:00Z",
    "resource": {
      "type": "string",
      "id": "EXAMPLE_ID"
    },
    "error": {
      "code": "string",
      "message": "string"
    },
    "usage": {
      "cost": null,
      "model": null
    }
  }
}

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed validation_failed bad_request payload_too_large not_found channel_not_configured invalid_state idempotency_key_required idempotency_conflict operation_in_progress concurrency_limit spend_limit_reached upstream_unavailable