События и аналитика

Как устроены события

Событие — запись о том, что что-то реально произошло: показан пейволл, человек открыл оплату, платёж прошёл, вызван агент. События только добавляются и не меняются. Из них строятся графики, воронка и статистика агентов в интерфейсе, и те же данные доступны через API.

Метод	Путь	Что отдаёт
GET	/assistants/{assistantId}/events	Сырой список событий с фильтрами
GET	/assistants/{assistantId}/events/summary	Счётчики по именам и разбивки пейволла, оплат и покупок
GET	/assistants/{assistantId}/events/funnel	Воронка по уникальным пользователям

Авторизация — ключ user_…, доступ у владельца и пользователя с расшаренным доступом. Чужой ассистент — 404 {"error": "Project not found or access denied"}.

У каждого события есть name, props (объект со свойствами, набор зависит от имени), user_id, chat_id и created_at. Повтор того же события от того же пользователя чаще раза в 10 секунд обычно не пишется, поэтому события — факты, а не клики вслепую.

Границы периода. Параметры from и to у всех трёх методов принимают YYYY-MM-DD или YYYY-MM-DD HH:MM:SS в UTC, обе границы включительно. Дата без времени — это полночь: to=2026-09-24 отрежет весь день 24-го. Чтобы захватить день целиком, передавайте to=2026-09-24 23:59:59. Нераспознанная дата молча игнорируется. Без границ считается вся история ассистента.

Методы

Список событий

Сырые события ассистента от новых к старым.

GET /assistants/{assistantId}/events

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	Путь. Id ассистента.
name	string	нет	Строка запроса. Имя события, одно. Старое имя command_executed принимается и отдаёт то же, что agent_invoked.
from, to	string	нет	Строка запроса. Границы по created_at.
limit	integer	нет	Строка запроса. 1–1000, по умолчанию 100.
offset	integer	нет	Строка запроса. По умолчанию 0.

curl -s "$BASE/assistants/$ASSISTANT/events?name=purchase&from=2026-09-01&limit=2" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "total": 12,
  "events": [
    {
      "id": 227495,
      "name": "purchase",
      "props": {
        "amount": 490,
        "currency": "RUB",
        "credits": 5428,
        "payment_id": 15244,
        "screen": "LQmAMDZFO44o"
      },
      "user_id": 100231,
      "chat_id": 64141,
      "created_at": "2026-09-22T03:10:53+00:00"
    },
    {
      "id": 277579,
      "name": "agent_invoked",
      "props": {
        "agent_id": 3678,
        "label": "Canva",
        "action": "send",
        "display_type": "image-tile",
        "category": "Изображения",
        "source": "link",
        "prompt": "You are Canva, a design assistant…"
      },
      "user_id": 100452,
      "chat_id": null,
      "created_at": "2026-09-25T19:48:09+00:00"
    }
  ]
}

Свойство	Тип	Описание
total	integer	Сколько событий подходит под фильтр, без учёта limit и offset.
events[].id	integer	Id события.
events[].name	string	Имя события, см. справочник ниже.
events[].props	object или null	Свойства события.
events[].user_id	integer или null	Внутренний id пользователя. null — действие без учётки (например, «Повторить диалог» у постороннего читателя).
events[].chat_id	integer или null	Id чата, если действие было в диалоге.
events[].created_at	string	ISO 8601, UTC.

HTTP	Когда
404	Ассистент не найден или нет доступа

Агрегаты

Счётчики по всем именам событий за период и готовые разбивки для денег: почему и где показан пейволл, через какой шлюз открыли оплату, сколько принесли покупки и какие агенты доводят до денег.

GET /assistants/{assistantId}/events/summary

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	Путь. Id ассистента.
from, to	string	нет	Строка запроса. Границы периода.

curl -s "$BASE/assistants/$ASSISTANT/events/summary?from=2026-09-01&to=2026-09-30%2023:59:59" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "range": {
    "from": "2026-09-01T00:00:00+00:00",
    "to": "2026-09-30T23:59:59+00:00"
  },
  "totals": {
    "agent_invoked": 1922,
    "checkout_opened": 38,
    "login": 39,
    "message_milestone": 1249,
    "paywall_shown": 1412,
    "purchase": 6,
    "registered": 101,
    "welcome_shown": 1865
  },
  "breakdowns": {
    "paywall_shown": {
      "by_reason": { "link": 910, "limit": 420, "feature_gate": 82 },
      "by_source": { "message": 586, "chat": 501, "menu": 285, "url": 26, "cliffhanger": 13 },
      "by_agent": { "936": 38, "944": 12, "18": 6 }
    },
    "checkout_opened": {
      "by_gateway": { "cloudpayments": 15, "payonline": 23 },
      "by_agent": { "18": 1, "944": 1 }
    },
    "purchase": {
      "count": 6,
      "revenue_by_currency": { "RUB": 4350 },
      "by_agent": {
        "18": { "count": 1, "revenue": { "RUB": 1900 } }
      }
    }
  }
}

