Skip to content
Shortcut: /, ⌘K or Ctrl+K

WhatsApp analytics

Read message engagement, call outcomes and connection vitals for your WhatsApp numbers.

View as Markdown

Open Analytics in the main Console sidebar and select Enable analytics. A team owner or admin controls this one setting for the team. Open the top-right … menu and select Disable and clear analytics to turn it off. Confirm Disable and delete history to remove the team’s stored message and engagement aggregates and queued analytics drain deliveries. This hides business analytics in the Console and API.

The Console error banner shows API and webhook failures from the last 24 hours and links to Logs → Errors. It follows the selected project and remains available when Analytics is off. Choosing a number does not filter these operational counts. Tracking starts after enabling; previous conversation metadata is not reconstructed. The call view uses retained operational call records; disabling Analytics does not delete that separate call history.

Use the project selector in the Console header to choose one project or All projects. Analytics opens on Last 24 hours, the first relative preset. This covers the preceding 24 hours up to the time you select it. Select dates and a number with the controls at the top. All numbers combines the numbers in that project scope.

In Numbers, open a production number's actions and select View analytics to open Analytics with that number selected. The number selection is included in the page URL. Select Refresh analytics to read the latest data for the chosen period.

Open All Numbers to search number names, project names or record IDs. Select a number to filter the page, or select the separate All Numbers row to return to the combined view. The picker groups numbers by project in searchable accordions.

The date range, API examples, Export all data, refresh and … actions sit above the data. Export all data downloads CSV for the selected project and number scope. The CSV preserves all returned fields in a long format: dataset, record, number ID, UTC timestamp, metric, value and value type. Each scalar measurement has its own row; missing values remain empty with a null type. For one row per category, use the breakdown’s CSV export. A number-specific export omits project-wide API request totals and the combined summary; the all-number export preserves the full response. Missing measurements show —.

Activity timeline uses lines with a light fill. Select a legend item to hide or restore its series and isolate one signal. At least one series stays visible. Changing the activity view restores both series. The response timeline and Phone intervals use the same controls; intervals without observations remain gaps. Tooltips show measured zeroes as 0 and unmeasured values as —.

The number table compares activity, reads, replies, response time, call answer rates, missed incoming calls and connection problems. Credits, limits and billable session-days stay in Usage.

What the numbers mean#

MetricMeasurement
Messages sentSuccessful sends observed by your Linked Devices connection, including group sends
Messages receivedObserved incoming direct message events, including reactions; groups excluded
Delivery, read and reply ratesShare of completed 24-hour direct conversations with the corresponding receipt or customer reply
Your average response timeTime from the newest unanswered incoming direct message to your next successful send in that chat
Customer reply timeTime from the conversation's first successful send to the first incoming reply within 24 hours
Online presence timeTime your number advertised itself as available; this is not customer presence or connection uptime
Send failure rateFailed sends divided by observed send attempts
Connection problemsObserved disconnects, connection failures, stream errors and keepalive timeouts

A conversation starts with a successful direct send. Further sends to that chat within 24 hours belong to the same conversation. Results are counted together when that window closes. A subsequent send starts another conversation. Groups and receipts from your own account do not contribute to the rates. Edits, reactions and protocol updates do not count as replies or open the reply queue.

Read rate means a WhatsApp read receipt was observed. It does not measure app opens. People who disable read receipts can read a message without contributing a receipt. A missing receipt does not prove the message was unread.

Counts cover recorded activity. Dashes and API null rates mean there is no completed denominator or tracking coverage is incomplete. Message activity on unobserved and Official API numbers is marked Not measured. Call outcomes remain available when calls were recorded. Test numbers are excluded. Aggregate rates are unavailable when any number in the selected scope has no measurements; select a measured number to inspect its own results.

The aggregates contain no message content or contact identities. Enabling Analytics does not enable hosted message storage. Operational safety measurements continue independently of the Analytics display setting.

Explore conversations and audience breakdowns#

