Аналитика и Tracker через API

Аналитика через API — это те же цифры, что вы видите в отчётах Chatterfy: сколько пришло новых чатов, сколько было активных, сколько сообщений написали операторы и как быстро они отвечают. Через API и

Обновлено 2 ноября 2026 г.5 мин

В статье — как запросить аналитику бота и операторов, что значит каждая метрика, а также как получить кампании, домены, лендинги и лиды Tracker и узнать, откуда пришёл клиент.

Что понадобится

Для аналитики: роль Space manager или выше — нужно право analytics.bot.read.

Для Tracker: роль Administrator в компании. Buyer и Buyer team lead видят только кампании, где они указаны баером. Подробнее — Права API-ключа: какую роль выдать.

id бота или id компании — Первый запрос к API за 5 минут.

Как устроен запрос аналитики бота

Отчёты аналитики бота запрашиваются методом GET по адресам /analytics/v1/bots/{bot_id}/..., а параметры from, to и timezone передаются прямо в адресе после знака ?:

curl 'https://api.chatterfy.ai/public-api/analytics/v1/bots/ID_БОТА/chats/new?from=2026-10-01T00:00:00Z&to=2026-10-31T23:59:59Z&timezone=Europe/Moscow' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Параметр	Обязательно	Что значит
`from`	Да	Начало периода, например `2026-10-01T00:00:00Z`. Входит в период
`to`	Да	Конец периода, позже `from`. Входит в период. Период — не больше 366 дней
`timezone`	Нет	Часовой пояс, по которому период делится на дни, например `Europe/Moscow`. По умолчанию UTC
`group_by`	Нет	Только для отчётов по операторам: `day` — по дням (по умолчанию), `hour` — по часам
`operator_id`	Нет	Только для отчётов по операторам: показать одного оператора

В ответе — список точек: дата начала дня или часа и значение. Даты приходят в UTC.

{
  "points": [
    { "date": "2026-10-01T00:00:00Z", "value": 42 },
    { "date": "2026-10-02T00:00:00Z", "value": 37 }
  ]
}

Отчёты аналитики по чатам: новые, активные, сводка

Адрес	Что показывает
`/analytics/v1/bots/{bot_id}/chats/new`	Сколько чатов началось за каждый день
`/analytics/v1/bots/{bot_id}/chats/active`	Сколько чатов получили сообщение от клиента за каждый день. Чат, активный три дня, посчитается в каждом из них
`/analytics/v1/bots/{bot_id}/chats/summary`	Новые чаты за сегодня, вчера, эту и прошлую неделю, этот и прошлый месяц

chats/summary сам знает свои периоды, поэтому принимает только timezone:

curl 'https://api.chatterfy.ai/public-api/analytics/v1/bots/ID_БОТА/chats/summary?timezone=Europe/Moscow' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

{
  "today": 18,
  "yesterday": 41,
  "week": 120,
  "last_week": 263,
  "month": 1034,
  "last_month": 1187
}

Отчёты аналитики по операторам

Отчёты по операторам показывают сообщения, чаты, действия и скорость ответа каждого оператора бота. Все адреса начинаются с /analytics/v1/bots/{bot_id}/operators/:

Адрес	Что показывает
`/operators/messages`	Сколько сообщений написал каждый оператор. Сообщения бота не считаются
`/operators/chats`	В скольких разных чатах писал каждый оператор
`/operators/events`	Сколько действий сделал оператор, кроме сообщений: смена тега, статуса, шага
`/operators/messages-per-chat`	Сколько сообщений в среднем приходится на один чат оператора
`/operators/events-per-chat`	Сколько действий в среднем приходится на один чат оператора
`/operators/reply-time`	Медиана в секундах: сколько клиент ждал ответа оператора

Все адреса начинаются с /analytics/v1/bots/{bot_id}. В каждой точке ответа есть operator_id — id оператора. Имя ищите в списке участников Space: POST /spaces/v1/{space_id}/members/search.

curl 'https://api.chatterfy.ai/public-api/analytics/v1/bots/ID_БОТА/operators/reply-time?from=2026-10-01T00:00:00Z&to=2026-10-31T23:59:59Z&timezone=Europe/Moscow&group_by=day' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Как считается скорость ответа оператора

Учитывается время между сообщением клиента и ответом оператора. Чат, на который оператор так и не ответил, в медиану не попадает — он виден как чат без ответа. Ответ засчитывается в день сообщения клиента: ответ сразу после полуночи пойдёт в предыдущий день.

Кампании Tracker через API

Кампании Tracker ищет POST /campaigns/v1/search с company_id в теле: Tracker работает на уровне компании, а не бота. Создать кампанию через API нельзя — только в приложении.

curl -X POST 'https://api.chatterfy.ai/public-api/campaigns/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"company_id": "ID_КОМПАНИИ", "status": "active"}'

В поиске можно отобрать кампании по status (active или stopped), target_type, bot_id и части названия query. Новые кампании идут первыми.

Запрос	Что делает
`GET /campaigns/v1/{campaign_id}`	Кампания целиком: источники, параметры, боты, баеры
`PATCH /campaigns/v1/{campaign_id}`	Изменить `name`, `description` или `status`. Статус `stopped` ставит кампанию на паузу
`GET /campaigns/v1/{campaign_id}/sources`	Источники трафика — по одному на рекламную платформу. Ключи доступа и пиксели не возвращаются
`GET /campaigns/v1/{campaign_id}/params`	Параметры ссылки кампании, например `clickid` или `utm_source`
`POST /campaigns/v1/{campaign_id}/params`	Добавить параметр: `name`, `key` и необязательный `placeholder`
`DELETE /campaigns/v1/{campaign_id}/params/{param_id}`	Удалить параметр

Домены и лендинги Tracker

Запрос	Что делает
`POST /domains/v1/search`	Домены компании. `status: ready` — домен работает
`POST /domains/v1`	Добавить домен: `company_id` и `link`. Домен заработает, когда его DNS будет указывать на Chatterfy
`PATCH /domains/v1/{domain_id}`	Сменить `link`. Домен снова станет `not_ready`, пока не проверится новый DNS
`DELETE /domains/v1/{domain_id}`	Удалить домен. Сначала переключите кампании, которые на него ссылаются
`POST /landings/v1/search`	Лендинги компании, без кода страниц
`GET /landings/v1/{landing_id}`	Один лендинг

Домен можно зарегистрировать только один раз на всей платформе — занятый адрес вернёт ошибку 409 domain_already_exists. Домен в статусе blocked нельзя изменить или удалить: 409 domain_blocked.

Узнайте, откуда пришёл клиент: лид Tracker

Источник клиента — лид Tracker: его lead_id есть в чате, а сам лид отдаёт GET /leads/v1/{lead_id}.

Возьмите lead_id из чата

Запросите чат через GET /chats/v1/{chat_id}. Если клиент пришёл через кампанию Tracker, в чате будет lead_id.

Запросите лида

curl 'https://api.chatterfy.ai/public-api/leads/v1/ID_ЛИДА' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

id лида — короткая строка, а не UUID, как у остальных объектов.

Посмотрите метки и события

В params — метки из ссылки, по которой пришёл клиент, например utm_source. В events — события воронки, например purchase, с суммой в cost. В campaign_id — кампания, её можно запросить через GET /campaigns/v1/{campaign_id}.

Как устроены лиды в Tracker — в статье Leads — лиды и события.