Свойство	Тип	Описание
range.from, range.to	string или null	Распознанные границы; null — граница не задана.
totals	object	Имя события → сколько раз случилось за период. Все имена, которые встречались, без исключений. Старые вызовы агента под именем command_executed, если они есть, идут отдельным ключом.
breakdowns.paywall_shown.by_reason	object	Показы пейволла по props.reason.
breakdowns.paywall_shown.by_source	object	Показы по props.source — где в интерфейсе.
breakdowns.paywall_shown.by_agent	object	Показы по id агента, активного в чате. Показы без агента сюда не входят.
breakdowns.checkout_opened.by_gateway	object	Открытия оплаты по шлюзу.
breakdowns.checkout_opened.by_agent	object	Открытия оплаты по агенту.
breakdowns.purchase.count	integer	Покупки за период без возвращённых платежей.
breakdowns.purchase.revenue_by_currency	object	Валюта → сумма покупок без возвратов. Валюты не складываются.
breakdowns.purchase.by_agent	object	Id агента → count и revenue по валютам. Покупки без агента не входят.

Ключи в разбивках — строки. Событие без нужного свойства в разбивку не попадает, поэтому сумма разбивки может быть меньше счётчика в totals. Доход здесь считается по событиям purchase; точные деньги в долларах — в платежах (revenue_usd).

HTTP	Когда
404	Ассистент не найден или нет доступа

Воронка

Три шага подписочной воронки по уникальным пользователям: увидел пейволл → открыл оплату → купил, и конверсии между шагами.

GET /assistants/{assistantId}/events/funnel

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	Путь. Id ассистента.
from, to	string	нет	Строка запроса. Границы периода.

curl -s "$BASE/assistants/$ASSISTANT/events/funnel?from=2026-09-01&to=2026-09-30%2023:59:59" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "range": {
    "from": "2026-09-01T00:00:00+00:00",
    "to": "2026-09-30T23:59:59+00:00"
  },
  "steps": [
    { "name": "paywall_shown", "users": 896 },
    { "name": "checkout_opened", "users": 30 },
    { "name": "purchase", "users": 6 }
  ],
  "conversion": {
    "paywall_to_checkout": 3.3,
    "checkout_to_purchase": 20,
    "overall": 0.7
  }
}

Свойство	Тип	Описание
steps[].users	integer	Сколько разных пользователей сделали этот шаг за период.
conversion.paywall_to_checkout	number	Процент, один знак после запятой. При нуле в знаменателе — 0.
conversion.checkout_to_purchase	number	То же для оплаты → покупки.
conversion.overall	number	Покупка от показа пейволла.

Шаги считаются независимо: человек, купивший без показа пейволла в этом периоде, всё равно попадёт в purchase. Возвраты воронка не вычитает. Докупка кредитов идёт отдельной воронкой topup_card_shown → topup_clicked → topup_purchased — её считают через summary или список.

HTTP	Когда
404	Ассистент не найден или нет доступа

Справочник событий

Деньги и пейволл

Событие	Когда пишется	Свойства (props)
paywall_shown	Показан пейволл	reason: limit (кончились сообщения или кредиты), link (клик по ссылке или кнопке покупки), feature_gate (попросил закрытую возможность); trigger: messages или credits (у limit); feature: image, search, voice, memory (у feature_gate); source — где показан (chat, message, menu, url, cliffhanger, image, diagram, video, widget, api, voice, delay); template — имя своего HTML-шаблона, если показан он; locale, currency, agent_id
paywall_methods_shown	Показан экран выбора способа оплаты	methods — список способов; gateway, interval, amount, currency, plan_name, agent_id
paywall_methods_back	«Назад» с выбора способа к тарифам	—
paywall_locale_changed	Сменили язык на экране оплаты	from, to
checkout_opened	Открыто окно оплаты	gateway, interval, amount, currency, plan_name, agent_id
purchase	Платёж подтверждён шлюзом	amount, currency, credits, payment_id, agent_id, screen — экран, с которого пришёл человек; top_up: true у докупки
topup_card_shown	В ленте показана плашка докупки кредитов тому, кто уже платил	source: chat_feed, blocked_feature (chat, image, video, diagram), block_reason (credits, messages_limit), topup_available, free_model_available, amount, credits, currency, plan_name, agent_id
topup_clicked	Клик по кнопке докупки	То же, плюс source: card
topup_purchased	Докупка оплачена, кредиты начислены	amount, currency, credits, payment_id, agent_id

agent_id — id агента, активного в чате; ключа нет вовсе, если работал сам ассистент без агента. У purchase агент определяется эвристикой: по последнему paywall_shown того же человека у этого ассистента за 24 часа.

Пользователи и активность

Событие	Когда пишется	Свойства (props)
registered	Создан аккаунт	method: google, telegram, telegram_chat, email
login	Вход в существующий аккаунт	method — те же значения
message_milestone	Человек отправил N-е сообщение	count: 1, 5, 10, 25, 50, 100, 250, 500
welcome_shown	Показан приветственный экран	screen — слаг экрана
agent_invoked	Вызван агент	agent_id, label, action, display_type, category и промпт-поля агента (prompt, prepared_response, subtitle, prompt_target и другие); source — откуда вызов: auto_switch — ассистент сам переключился на агента (тогда ещё reason — обоснование модели), другие значения присылает интерфейс (например, link — агент открыт по прямой ссылке); без source — клик человека по карточке
suggestion_clicked	Клик по варианту ответа	index, count, dialog_type
repeat_chat_clicked	«Повторить диалог» под чужим публичным диалогом	source: shared_chat, agent_id; user_id часто null
auth_popup_opened	Открылось окно входа	branch (google, telegram), host, in_iframe, foreign_host, ua, standalone, attempt
auth_popup_blocked	Окно входа заблокировал браузер	То же плюс ms_since_click

Раньше вызов агента назывался command_executed. Фильтр name понимает оба имени.

Контент

Событие	Когда пишется	Свойства (props)
image_downloaded	«Скачать» под картинкой	source: message, agent_id
image_share_clicked	«Поделиться» под картинкой — клик, а не факт отправки	source: message, agent_id
image_4k_clicked	«HD качество» под картинкой	source: message, agent_id
image_generated_4k	HD-версия сгенерирована, кредиты списаны	model, cost (USD), size, agent_id
video_generated	Сгенерировано видео	—
document_downloaded, document_printed	Документ скачан или отправлен на печать	format (pdf, docx, md, txt, html или расширение оригинала), original, source (panel, chat_card, documents_page, documents_tree), file, agent_id

Панели агентов

Эти события пишут агенты с собственными панелями — планер постов, креативы и экран-форма агента.

Событие	Когда пишется	Свойства (props)
post_created, post_updated, post_deleted, posts_reordered, posts_demo_inserted, post_media_removed	Действия с постами в плане публикаций	source (agent, manual, frame), brand_id, post_id, count, network, format, agent_id; у post_updated ещё fields — что изменено
post_image_generated	Картинки к посту нарисованы и оплачены	cost, post_id, count, requested, network, format, reference, aspect, model, source, agent_id
brand_created, brand_switched	Заведён бренд, выбран другой бренд	brand_id, demo_count или from, agent_id
posts_panel_opened, posts_panel_closed	Открыта или закрыта панель постов	source, brand_id, agent_id
post_attached, post_detached, post_previewed, post_copied, post_exported, posts_cleared, post_media_uploaded	Действия в панели постов	post_id, brand_id, source, agent_id и специфичные поля
posts_feedback_sent	Отправлен отзыв «Что улучшить?» из панели постов	ticket_id, brand_id, posts_count, agent_id
creatives_panel_opened, creatives_panel_closed, creatives_platform_picked, creatives_photo_uploaded, creative_generate, creative_generated, creative_generate_failed, creative_attached	Действия в панели креативов	source, platform, format, reference_id, has_photo, count, reason (у failed), creative_id
frame_opened, frame_submitted, frame_closed	Показан, отправлен или закрыт экран-форма агента	frame_id, agent_id; у submitted — frame, example_id, network, tone, has_photo, has_comment; у closed — source

Служебные

client_diag — диагностический снимок браузера при загрузке чата: контекст встраивания, хранилище, маркер устройства. Это не аналитика: события хранятся 30 дней, в props есть технические данные устройства и сети. Для отчётов отфильтровывайте его по name.

Сценарий: какие агенты приносят деньги

Один запрос summary за месяц даёт по каждому агенту показы пейволла, открытия оплаты и выручку:

curl -s "$BASE/assistants/$ASSISTANT/events/summary?from=2026-09-01&to=2026-09-30%2023:59:59" \
  -H "Authorization: Bearer $KEY" \
  | jq '.breakdowns | {paywall: .paywall_shown.by_agent, checkout: .checkout_opened.by_agent, revenue: .purchase.by_agent}'

Названия агентов по id — в списке агентов.

Дальше

• Подписчики, кредиты, платежи
• Пейволл и тарифы
• Версии — отметки изменений на графиках