Analytics opens on Overview. The tabs beside it open Performance by number, Response operations, Devices and platforms and Call outcomes. The selected tab and chart view are part of the page address, so a link or a refresh opens the same view. Performance by number lists each number, with the number vitals below the list. Select a row to scope the page to that number. On a phone, open a row's menu and select Details to see every metric.

In Overview, the horizontal tabs select Conversations, Recipients, Number activity or Calls. Each view uses the same main graph. In Conversations, select Conversations, Read, Replied or Customer reply time above it. Read and Replied show absolute observed conversation counts. Number activity selects sent and received messages, phone and API replies or recipient presence; Calls shows call outcomes. Drag across the graph to narrow the shared date range, or use the date picker. Outcomes are grouped by the time each 24-hour conversation window completed.

Country, message and device breakdowns follow the graph’s selected metric. Its name appears at the top right of each panel. Each category has one absolute count or reply-time value with a horizontal bar; no percentage columns appear in the compact view. Click anywhere on a category row or use its Filter button to filter the conversation graph and every conversation breakdown. Filters intersect: choosing Brazil and Image selects only completed conversations with both values. Remove filter × appears beneath the affected panel's header. The chips above the timeline also remove individual filters; Clear filters removes all of them. The graph and breakdowns use the same filtered conversations.

The underlined Type, Length and Source tabs switch between the first outgoing message's type, length band and source. The split, expansion and export actions follow the selected tab. Use the left and right arrow keys to move between tabs. Length bands are no text, 1–160, 161–500, 501–1,500 and over 1,500 characters, with Unknown separate. Recipient country is inferred from full phone numbering, not location or nationality. Shared calling codes are not treated as unique countries. Older buckets without country metadata stay Unknown. Recipient device-count ranges are Primary only, 1 linked device, 2+ linked devices and Unknown. The linked count excludes the primary device. A complete observed list establishes a count; a missing, stale or invalidated list stays Unknown.

Each breakdown has an action strip. On desktop, hover or focus within the panel to expand its controls; mobile and touch screens keep them visible. Expand all opens a searchable table of every returned category, its completed conversation count, share, delivered/read/replied counts and reply time. The table inherits the active filters. Split by names that breakdown's dimension and compares its categories in the main conversation timeline. Select it again to remove the split. The timeline's Split by menu also lets you choose another dimension or No split without adding another timeline.

Open a breakdown's … menu and select Export as CSV for one aggregate row per category. Country exports use country codes. Exports include every returned category in the selected project, number, date range and active filters, including categories beyond the compact table's first six rows. Search in the expanded table changes the visible list; it does not narrow the export. The filename includes the selected UTC date range. Counts, shares, outcome numerators, read/reply percentages and weighted reply time are separate columns. Unavailable rates and reply times are empty fields, not zeroes.

For hourly joint data, open the timeline's … menu and select Export conversation rows as CSV. This export preserves every matching conversation row, its completion bucket, dimensions and raw outcome numerators. Export all data downloads all scoped fields as CSV. The API response remains JSON.

Read and reply rates divide their outcome counts by completed conversations. Reply time divides the total first-reply delay by replied conversations; it does not average category averages. Partial coverage, dropped conversations and truncated results hide outcome rates and average reply time; observed counts remain available. Known empty measured buckets show zero counts; unobserved buckets remain gaps. These are observed associations, not evidence that a message format caused a response.

Country and device-count filters also apply to recipient signals. Switching to recipient signals clears message type, length and send-source filters, because those attributes belong to conversation outcomes. Selecting number operations clears recipient filters. Connection, owned-phone, platform and call data follows the project/number/date scope.

Through the API, conversationBreakdown.rows jointly groups completed conversations by completion time, recipient country, first outgoing message type, length and source, and linked-device count range. Filter the rows to intersect values, and weight rates by the row sums; never infer an intersection from independent totals:

API

cURL
curl --get "$POLYMORFA_API_URL/platform/analytics" \
  --header "Authorization: Bearer $POLYMORFA_API_KEY" \
  --data-urlencode "projectId=$PROJECT_ID" |
  jq '[.data.summary.conversationBreakdown.rows[]
       | select(.recipientCountry == "BR" and .messageType == "image" and .recipientDeviceCount == "two_plus_linked")]'
TypeScript
const rows = result.data.summary?.conversationBreakdown.rows ?? [];
const selected = rows.filter((row) =>
  row.recipientCountry === "BR" &&
  row.messageType === "image" &&
  row.recipientDeviceCount === "two_plus_linked"
);

const totals = selected.reduce((sum, row) => ({
  completed: sum.completed + row.completedConversations,
  replied: sum.replied + row.repliedConversations,
  replyMs: sum.replyMs + row.replyLatencySumMs,
}), { completed: 0, replied: 0, replyMs: 0 });

const complete = result.data.summary?.conversationBreakdown.complete;
const replyRate = complete && totals.completed ? totals.replied / totals.completed : null;
const averageReplyMs = complete && totals.replied ? totals.replyMs / totals.replied : null;

TypeScript:

result is an analytics.get response; see Read analytics through the API.

Platform message counts are separate observations and cannot be intersected with country from these rows.

Recipient activity and business hours#

Open Recipients for incoming messages, delivery receipts, read receipts and observed online/offline/typing signals. Recipient signals overlays the six signal series in the same graph. The four controls above the main graph select incoming messages, delivery receipts, read receipts and activity. The activity control includes local hours, online/offline/typing signals and average quiet gaps. These measurements use one graph; the shared country, device usage and device-count panels show the selected measurement and filter or split that graph. Select an individual signal above the graph or click a graph legend entry to isolate it. Country, device-count and Device usage rows filter the observed signals. Each panel supports Expand all, Split by and Export as CSV. Splitting the combined signal view switches to incoming messages; select another signal to compare it by the same categories. Expanded tables and CSV exports include presence counts, completed quiet gaps and their weighted average; unavailable averages remain empty CSV fields.

Select Average quiet gap to graph device timing, then Split by Device usage to compare primary and linked devices in that same graph. Device usage separates signals attributed to a primary device, linked device or Unknown source. A nonzero sender device index is a linked-device observation. A delivery receipt means the message reached a device, independently of a read receipt. Multiple devices can receipt the same message; receipt counts are not unique people or messages.

Average quiet gap uses completed gaps of at least 15 minutes between signals from the same observed device. It excludes open gaps and does not establish online/offline time, power state or ability to respond. User-level presence has an Unknown device source. Presence remains subject to your existing presence settings. An intended send reuses a permitted recipient subscription within bounded limits; Analytics does not enable presence, set your number online or poll every contact.

Open the Activity control and select Incoming messages by local hour, then choose a searchable Business time zone. This replaces the main graph rather than adding another one. The graph combines observed hourly counts into local clock hours across the selected period, including daylight-saving changes. Unobserved hours stay gaps. Busiest observed hour compares incoming volume in the observed rows, including partial coverage marked in the panel. It does not establish the busiest hour across missing data or predict conversion. Hourly counts describe when activity was collected, so delayed message arrival can shift a message into a later observation hour.

The API returns optional recipientActivity on the summary and each number: rows includes UTC hour, country, device-count range, device source, incoming and receipt counts, presence counts, last signal, completed quiet-gap count and raw duration sum. Check measured, complete, observedBuckets, droppedSignals and truncated. Missing historical coverage leaves rates or averages unavailable. These aggregates contain no recipient identities or device indexes.

API

cURL
curl --get "$POLYMORFA_API_URL/platform/analytics" \
  --header "Authorization: Bearer $POLYMORFA_API_KEY" \
  --data-urlencode "projectId=$PROJECT_ID" |
  jq '[.data.summary.recipientActivity.rows[]
       | select(.recipientCountry == "BR" and .recipientDeviceCount == "one_linked")]'
TypeScript
const activity = result.data.summary?.recipientActivity;
const selected = activity?.rows.filter((row) =>
  row.recipientCountry === "BR" && row.recipientDeviceCount === "one_linked"
) ?? [];

for (const row of selected) {
  console.log(row.ts, row.deviceSource, row.incomingMessages);
  console.log(row.deliveryReceipts, row.readReceipts);
  console.log(row.quietGaps, row.quietGapMs, row.averageQuietGapMs);
}

deviceSource is primary, linked or unknown. Recipient count ranges are primary_only, one_linked, two_plus_linked and unknown. For a weighted mean quiet gap, add quietGapMs and divide by the total quietGaps, and only when coverage is complete. Use the recipient rows on their own: message metadata is collected jointly in conversationBreakdown, so don't infer message-type intersections from recipient totals.

Linked Devices provides recipient message observations. Official messaging Analytics is unmeasured, including conversations addressed by BSUID. Call coverage is separate.

Device observations#

Devices separates estimated platforms for incoming customer messages from messages sent by your account. Counts describe direct messages, not unique people or physical devices. WhatsApp message ID prefixes provide the estimate: Web, Android, iPhone, iPad, macOS, Windows, wearables, AR devices or Unknown. Prefixes can be spoofed and do not verify a manufacturer, model, operating-system version or device ownership. Unknown is included in the denominator.

Search and expand a connected number to see its observed owned-device indexes, coarse reported class, estimated sending platform and last observed message. A full observed list can contain up to 25 entries. Incremental device changes make the full list stale: current membership and device count become unknown until another full list is observed. An index is not a permanent hardware identifier; last activity is an observed message, not uptime.

The API exposes these measurements under each number's deviceAnalytics, and intersecting conversation rows under conversationBreakdown. These fields and recipientActivity are included in full JSON exports and hourly analytics drains. Analytics does not retain per-recipient device identities, raw message IDs or message content.

API

cURL
curl --get "$POLYMORFA_API_URL/platform/analytics" \
  --header "Authorization: Bearer $POLYMORFA_API_KEY" \
  --data-urlencode "projectId=$PROJECT_ID" \
  --data-urlencode "sessionId=$NUMBER_ID" |
  jq '.data.numbers[].deviceAnalytics'
TypeScript
const result = await platform.analytics.get({
  projectId,
  sessionId: numberId,
  start: Date.now() - 24 * 60 * 60 * 1000,
  end: Date.now(),
});

for (const number of result.data.numbers) {
  const devices = number.deviceAnalytics;
  console.log(devices.customerPlatforms, devices.accountPlatforms);
  console.log(devices.inventory?.listCurrent);
  console.log(devices.inventory?.devices);
}

customerPlatforms counts incoming direct messages by estimated sending client, and accountPlatforms counts direct messages your account sent. Each row has platform, messages and a nullable share. Each number's inventory holds the observed owned-device indexes with their estimated platform, reported class, nullable last message time and nullable list membership; the combined summary has inventory: null. listCurrent: false makes deviceCount and each device's listed value null, and truncated reports an incomplete list. measured, complete and observedBuckets describe coverage; missing measurements are null, not zero.

A recipient's linked devices #

Analytics keeps no per-recipient device list. To see one recipient's linked devices now, call Get user devices with contacts:read on a connected Linked Devices number. The contact ID is the phone number with country code, digits only.

API

cURL
curl "https://api.polymorfa.com/messaging/$SESSION/contacts/5511999999999/devices" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"
TypeScript
const devices = await messaging.contacts.devices(numberId, "5511999999999");
for (const device of devices.data.data) {
  console.log(device.device);
}

This is a live lookup; it creates no retained device directory. A device index does not establish a platform, model, ownership or hardware identity. Keep your application's person-level retention separate from the aggregate Analytics measurements.

Phone, Polymorfa and customer activity#

Response operations compares messages and replies observed from the primary phone, other linked devices and Polymorfa in a table beside the response timeline. It also shows the primary phone's average response time and last observed activity. Polymorfa's reply time starts at the newest unanswered direct message and ends with a successful send; failed sends do not count as replies.

A primary-phone active period starts with a signal after at least 15 minutes without an observed signal. This measures activity evidence, not phone power cycles, continuous uptime or verified offline state. Unobserved activity remains unknown.

Avg phone activity span measures the time from the first to the last signal in completed activity periods. A single-signal span has a duration of zero. Avg gap without phone activity measures completed gaps of at least 15 minutes between successive signals. The view shows the sample count for each average; open intervals and restarts do not enter these averages. Choose Phone intervals to graph the averages over time. A completed span is booked when it closes; a gap is booked when the next signal arrives. A period can therefore include intervals that started before the selected range.

The JSON API exposes completedPhoneActivityPeriods, phoneActivityMs, averagePhoneActivityMs, phoneQuietGaps, phoneQuietMs and averagePhoneQuietMs in accountActivity. Series rows include duration sums and sample counts so you can compute weighted averages across numbers.

Awaiting your reply and Longest wait are a snapshot of tracked direct chats at the last measurement. They are not sums of historical snapshots, and they are bounded to the observed chat window. The timestamp tells you how old the snapshot is.

Customer online, offline and typing counts come from existing presence subscriptions. Analytics does not subscribe to every customer or infer their availability when signals are missing. The activity chart can compare message activity, phone versus Polymorfa replies, customer online versus typing signals, or answered versus unanswered calls. Selecting a number filters activity, engagement, call details and the chart. The number table keeps the numbers in the project scope available for comparison.

Calls#

Call outcomes shows recorded calls, answer rate, missed incoming calls and failures. Incoming and outgoing rows compare volume, answer rate, average pickup time, median call length and total talk time. Select Call history to inspect individual records. The number filter also applies to call summaries and the UTC daily call chart.

Answer rate is answered calls divided by all recorded calls except those still ringing. Talk time excludes ringing. Length statistics include answered calls with recorded durations; pickup time includes calls with a recorded answer timestamp. The API returns the timing observation counts, average, median and 95th percentile. Answered under 10 seconds counts short calls with a known duration; it does not infer a failed sale.

The follow-up rate counts missed incoming calls followed by an answered outgoing call to the same matched contact on the same number within 24 hours. Its denominator contains only missed calls with a known contact match and a complete 24-hour window. Pending windows and missing contact matches are shown separately. A follow-up can occur after the selected period ends. This is an observed call sequence, not proof of callback intent or a business conversion.

Expand Audio and connection details for reported media and app measurements, call end reasons, app errors, connection transports, video calls and calls with multiple app participants. Quality fields remain unknown when measurements are absent. App quality uses the latest cumulative report per connection; delay and audio timing variation are averaged per call before the overall average. Packet-loss rate uses lost and received packets reported together. Error and transport counts are distinct calls per category and can overlap. App participant counts do not describe the customer's WhatsApp devices.

Call counts cover retained records attributed to the original number and project, including recorded Official API calls. Recreated numbers do not inherit old calls because they share a name. Deleted numbers, test numbers and calls without an original owner are excluded. Calls made outside Polymorfa are not inferred. Existing call history and retention settings remain separate from Analytics.

API examples and collector setup#

Select the Analytics API button beside the date picker for HTTP examples. The examples use the selected project, number and date range. They read analytics; the team's enable setting remains an owner or admin action in the Console.

Open the … menu and select Connect a collector to copy a syntax-highlighted OpenTelemetry configuration for the selected project and number. Choose a rolling window of 1, 24 or 168 hours and whether to include message and audience breakdowns. The collector window is independent of the calendar range on the page. Mount your API key in the collector; the Console does not collect or save that key. See collector setup for backend configuration and metric definitions.

Read analytics through the API#

The Console API button appears after an enabled Analytics read succeeds and hides while that read refreshes or fails.

Use API Read team analytics with a key that has sessions:read. A team key reads its team, or one project with projectId. A project credential stays inside its project. The project-specific route is API Read project analytics.

API

cURL
curl --get "$POLYMORFA_API_URL/platform/analytics" \
  --header "Authorization: Bearer $POLYMORFA_API_KEY" \
  --data-urlencode "projectId=$PROJECT_ID" \
  --data-urlencode "start=1790812800000" \
  --data-urlencode "end=1790985600000"
TypeScript
const end = Date.now();
const { data } = await platform.analytics.get({
  projectId: "22222222-2222-4222-8222-222222222222",
  start: end - 24 * 60 * 60 * 1_000,
  end,
});

if (!data.enabled) {
  console.log("Analytics is off");
} else {
  console.log(data.summary?.engagement.readRate, data.summary?.engagement.replyRate);
  console.log(data.summary?.calls.directions.inbound.missed);
}

TypeScript:

analytics.get is typed in @polymorfa/sdk 0.1.0-dev.20261004011426 and later. Installing the SDK does not turn on collection or grant access.

Recompute the timestamps on each read for a rolling window. A client bound to a project with a project token uses the project route and rejects a different projectId. Invalid UUIDs and date ranges throw PolymorfaValidationError before any request is sent.

Optional sessionId is the Number record UUID, not its name or phone number. start and end are Unix milliseconds. When you omit them, the API defaults to the previous 30 days. The maximum is 366 days. Activity uses whole hourly measurement buckets whose start is at or after start and before end; partial hours are not prorated. Daily series use UTC. Conversation results belong to the bucket where their completed window is recorded, rather than their first-send date.

The response's data contains:

  • enabled and period;
  • requestVitals with recorded authenticated API/MCP requests, failures and error rate for the selected team or project; a number filter does not narrow these request totals;
  • summary with aggregate activity, number coverage and engagement;
  • numbers with the same metrics for each number and its present connection status and project;
  • series with activity, phone replies, phone interval sums and sample counts, customer activity and connection counts for each number. Buckets are hourly for ranges up to 48 hours and daily for longer ranges, in UTC;
  • calls inside the summary and each number, with direction breakdowns, timing observation counts, reported quality, failure categories and missed-call follow-up;
  • callSeries with daily call outcomes and timings for each number, grouped by call start time in UTC. Call start selection uses the exact requested timestamps.

Disabled responses have summary: null, numbers: [], series: [] and callSeries: []. measured, observedHours and lastObservedAt identify messaging telemetry coverage; they do not describe call-record coverage. Engagement includes the completed conversation denominator, receipt and reply counts, nullable rates, and dropped conversation, record and receipt-join counts. Do not replace null rates with zero.

The API error rate counts failures in authenticated requests that were recorded for the selected scope. Rejections before team identity is established are not included. Connection status is a present snapshot independent of the dates. Each number's status is its session status, such as CONNECTED. summary.connectedNumbers counts numbers whose status is CONNECTED. The Console labels CONNECTED and DISCONNECTED as Connected and Disconnected and shows other statuses as reported.

Each summary and number includes messageAnalysis.segments, customerActivity, accountActivity and responseQueue. Segment rows return counts, shares, nullable rates, rate differences and 95% intervals. messageAnalysis.complete identifies metadata coverage; unknown categories and missing coverage must not be treated as measured zeros. The queue includes its own observation time and coverage flag.

Use the team API reference or project API reference for all response fields. The CLI command reads the same aggregates.

Connect a collector#

Use the collector metrics export to read engagement, connection and call gauges with Prometheus or OpenTelemetry. It uses the same Analytics enablement and project/number scopes.

Send analytics to your endpoint#

Open Project Settings → Drains to manage log and analytics destinations together. Select Add drain → Analytics, or open Analytics drains in the Analytics … menu. Choose all numbers in the project or one number, a rolling window, and a public HTTPS endpoint. See analytics drain setup for the payload and delivery behavior.

See the product overview for a visual introduction.