Analytics and Tracker via API

Analytics via API provides the same figures you see in Chatterfy reports: how many new chats arrived, how many were active, how many messages operators wrote, and how fast they reply. Via API, you can

Updated November 2, 20265 min
Analytics via API provides the same figures you see in Chatterfy reports: how many new chats arrived, how many were active, how many messages operators wrote, and how fast they reply. Via API, you can export them to your spreadsheet or BI system.
This article explains how to request bot and operator analytics, what each metric means, as well as how to retrieve Tracker campaigns, domains, landing pages, and leads to find out where the client came from.


What you will need

  1. For analytics: Space manager role or higher — requires analytics.bot.read permission.
  1. For Tracker: Administrator role in the company. Buyer and Buyer team lead can only see campaigns where they are listed as the buyer. Read more — API Key Permissions: Which Role to Assign.
  1. bot ID or company ID — First API request in 5 minutes.


How bot analytics requests work

Bot analytics reports are requested using the GET method at addresses /analytics/v1/bots/{bot_id}/..., and the from, to, and timezone parameters are passed directly in the URL after the ? sign:
Новые чаты по дням за октябрьbash
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: ВАШ_КЛЮЧ'
Parameter
Required
What it means
from
Yes
Start of the period, e.g., 2026-10-01T00:00:00Z. Included in the period
to
Yes
End of the period, later than from. Included in the period. The period cannot exceed 366 days
timezone
No
Timezone by which the period is divided into days, e.g., Europe/Moscow. Defaults to UTC
group_by
No
Only for operator reports: day — by days (default), hour — by hours
operator_id
No
Only for operator reports: show a single operator
The response is a list of data points: the start date of the day or hour and the value. Dates are provided in UTC.
Ответjson
{
  "points": [
    { "date": "2026-10-01T00:00:00Z", "value": 42 },
    { "date": "2026-10-02T00:00:00Z", "value": 37 }
  ]
}


Chat analytics reports: new, active, summary

Address
What it shows
/analytics/v1/bots/{bot_id}/chats/new
Number of chats started per day
/analytics/v1/bots/{bot_id}/chats/active
Number of chats that received a message from a client per day. A chat active for three days will be counted in each of them.
/analytics/v1/bots/{bot_id}/chats/summary
New chats for today, yesterday, this and last week, this and last month
chats/summary knows its own periods, so it only accepts timezone:
Запросbash
curl 'https://api.chatterfy.ai/public-api/analytics/v1/bots/ID_БОТА/chats/summary?timezone=Europe/Moscow' \
  -H 'ApiKey: ВАШ_КЛЮЧ'
Ответjson
{
  "today": 18,
  "yesterday": 41,
  "week": 120,
  "last_week": 263,
  "month": 1034,
  "last_month": 1187
}


Operator analytics reports

Operator reports show messages, chats, actions, and response speed for each bot operator. All addresses start with /analytics/v1/bots/{bot_id}/operators/:
Address
What it shows
/operators/messages
How many messages each operator wrote. Bot messages are not counted.
/operators/chats
In how many different chats each operator wrote.
/operators/events
How many actions an operator performed, other than messages: changing a tag, status, or step.
/operators/messages-per-chat
Average number of messages per operator chat
/operators/events-per-chat
Average number of actions per operator chat
/operators/reply-time
Median in seconds: how long the client waited for an operator's response
All addresses start with /analytics/v1/bots/{bot_id}. Each response point includes an operator_id — the operator's ID. Look for the name in the list of Space members: POST /spaces/v1/{space_id}/members/search.
Скорость ответа операторов по днямbash
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: ВАШ_КЛЮЧ'


How operator response time is calculated

The time between the client's message and the operator's response is taken into account. A chat to which the operator did not respond is not included in the median — it appears as a chat without a response. The response is counted on the day of the client's message: a response immediately after midnight counts towards the previous day.


Tracker campaigns via API

Tracker campaigns are searched via POST /campaigns/v1/search with company_id in the body: Tracker works at the company level, not the bot level. You cannot create a campaign via the API — only in the application.
Список кампанийbash
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"}'
In the search, you can filter campaigns by status (active or stopped), target_type, bot_id, and part of the name in query. New campaigns appear first.
Request
What it does
GET /campaigns/v1/{campaign_id}
Entire campaign: sources, parameters, bots, buyers
PATCH /campaigns/v1/{campaign_id}
Change name, description, or status. The stopped status pauses the campaign
GET /campaigns/v1/{campaign_id}/sources
Traffic sources — one per advertising platform. Access keys and pixels are not returned
GET /campaigns/v1/{campaign_id}/params
Campaign link parameters, for example clickid or utm_source
POST /campaigns/v1/{campaign_id}/params
Add parameter: name, key, and an optional placeholder
DELETE /campaigns/v1/{campaign_id}/params/{param_id}
Delete parameter


Tracker domains and landing pages

Request
What it does
POST /domains/v1/search
Company domains. status: ready — the domain is active
POST /domains/v1
Add a domain: company_id and link. The domain will become active once its DNS points to Chatterfy
PATCH /domains/v1/{domain_id}
Change the link. The domain will become not_ready again until the new DNS is verified
DELETE /domains/v1/{domain_id}
Delete a domain. First, switch the campaigns that refer to it
POST /landings/v1/search
Company landing pages, excluding page code
GET /landings/v1/{landing_id}
A single landing page
A domain can be registered only once on the entire platform — a taken address will return a 409 domain_already_exists error. A domain with the blocked status cannot be changed or deleted: 409 domain_blocked.


Find out where the client came from: Tracker lead

The client's source is a Tracker lead: their lead_id is in the chat, and the lead itself is returned via GET /leads/v1/{lead_id}.

  1. Get the lead_id from the chat

    Request the chat via GET /chats/v1/{chat_id}. If the client came through a Tracker campaign, the chat will contain a lead_id.

  2. Request the lead

    Запросbash
    curl 'https://api.chatterfy.ai/public-api/leads/v1/ID_ЛИДА' \
  -H 'ApiKey: ВАШ_КЛЮЧ'
    The lead ID is a short string, not a UUID like other objects.

  3. View tags and events

    In params, there are tags from the link the client used, for example, utm_source. In events, there are funnel events, such as purchase, with the amount in cost. campaign_id is the campaign, which can be requested via GET /campaigns/v1/{campaign_id}.
How leads are structured in Tracker — in the article Leads — leads and events.


FAQ



Related

Leads — leads and events
Tracker → Leads is a section for viewing individual leads and their events. Here you can find a record by Click ID, filter the selection, and check the source, campaign, latest event, and funnel stage
Chats — conversation analytics
The Chats tab in the — is the main analytics view for the number of bot conversations. Here you can see: how many users messaged the bot how activity changes by day whether leads return how effectivel
API Key Permissions: Which Role to Assign
API key permissions define what an application is allowed to do in Chatterfy. They depend on two service account roles: the company role and the role in each Space. This article explains which role to
How to get chats and messages via API
Chats and messages via the API are read in two requests: first the list of bot chats, then the messages of the specific chat. This is the same as opening the bot in the application and tapping on a co

Was this article helpful?