Схемы данных
Объекты запросов и ответов. Типы в таблицах методов ведут сюда.
#Money
Денежная сумма.
| Поле | Тип | Описание |
|---|---|---|
amount | string обязательное | Сумма СТРОКОЙ (не число с плавающей точкой), например "123.45". |
currency | string обязательное | Код валюты ISO 4217: RUB (RU), GBP (EN), IDR (ID). |
#FieldError
Ошибка проверки одного поля.
| Поле | Тип | Описание |
|---|---|---|
field | string обязательное | Путь к полю запроса в формате JSON Pointer (RFC 6901): "/limit", "/events/0". |
code | string обязательное | Машинный код причины: out_of_range, required, invalid_format… |
message | string обязательное | Пояснение для человека. |
#Problem
Ошибка в формате application/problem+json (RFC 9457).
| Поле | Тип | Описание |
|---|---|---|
type | string обязательное | Ссылка на описание кода: https://<домен ячейки>/developers/errors#<code>. |
title | string обязательное | Краткое название, одинаковое для кода. |
status | integer обязательное | HTTP-статус. |
code | string обязательное | Стабильный машинный код. Ветвите логику по нему, а не по тексту. Значения: invalid_api_key wrong_cell integration_inactive tenant_inactive scope_missing ip_not_allowed feature_not_in_plan pii_transfer_not_allowed not_found method_not_allowed bad_request idempotency_key_required idempotency_conflict operation_in_progress invalid_state channel_not_configured encryption_key_required precondition_failed precondition_required payload_too_large validation_failed rate_limited concurrency_limit spend_limit_reached insufficient_funds wallet_suspended internal_error service_unavailable upstream_unavailable |
detail | string обязательное | Пояснение к конкретному случаю. Не разбирайте этот текст. |
request_id | string обязательное | Идентификатор запроса (совпадает с заголовком X-Request-Id). Указывайте при обращении в поддержку. |
errors | array<FieldError> необязательное | Ошибки по полям (только validation_failed). |
correct_base_url | string необязательное | Только wrong_cell: базовый адрес ячейки, где выпущен ключ. |
topup_url | string необязательное | Только wallet_suspended: адрес кабинета, где пополняется кошелёк. |
balance | Money необязательное, может быть null | Только wallet_suspended: остаток кошелька на момент отказа. |
#Usage
Стоимость платной операции.
| Поле | Тип | Описание |
|---|---|---|
cost | Money обязательное | |
model | string обязательное | Модель, выполнившая операцию. |
#Operation
Асинхронная операция (единый конверт для всех модулей).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор операции. |
type | string обязательное | Вид операции, например "article.generation". |
status | string обязательное | Состояние операции. Значения: queued running succeeded failed canceled |
created_at | string обязательное | Время создания, ISO 8601 UTC. |
completed_at | string необязательное | Время завершения; только для succeeded, failed, canceled. |
resource | object необязательное | Ресурс, к которому относится операция; по нему читают результат. |
resource.type | string обязательное | |
resource.id | string обязательное | |
error | object необязательное | Только для failed: код из каталога ошибок или код причины операции. |
error.code | string обязательное | |
error.message | string обязательное | |
usage | Usage необязательное | Только для платных операций. |
#OperationEnvelope
Ответ 202 на создающий запрос.
| Поле | Тип | Описание |
|---|---|---|
operation | Operation обязательное |
#Me
Кто вы: арендатор, интеграция, ключ, пределы, кошелёк.
| Поле | Тип | Описание |
|---|---|---|
tenant | object обязательное | Арендатор — владелец ключа. |
tenant.id | string обязательное | |
tenant.name | string обязательное | |
cell | string обязательное | Ячейка платформы: ru, en или id. Значения: ru en id |
base_url | string обязательное | Базовый адрес API этой ячейки. |
integration | object обязательное | Интеграция (служебная учётная запись), которой принадлежит ключ. |
integration.id | string обязательное | |
integration.name | string обязательное | |
channel_id | string обязательное, может быть null | Канал "api" интеграции; null — канал ещё не создан. |
key | object обязательное | |
key.key_id | string обязательное | Публичный идентификатор ключа (не секрет). |
key.mode | string обязательное | Значения: live test |
key.scopes | array<string> обязательное | Действующие области: область интеграции ∩ текущие права владельца ∩ лицензия. Значения: conversations:read conversations:write ai_seller:invoke leads:read leads:write leads:score analytics:read analytics:write dashboards:read articles:read articles:write articles:generate strategist:read strategist:write strategist:chat webhooks:manage channels:read channels:write cards:read cards:write |
key.expires_at | string обязательное | Срок действия ключа, ISO 8601 UTC. |
key.ip_allowlist | array<string> обязательное, может быть null | Разрешённые адреса и сети (CIDR); null — любой адрес. |
limits | object обязательное | Пределы частоты запросов и платных операций. |
limits.read_per_min | integer обязательное | |
limits.write_per_min | integer обязательное | |
limits.paid_per_min | integer обязательное | |
limits.paid_concurrency | integer обязательное | Одновременных платных операций ИИ на интеграцию; сверх — 429 concurrency_limit. |
limits.max_operation_cost | Money обязательное, может быть null | Максимум стоимости одной платной операции в валюте кошелька (оценка выше — 402 spend_limit_reached); null — не удалось прочитать. |
wallet | object обязательное | Кошелёк арендатора (ИИ-операции). |
wallet.balance | Money обязательное, может быть null | Остаток кошелька в рублях; null — состояние неизвестно или арендатор не тарифицируется. |
wallet.state | string обязательное | ok — достаточно; low — мало средств; negative — остаток ниже нуля; blocked — кошелёк заблокирован; unknown — состояние получить не удалось. Подробности — GET /wallet. Значения: ok low negative blocked unknown |
wallet.exchange | string обязательное | suspended при negative и blocked: все маршруты, кроме /me и /wallet, отвечают 402 wallet_suspended. Значения: active suspended |
wallet.topup_url | string обязательное | Адрес кабинета, где пополняется кошелёк. |
wallet.daily_spend | object обязательное, может быть null | Суточные траты интеграции; null — посчитать не удалось. |
wallet.daily_spend.limit | Money обязательное, может быть null | Суточный предел трат интеграции; null — не задан. |
wallet.daily_spend.used | Money обязательное | Списано за платные операции интеграции с начала местных суток ячейки. |
crm_mode | string обязательное | Режим CRM арендатора: "internal" (наша CRM) или внешняя система. |
#Webhook
Подписка на события. Секрета у подписки нет: каждую доставку подписывает ключ платформы (JWS EdDSA, заголовок Webhook-Signature), открытые ключи — GET /.well-known/jwks.json.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор подписки. |
url | string обязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> обязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean обязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string обязательное, может быть null | Пометка для вас, до 200 знаков. |
status | string обязательное | active — доставки идут; paused — приостановлена. Значения: active paused |
created_at | string обязательное | ISO 8601 UTC. |
updated_at | string обязательное | ISO 8601 UTC. |
#WebhookJwk
Открытый ключ подписи вебхуков.
| Поле | Тип | Описание |
|---|---|---|
kty | string обязательное | |
crv | string обязательное | |
x | string обязательное | Открытый ключ, base64url. |
kid | string обязательное | Идентификатор ключа (отпечаток RFC 7638); совпадает с kid в заголовке подписи. |
alg | string обязательное | |
use | string обязательное |
#WebhookJwks
Набор открытых ключей подписи вебхуков ячейки (RFC 7517).
| Поле | Тип | Описание |
|---|---|---|
keys | array<WebhookJwk> обязательное | Действующий ключ и ключи, ещё живущие после ротации. |
#WebhookCreate
Тело создания подписки.
| Поле | Тип | Описание |
|---|---|---|
url | string обязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> обязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean необязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string необязательное, может быть null | Пометка для вас, до 200 знаков. |
#WebhookUpdate
Тело правки: передайте хотя бы одно поле.
| Поле | Тип | Описание |
|---|---|---|
url | string необязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> необязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean необязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string необязательное, может быть null | Пометка для вас, до 200 знаков. |
status | string необязательное | Приостановить или возобновить доставки. Значения: active paused |
#WebhookPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Webhook> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#WebhookTestResult
Ответ 202 на тестовую доставку. Тело события приходит на ваш адрес с livemode: false.
| Поле | Тип | Описание |
|---|---|---|
event_id | string обязательное, может быть null | Идентификатор тестового события. |
type | string обязательное | |
status | string обязательное | Событие в очереди; уйдёт на ближайшем запуске доставщика (до минуты). |
#WebhookDelivery
Запись журнала доставок (хранится 30 суток).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор доставки. |
event_id | string обязательное | Идентификатор события. |
state | string обязательное | pending — ждёт попытки; delivered — доставлено; failed — попытка не удалась, будет повтор; dead — повторы исчерпаны. Значения: pending delivered failed dead |
attempt | integer обязательное | Номер последней попытки (0 — ещё не было). |
status_code | integer обязательное, может быть null | HTTP-код ответа подписчика; null, если ответа не было. |
duration_ms | integer обязательное, может быть null | Длительность попытки, мс. |
error | string обязательное, может быть null | Причина сбоя: тайм-аут, ошибка соединения или сертификата, ответ 3xx. |
next_attempt_at | string обязательное, может быть null | Время следующей попытки; null, если попыток больше не будет. |
delivered_at | string обязательное, может быть null | Время успешной доставки. |
created_at | string обязательное |
#WebhookDeliveryPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<WebhookDelivery> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#ChannelWidgetPoweredBy
Подпись внизу виджета.
| Поле | Тип | Описание |
|---|---|---|
mode | string обязательное | default — название продукта ячейки; custom — ваш текст и ссылка; hidden — без подписи. Значения: default custom hidden |
text | string необязательное, может быть null | Текст подписи для custom, до 40 знаков. |
url | string необязательное, может быть null | Ссылка подписи для custom: только https://. |
#ChannelWidgetFiles
Файлы посетителя.
| Поле | Тип | Описание |
|---|---|---|
visitor_upload | boolean обязательное | Посетитель может присылать файлы. По умолчанию true. |
max_mb | integer обязательное | Предел одного файла, МБ (1–10). |
#ChannelWidget
Настройки чат-виджета канала. null — значение по умолчанию.
| Поле | Тип | Описание |
|---|---|---|
channel_id | string обязательное | Идентификатор канала web_chat. |
name | string обязательное | Имя канала. |
is_active | boolean обязательное | Канал включён. |
assistant_name | string обязательное, может быть null | Имя ассистента в шапке; по умолчанию — имя канала. До 60 знаков. |
assistant_subtitle | string обязательное, может быть null | Подзаголовок ассистента. До 80 знаков. |
assistant_avatar_url | string обязательное, может быть null | Иконка ассистента (шапка и лента). Только https:// или путь вашего сайта на этой ячейке, начинающийся с «/». До 500 знаков. |
queue_title | string обязательное, может быть null | Заголовок шапки, пока диалог ждёт оператора. До 60 знаков. |
queue_subtitle | string обязательное, может быть null | Подзаголовок ожидания оператора. До 80 знаков. |
queue_icon_url | string обязательное, может быть null | Иконка ожидания оператора. Только https:// или путь вашего сайта на этой ячейке, начинающийся с «/». До 500 знаков. |
powered_by | ChannelWidgetPoweredBy обязательное | |
files | ChannelWidgetFiles обязательное | |
color | string обязательное, может быть null | Цвет виджета: #rrggbb. |
greeting | string обязательное, может быть null | Приветствие. До 500 знаков. |
position | string обязательное, может быть null | Угол кнопки. Значения: bottom-right bottom-left |
theme | string обязательное, может быть null | Тема. Значения: light dark |
bubble_text | string обязательное, может быть null | Подсказка у кнопки. До 60 знаков. |
delay | integer обязательное, может быть null | Задержка показа, секунды. |
consent_text | string обязательное, может быть null | Текст согласия перед первым сообщением. До 600 знаков. |
consent_url | string обязательное, может быть null | Ссылка на документ согласия: только https://. |
#ChannelWidgetUpdate
Правка: передайте хотя бы одно поле. Не переданное остаётся как было, null возвращает значение по умолчанию; неизвестные поля отбрасываются.
| Поле | Тип | Описание |
|---|---|---|
assistant_name | string необязательное, может быть null | Имя ассистента в шапке; по умолчанию — имя канала. До 60 знаков. |
assistant_subtitle | string необязательное, может быть null | Подзаголовок ассистента. До 80 знаков. |
assistant_avatar_url | string необязательное, может быть null | Иконка ассистента (шапка и лента). Только https:// или путь вашего сайта на этой ячейке, начинающийся с «/». До 500 знаков. |
queue_title | string необязательное, может быть null | Заголовок шапки, пока диалог ждёт оператора. До 60 знаков. |
queue_subtitle | string необязательное, может быть null | Подзаголовок ожидания оператора. До 80 знаков. |
queue_icon_url | string необязательное, может быть null | Иконка ожидания оператора. Только https:// или путь вашего сайта на этой ячейке, начинающийся с «/». До 500 знаков. |
powered_by | ChannelWidgetPoweredBy необязательное, может быть null | |
files | object необязательное, может быть null | |
files.visitor_upload | boolean необязательное | Посетитель может присылать файлы. По умолчанию true. |
files.max_mb | integer необязательное | Предел одного файла, МБ (1–10). |
color | string необязательное, может быть null | Цвет виджета: #rrggbb. |
greeting | string необязательное, может быть null | Приветствие. До 500 знаков. |
position | string необязательное, может быть null | Угол кнопки. Значения: bottom-right bottom-left |
theme | string необязательное, может быть null | Тема. Значения: light dark |
bubble_text | string необязательное, может быть null | Подсказка у кнопки. До 60 знаков. |
delay | integer необязательное, может быть null | Задержка показа, секунды. |
consent_text | string необязательное, может быть null | Текст согласия перед первым сообщением. До 600 знаков. |
consent_url | string необязательное, может быть null | Ссылка на документ согласия: только https://. |
#CardButton
Кнопка карточки.
| Поле | Тип | Описание |
|---|---|---|
label | string обязательное | Подпись, до 30 знаков. |
url | string обязательное | Адрес кнопки. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта). |
#Card
Карточка товара для чата: картинка, название, цена и до трёх кнопок. Хранится на товаре аккаунта.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор товара. |
code | string обязательное | Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код]. |
name | string обязательное | Название. До 120 знаков. |
description | string обязательное, может быть null | Описание. До 500 знаков. |
image_url | string обязательное, может быть null | Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта. |
price_text | string обязательное, может быть null | Цена текстом; не задана — из цены и валюты товара; null — цены нет. |
badge | string обязательное, может быть null | Плашка («Хит»). До 30 знаков. |
page_url | string обязательное, может быть null | Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта). |
buttons | array<CardButton> обязательное | До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url. |
ai_enabled | boolean обязательное | Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код. |
sort | integer обязательное | Порядок в каталоге продажника и выборе оператора (по возрастанию). |
active | boolean обязательное | Товар активен; неактивную карточку нельзя отправить. |
created_at | string обязательное | ISO 8601 UTC. |
updated_at | string обязательное | ISO 8601 UTC. |
#CardCreate
Тело создания карточки. Неизвестные поля — 422.
| Поле | Тип | Описание |
|---|---|---|
code | string обязательное | Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код]. |
name | string обязательное | Название. До 120 знаков. |
description | string необязательное, может быть null | Описание. До 500 знаков. |
image_url | string необязательное, может быть null | Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта. |
page_url | string необязательное, может быть null | Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта). |
badge | string необязательное, может быть null | Плашка («Хит»). До 30 знаков. |
price_text | string необязательное, может быть null | Цена текстом. До 40 знаков. |
buttons | array<CardButton> необязательное | До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url. |
ai_enabled | boolean необязательное | Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код. |
sort | integer необязательное | Порядок в каталоге продажника и выборе оператора (по возрастанию). |
active | boolean необязательное | Товар активен; неактивную карточку нельзя отправить. |
#CardUpdate
Тело правки: передайте хотя бы одно поле.
| Поле | Тип | Описание |
|---|---|---|
code | string необязательное | Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код]. |
name | string необязательное | Название. До 120 знаков. |
description | string необязательное, может быть null | Описание. До 500 знаков. |
image_url | string необязательное, может быть null | Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта. |
page_url | string необязательное, может быть null | Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта). |
badge | string необязательное, может быть null | Плашка («Хит»). До 30 знаков. |
price_text | string необязательное, может быть null | Цена текстом. До 40 знаков. |
buttons | array<CardButton> необязательное | До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url. |
ai_enabled | boolean необязательное | Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код. |
sort | integer необязательное | Порядок в каталоге продажника и выборе оператора (по возрастанию). |
active | boolean необязательное | Товар активен; неактивную карточку нельзя отправить. |
#CardPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Card> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#MessageCard
Копия карточки в сообщении на момент отправки (адреса развёрнуты).
| Поле | Тип | Описание |
|---|---|---|
code | string обязательное | Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код]. |
name | string обязательное | Название. До 120 знаков. |
description | string обязательное, может быть null | |
image_url | string обязательное, может быть null | Полный https-адрес картинки. |
price_text | string обязательное, может быть null | |
badge | string обязательное, может быть null | |
page_url | string обязательное, может быть null | Полный https-адрес страницы; null — путь без домена аккаунта. |
buttons | array<CardButton> обязательное |
#CardSend
Тело отправки карточек в диалог.
| Поле | Тип | Описание |
|---|---|---|
codes | array<string> обязательное | Коды карточек, 1–3. |
comment | string необязательное, может быть null | Текст над карточками, до 1000 знаков. |
#CardSendResult
Ответ 201 на отправку карточек.
| Поле | Тип | Описание |
|---|---|---|
message_id | string обязательное | Идентификатор сообщения с карточками. |
conversation_id | string обязательное | |
created_at | string обязательное | ISO 8601 UTC. |
cards | array<MessageCard> обязательное | |
delivery | string обязательное | Как карточки доходят до клиента: metadata — виджет сайта и канал интеграции (событие message.created); native — Telegram, VK, Max своим форматом; text — строками «название — цена — ссылка». Значения: metadata native text |
status | string обязательное | Состояние доставки в канал. Значения: sent delivered failed |
#Wallet
Состояние кошелька арендатора и обмена данными.
| Поле | Тип | Описание |
|---|---|---|
balance | Money обязательное, может быть null | Остаток кошелька в рублях (кошелёк ведётся в RUB на любой ячейке); null — состояние неизвестно или арендатор не тарифицируется. |
state | string обязательное | ok — достаточно; low — мало средств (обмен идёт); negative — остаток ниже нуля; blocked — кошелёк заблокирован; unknown — состояние получить не удалось. Значения: ok low negative blocked unknown |
exchange | string обязательное | suspended при negative и blocked: все маршруты, кроме /me и /wallet, отвечают 402 wallet_suspended, вебхуки откладываются. При unknown остаётся active: бесплатное чтение идёт с заголовком Wallet-State: unknown, платные операции закрыты (503). Значения: active suspended |
topup_url | string обязательное | Адрес кабинета, где пополняется кошелёк (нужен вход сотрудника с правом пополнения). |
daily_spend | object обязательное, может быть null | Суточные траты интеграции: списания за её платные операции с начала местных суток ячейки; null — посчитать не удалось. |
daily_spend.limit | Money обязательное, может быть null | Суточный предел трат интеграции; null — не задан. |
daily_spend.used | Money обязательное | Списано с начала местных суток ячейки. |
#TimeseriesItem
Один временной ряд.
| Поле | Тип | Описание |
|---|---|---|
metric | string обязательное | Значения: sessions pageviews visitors bounce_rate impressions clicks ctr position ai_referrals bot_hits leads deals_won revenue |
from | string обязательное | Дата YYYY-MM-DD. |
to | string обязательное | Дата YYYY-MM-DD. |
granularity | string обязательное | Значения: day week |
agg | string обязательное | Способ свёртки ряда за период. Значения: sum avg |
engine | string обязательное, может быть null | Поисковик ряда; null у метрик, не привязанных к поиску. Значения: google yandex bing |
availability | string обязательное | Значения: ok no_data no_source |
reason | string обязательное, может быть null | Код причины, если availability не ok. |
series | array<object> обязательное | Ряд значений; дни без данных заполнены нулями. При недельном шаге date — первый день недели. |
comparison | object обязательное | |
comparison.current | object обязательное, может быть null | |
comparison.prev | object обязательное, может быть null | |
comparison.delta_pct | number обязательное, может быть null | Изменение в процентах; null, если сравнить не с чем или база равна нулю. |
comparison.data_through | string обязательное, может быть null | Последняя дата, по которую данные полны. |
summary | object обязательное, может быть null | |
summary.total | object обязательное, может быть null | |
summary.latest | object обязательное, может быть null | |
summary.non_zero_days | integer обязательное | |
cluster_applied | boolean обязательное | |
data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#TimeseriesResponse
Один ряд (одна метрика) либо items в порядке запроса (несколько метрик).
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное |
#TrafficSourceRow
Источник первого визита за период.
| Поле | Тип | Описание |
|---|---|---|
source | string обязательное | Значения: google yandex bing chatgpt perplexity ai_other social ads direct other |
kind | string обязательное | Значения: search ai_assistant social ads direct other |
sessions | integer обязательное | |
visitors | integer обязательное, может быть null | Уникальные посетители за день, просуммированные по периоду; null, когда посчитать нечем (маячок anonymous). |
leads | integer обязательное | |
series | array<object> необязательное | Только при include=series. |
#TrafficSourcesResponse
Источники трафика, больше сессий первыми.
| Поле | Тип | Описание |
|---|---|---|
data | array<TrafficSourceRow> обязательное | |
data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#FunnelStep
Ступень воронки со своей доступностью и своей датой.
| Поле | Тип | Описание |
|---|---|---|
key | string обязательное | Значения: impressions clicks sessions leads deals_created deals_won revenue |
availability | string обязательное | Значения: ok no_data no_source |
sources | array<string> обязательное | |
unit | string обязательное | Значения: count money |
current | object обязательное, может быть null | |
prev | object обязательное, может быть null | |
delta_pct | number обязательное, может быть null | |
data_through | string обязательное, может быть null |
#FunnelResponse
Воронка «показы → клики → сессии → лиды → сделки → выручка».
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.engine | string обязательное | Значения: yandex google both |
data.from | string обязательное | Дата YYYY-MM-DD. |
data.to | string обязательное | Дата YYYY-MM-DD. |
data.steps | array<FunnelStep> обязательное | |
data.by_channel | array<object> обязательное | |
data.search_by_engine | array<object> необязательное | Только engine=both: движки раздельно. |
data.by_product | array<object> обязательное | |
data.crm | object обязательное | |
data.crm.availability | string обязательное | Значения: ok no_data |
data.crm.reason | string необязательное | |
data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#VisibilityResponse
Видимость: пять самостоятельных разделов.
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.from | string обязательное | Дата YYYY-MM-DD. |
data.to | string обязательное | Дата YYYY-MM-DD. |
data.engine | string обязательное | Значения: yandex google both |
data.share | object обязательное | |
data.share.availability | string обязательное | |
data.share.reason | string необязательное | |
data.share.source | string обязательное | |
data.share.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.share.data | object обязательное | |
data.distribution | object обязательное | |
data.distribution.availability | string обязательное | |
data.distribution.reason | string необязательное | |
data.distribution.source | string обязательное | |
data.distribution.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.distribution.data | object обязательное | |
data.sov | object обязательное | |
data.sov.availability | string обязательное | |
data.sov.reason | string необязательное | |
data.sov.source | string обязательное | |
data.sov.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.sov.data | object обязательное | |
data.aeo | object обязательное | |
data.aeo.availability | string обязательное | |
data.aeo.reason | string необязательное | |
data.aeo.source | string обязательное | |
data.aeo.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.aeo.data | object обязательное | |
data.regions | object обязательное | |
data.regions.availability | string обязательное | |
data.regions.reason | string необязательное | |
data.regions.source | string обязательное | |
data.regions.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.regions.data | object обязательное |
#OverviewResponse
Срез экрана «Обзор»: запрошенные блоки в порядке экрана.
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.from | string обязательное | Дата YYYY-MM-DD. |
data.to | string обязательное | Дата YYYY-MM-DD. |
data.blocks | object обязательное | |
data.blocks.strategist | object необязательное | |
data.blocks.strategist.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.strategist.reason | string необязательное | |
data.blocks.strategist.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.kpi | object необязательное | |
data.blocks.kpi.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.kpi.reason | string необязательное | |
data.blocks.kpi.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.funnel | object необязательное | |
data.blocks.funnel.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.funnel.reason | string необязательное | |
data.blocks.funnel.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.attention | object необязательное | |
data.blocks.attention.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.attention.reason | string необязательное | |
data.blocks.attention.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.ads | object необязательное | |
data.blocks.ads.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.ads.reason | string необязательное | |
data.blocks.ads.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.ai_assistants | object необязательное | |
data.blocks.ai_assistants.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.ai_assistants.reason | string необязательное | |
data.blocks.ai_assistants.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.popular_pages | object необязательное | |
data.blocks.popular_pages.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.popular_pages.reason | string необязательное | |
data.blocks.popular_pages.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.clusters | object необязательное | |
data.blocks.clusters.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.clusters.reason | string необязательное | |
data.blocks.clusters.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.data_trust | object необязательное | |
data.blocks.data_trust.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.data_trust.reason | string необязательное | |
data.blocks.data_trust.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.sitemap_health | object необязательное | |
data.blocks.sitemap_health.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.sitemap_health.reason | string необязательное | |
data.blocks.sitemap_health.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.status | object необязательное | |
data.blocks.status.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.status.reason | string необязательное | |
data.blocks.status.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#PulseAlert
Находка «Пульса»: тема спроса, которая начала расти.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
topic_id | string обязательное | |
topic_name | string обязательное, может быть null | |
keyword | string обязательное | |
horizon | string обязательное | |
status | string обязательное | |
episode_start | string обязательное, может быть null | |
last_seen | string обязательное, может быть null | |
score | number обязательное, может быть null | |
volume | number обязательное, может быть null | |
growth | number обязательное, может быть null | |
sources | array<object> обязательное | |
strategist_topic | object обязательное, может быть null | Связанная тема очереди стратега. |
strategist_topic.id | string обязательное | |
strategist_topic.status | string обязательное |
#PulseResponse
Срез экрана «Пульс».
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.period | object обязательное | |
data.period.from | string обязательное | Дата YYYY-MM-DD. |
data.period.to | string обязательное | Дата YYYY-MM-DD. |
data.new_7d | integer обязательное | |
data.truncated | boolean обязательное | |
data.alerts | array<PulseAlert> обязательное | |
data.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#ArticleSummary
Статья арендатора без содержимого (элемент списка).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор статьи. |
title | string обязательное | |
slug | string обязательное, может быть null | |
status | string обязательное | draft — черновик; review — на проверке; approved — одобрена; published — опубликована; rejected — отклонена; transferred — передана в блог; external — внешняя. |
locale | string обязательное, может быть null | Язык статьи (ru, en, id). |
keyword | string обязательное, может быть null | Главный запрос статьи. |
meta_title | string обязательное, может быть null | |
meta_description | string обязательное, может быть null | |
cover_image_url | string обязательное, может быть null | |
word_count | integer обязательное | |
created_at | string обязательное, может быть null | ISO 8601 UTC. |
updated_at | string обязательное, может быть null | ISO 8601 UTC. |
published_at | string обязательное, может быть null | ISO 8601 UTC. |
#ArticlePublication
Состояние последней выкладки статьи через модуль сайта.
| Поле | Тип | Описание |
|---|---|---|
target | string обязательное | Куда выкладывается: модуль на вашем сайте. |
state | string обязательное | queued — в очереди или отдано модулю; applied — применено на сайте; skipped — пропущено; conflict — правка на сайте новее; failed — ошибка. Значения: queued applied skipped conflict failed |
published_url | string обязательное, может быть null | Адрес статьи на вашем сайте после применения. |
error | string обязательное, может быть null | Причина сбоя, до 200 знаков. |
#Article
Статья арендатора с содержимым.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор статьи. |
title | string обязательное | |
slug | string обязательное, может быть null | |
status | string обязательное | draft — черновик; review — на проверке; approved — одобрена; published — опубликована; rejected — отклонена; transferred — передана в блог; external — внешняя. |
locale | string обязательное, может быть null | Язык статьи (ru, en, id). |
keyword | string обязательное, может быть null | Главный запрос статьи. |
meta_title | string обязательное, может быть null | |
meta_description | string обязательное, может быть null | |
cover_image_url | string обязательное, может быть null | |
word_count | integer обязательное | |
created_at | string обязательное, может быть null | ISO 8601 UTC. |
updated_at | string обязательное, может быть null | ISO 8601 UTC. |
published_at | string обязательное, может быть null | ISO 8601 UTC. |
content | object обязательное | Тело статьи в запрошенном формате: html и markdown — строка; blocks — массив блоков {type, html}. HTML очищен от скриптов, опасных ссылок и обработчиков событий. У статьи, чьё тело переехало в блог площадки, содержимое пустое. |
publication | ArticlePublication обязательное, может быть null | null — статью ещё не выкладывали через модуль сайта. |
#ArticlePage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<ArticleSummary> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#StrategistReportSummary
Шапка отчёта стратега (элемент списка).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор отчёта. |
report_date | string обязательное | Дата отчёта YYYY-MM-DD. |
report_type | string обязательное | daily — ежедневный, weekly — недельный. Значения: daily weekly |
summary_text | string обязательное | Краткий вывод. |
actions_count | integer обязательное | Сколько действий рекомендовано. |
data_as_of | object обязательное | Актуальность данных: по каждому показателю (ключ) дата последних данных YYYY-MM-DD; ключ snapshot — дата снимка аналитики, на котором построен отчёт. Пусто, если снимка нет. |
delivered_at | string обязательное, может быть null | Когда отчёт доставлен владельцу; null — ещё нет. ISO 8601 UTC. |
#StrategistReportAction
Рекомендованное действие.
| Поле | Тип | Описание |
|---|---|---|
title | string обязательное | |
priority | string обязательное | Приоритет действия (high, medium, low). |
rationale | string обязательное | Обоснование. Названия конкурентов в нём скрыты. |
target_ref | string обязательное, может быть null | Ссылка на цель (статья, товар, кампания); null, если цели нет или это конкурент. |
expected_effect | object обязательное, может быть null | Ожидаемый эффект; null, если стратег его не назвал. |
expected_effect.metric | string обязательное, может быть null | |
expected_effect.delta | string обязательное, может быть null | |
expected_effect.horizon_days | integer обязательное, может быть null | |
check_after_days | integer обязательное, может быть null | Через сколько дней проверить результат. |
basis | string обязательное | На чём стоит вывод: observed_pattern — наблюдали у других; own_measured — измерили у вас; research — исследование; hypothesis — гипотеза. Значения: observed_pattern own_measured research hypothesis |
#StrategistEvidence
Доказательства по действиям. Дословные формулировки конкурентов не отдаются.
| Поле | Тип | Описание |
|---|---|---|
actions | array<object> обязательное | |
validation | object необязательное | Итог проверки доказательств. relevance_checked всегда false: проверяются ссылки и цитаты, а не смысл. |
validation.refs_valid | boolean обязательное | |
validation.excerpts_valid | boolean обязательное | |
validation.relevance_checked | boolean обязательное | |
validation.limitations | array<string> обязательное |
#StrategistReport
Отчёт стратега целиком. Снимок аналитики, модель и стоимость не отдаются.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
report_date | string обязательное | |
report_type | string обязательное | Значения: daily weekly |
summary_text | string обязательное | |
data_as_of | object обязательное | Актуальность данных: по каждому показателю (ключ) дата последних данных YYYY-MM-DD; ключ snapshot — дата снимка аналитики, на котором построен отчёт. Пусто, если снимка нет. |
highlights | array<object> обязательное | Что идёт хорошо. |
concerns | array<object> обязательное | Что беспокоит. |
actions | array<StrategistReportAction> обязательное | |
evidence | StrategistEvidence обязательное |
#StrategistReportPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<StrategistReportSummary> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#StrategistTopic
Тема в очереди стратега.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
title | string обязательное, может быть null | |
rationale | string обязательное, может быть null | Почему тема предложена. Для тем от конкурентов домены скрыты. |
trend_score | number обязательное, может быть null | Оценка тренда; null — не оценивалась. |
source | string обязательное | Откуда тема: planner, competitors, chat и др. |
status | string обязательное | proposed — ждёт решения; approved — одобрена; generating — статья создаётся; generated — статья создана; rejected — отклонена; duplicate — дубль; expired — срок вышел. Значения: proposed approved generating generated rejected duplicate expired |
cluster_id | string обязательное, может быть null | |
generated_article_id | string обязательное, может быть null | Идентификатор созданной статьи (GET /articles/{id}). |
proposed_at | string обязательное, может быть null | ISO 8601 UTC. |
decided_at | string обязательное, может быть null | ISO 8601 UTC. |
expires_at | string обязательное, может быть null | ISO 8601 UTC. |
#StrategistTopicPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<StrategistTopic> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#StrategistAction
Действие стратега, предложенное в вашей сессии и ждущее решения.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
session_id | string обязательное, может быть null | Сессия разговора, в которой предложено действие. |
type | string обязательное | Вид действия. В v1 — только propose_topic. |
title | string обязательное | Заголовок предлагаемой темы. |
status | string обязательное | proposed — ждёт подтверждения; confirmed — подтверждено, выполняется; executed — выполнено; failed — не удалось; cancelled — отменено; expired — срок вышел (7 суток). Значения: proposed confirmed executed failed cancelled expired |
result | object обязательное, может быть null | Результат выполненного действия: созданная тема. |
result.topic_id | string обязательное | |
error | object обязательное, может быть null | Причина сбоя при status = failed. |
error.code | string обязательное | |
error.message | string обязательное | |
created_at | string обязательное, может быть null | ISO 8601 UTC. |
decided_at | string обязательное, может быть null | ISO 8601 UTC. |
expires_at | string обязательное, может быть null | Когда ожидание истекает: создание + 7 суток. ISO 8601 UTC. |
#StrategistActionPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<StrategistAction> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#Conversation
Диалог. Содержит персональные данные (external_customer_id).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор диалога (uuid). |
channel | string обязательное, может быть null | Тип канала: api, telegram, website … |
contact_id | string обязательное, может быть null | Идентификатор контакта (клиента) на платформе. |
external_customer_id | string необязательное, может быть null | Идентификатор клиента в вашей системе. Только у канала api; у остальных каналов null (внешний идентификатор мессенджера не раскрывается). Персональные данные: в чтении приходит, только если названо в fields=. |
status | string обязательное | Состояние диалога: open, handoff_pending, resolved, closed … Набор значений может расширяться — не считайте список закрытым. |
mode | string обязательное | Кто ведёт диалог: ai — отвечает ИИ (режимы auto и supervised), operator — отвечает человек (copilot и manual). Значения: ai operator |
language | string обязательное, может быть null | Язык диалога (ISO 639-1); null — не определён. |
created_at | string обязательное, может быть null | Начало диалога, ISO 8601 UTC. |
updated_at | string обязательное | Последнее изменение или сообщение, ISO 8601 UTC. По нему идёт обход. Счётчик непрочитанного его не меняет. |
#MessageAttachment
Вложение сообщения.
| Поле | Тип | Описание |
|---|---|---|
type | string обязательное, может быть null | Вид содержимого: image, file, audio … |
url | string обязательное | Временная подписанная ссылка на файл (скачивание без ключа API). Не сохраняйте ссылку: запросите сообщение заново. |
expires_at | string обязательное, может быть null | Когда ссылка перестанет работать, ISO 8601 UTC (около часа); null — постоянный путь. |
name | string необязательное | Имя файла (вложения, загруженные через виджет или оператором). |
size | integer необязательное | Размер, байт. |
#Message
Сообщение диалога. Содержит персональные данные клиента (текст, вложения).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор сообщения (uuid). |
conversation_id | string обязательное | Диалог. |
sender | string обязательное | Отправитель: customer — клиент, ai — ИИ, operator — оператор, system — служебное. Значения: customer ai operator system |
content_type | string обязательное | Вид содержимого: text, image, file … |
content | string необязательное, может быть null | Текст; null — текста нет (только вложение) или сообщение удалено. Персональные данные: в чтении приходит, только если названо в fields=. |
attachments | array<MessageAttachment> необязательное | Вложения: до пяти файлов на сообщение. Персональные данные: в чтении приходит, только если названо в fields=. |
cards | array<MessageCard> необязательное | Карточки товаров сообщения (до трёх); поля нет — карточек нет. Персональных данных не содержат. |
deleted | boolean обязательное | true — сообщение удалено (приходит только при include_deleted=true; текста и вложений нет). |
created_at | string обязательное | Время сообщения, ISO 8601 UTC. |
#ConversationPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Conversation> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#MessagePage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Message> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#ConversationCreate
Диалог клиента вашего канала. Неизвестные поля — 422.
| Поле | Тип | Описание |
|---|---|---|
external_customer_id | string обязательное | Стабильный идентификатор клиента в вашей системе (не телефон и не почта). По нему платформа находит или заводит контакт и диалог; идентификаторы разных интеграций не смешиваются. |
name | string необязательное | Имя клиента. Пишется только в пустое поле контакта. |
email | string необязательное | Почта клиента. Пишется только в пустое поле контакта. |
phone | string необязательное | Телефон в международном формате (+…). Пишется только в пустое поле контакта. |
language | string необязательное | Язык нового диалога (ISO 639-1). Язык ответа ИИ ограничен языками ячейки. |
#MessageCreate
Сообщение клиента. Вложения в v1 не принимаются. Неизвестные поля — 422.
| Поле | Тип | Описание |
|---|---|---|
content | string обязательное | Текст реплики клиента, до 4000 знаков. |
ai_reply | string обязательное | auto — запросить ответ ИИ-продажника (нужна область ai_seller:invoke; без неё сообщение только сохраняется); none — только сохранить сообщение. Значения: auto none |
#AiReply
Что стало с ответом ИИ на сообщение клиента.
| Поле | Тип | Описание |
|---|---|---|
status | string обязательное | replied — ИИ ответил (ответ — отдельное сообщение диалога); queued — ответ готовится (операция); queued_for_review — ответ ИИ стал черновиком и ждёт оператора (режим надзора); skipped — ИИ не ответит, причина в reason. Значения: replied queued queued_for_review skipped |
reason | string необязательное | Только при skipped: operator_active, spam, flow_reply, ai_unavailable_handoff, no_agent, daily_limit, insufficient_funds, upstream_unavailable, quota_exceeded, not_requested. Список может расширяться. Значения: operator_active spam flow_reply ai_unavailable_handoff no_agent daily_limit insufficient_funds upstream_unavailable quota_exceeded not_requested |
#MessageAccepted
Сообщение клиента принято.
| Поле | Тип | Описание |
|---|---|---|
message_id | string обязательное | Идентификатор записанного сообщения клиента. |
conversation_id | string обязательное | Диалог. |
ai_reply | AiReply обязательное | |
reply | object необязательное | Только при replied: идентификатор ответа ИИ. Текста в ответе нет — прочитайте его GET /conversations/{id}/messages (выдача ПДн в журнале). |
reply.id | string обязательное | |
operation | Operation необязательное | Операция conversation.ai_reply: при 202 — queued или running, при 200 — завершена (usage.cost — списано с кошелька в его валюте). Нет, если ответ ИИ не запрашивался. |
#LeadFlags
Флаги ИИ по переписке. true/false ставятся только при уверенности модели.
| Поле | Тип | Описание |
|---|---|---|
buy_intent | boolean обязательное, может быть null | Намерение купить; null — модель не уверена. |
support | boolean обязательное, может быть null | Обращение в поддержку, а не покупка; null — не уверена. |
supplier | boolean обязательное, может быть null | Поставщик или рекламодатель, а не клиент; true уводит лид в архив (ai_not_client). |
#LeadScore
Оценка лида. null у лида, которого ещё не оценивали.
| Поле | Тип | Описание |
|---|---|---|
score | integer обязательное | Балл 0–100. |
grade | string обязательное | Класс: A — 75 и выше, B — 50–74, C — 25–49, D — ниже 25. Значения: A B C D |
reason | string необязательное, может быть null | Объяснение оценки; null, пока не записано. Персональные данные: приходит, только если названо в fields=. |
flags | LeadFlags обязательное, может быть null | |
source | string обязательное, может быть null | Кто оценил: ai, external или manual; null — неизвестно. Значения: ai external manual |
model | string обязательное, может быть null | Модель, поставившая флаги; null, если оценка не ИИ. |
scored_at | string обязательное, может быть null | Когда выставлена оценка. ISO 8601 UTC. |
#LeadContact
Контакт лида. Поля с персональными данными приходят, только если названы в fields=; выдача пишется в журнал выдач.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор контакта. |
first_name | string необязательное, может быть null | Имя (contact.first_name). Персональные данные: приходит, только если названо в fields=. |
last_name | string необязательное, может быть null | Фамилия (contact.last_name). Персональные данные: приходит, только если названо в fields=. |
email | string необязательное, может быть null | Почта (contact.email). Персональные данные: приходит, только если названо в fields=. |
phone | string необязательное, может быть null | Телефон (contact.phone). Персональные данные: приходит, только если названо в fields=. |
tags | array<string> обязательное | |
geo_country | string необязательное, может быть null | Страна по IP, ISO 3166-1 alpha-2 (contact.geo_country). Персональные данные: приходит, только если названо в fields=. |
geo_city | string необязательное, может быть null | Город по IP (contact.geo_city). Персональные данные: приходит, только если названо в fields=. |
#LeadAttribution
Откуда пришёл лид (первое касание). null, если следов нет.
| Поле | Тип | Описание |
|---|---|---|
utm_source | string обязательное, может быть null | |
utm_medium | string обязательное, может быть null | |
utm_campaign | string обязательное, может быть null | |
first_page | string обязательное, может быть null | Страница первого визита. |
referrer | string обязательное, может быть null |
#Lead
Лид арендатора. С fields= приходят только перечисленные поля (и id).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор лида. |
external_id | string обязательное, может быть null | Идентификатор во внешней CRM; null, пока внешняя CRM не подключена. |
external_url | string обязательное, может быть null | |
version | integer обязательное, может быть null | Версия для If-Match; null, пока в базе нет колонки версии — используйте etag. |
etag | string обязательное | Метка версии (совпадает с заголовком ETag карточки). |
status | string обязательное | Один из шести канонических статусов. Архив — флаг archived, не статус. Значения: new qualified proposal negotiation won lost |
archived | boolean обязательное | Лид в архиве. |
archived_reason | string обязательное, может быть null | Причина архива, например ai_not_client. |
owner | string обязательное | Где живёт лид: internal — в нашей CRM. Значения: internal external |
title | string необязательное, может быть null | Заголовок лида. Персональные данные: приходит, только если названо в fields=. |
source | string обязательное, может быть null | |
assigned_to | string обязательное, может быть null | Идентификатор ответственного сотрудника. |
value | Money обязательное, может быть null | |
product_id | string обязательное, может быть null | |
course_slug | string обязательное, может быть null | |
contact | LeadContact обязательное, может быть null | |
conversation_id | string обязательное, может быть null | |
attribution | LeadAttribution обязательное, может быть null | |
score | LeadScore обязательное, может быть null | |
flags | LeadFlags обязательное, может быть null | |
intent | string необязательное, может быть null | Намерение клиента. Персональные данные: приходит, только если названо в fields=. |
ai_summary | string необязательное, может быть null | ИИ-сводка переписки. Персональные данные: приходит, только если названо в fields=. |
next_action | string необязательное, может быть null | Следующее действие. Персональные данные: приходит, только если названо в fields=. |
next_action_at | string обязательное, может быть null | ISO 8601 UTC. |
lost_reason | string необязательное, может быть null | Причина проигрыша. Персональные данные: приходит, только если названо в fields=. |
qualified_at | string обязательное, может быть null | ISO 8601 UTC. |
won_at | string обязательное, может быть null | ISO 8601 UTC. |
lost_at | string обязательное, может быть null | ISO 8601 UTC. |
last_activity_at | string обязательное, может быть null | ISO 8601 UTC. |
created_at | string обязательное | Создан. ISO 8601 UTC. |
updated_at | string обязательное | Изменён. ISO 8601 UTC. |
#LeadPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Lead> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |