From 9a7d2ca52a9d20eb092840491bceb3850dc0ce2c Mon Sep 17 00:00:00 2001 From: Shijith Karumathil Date: Thu, 11 Jun 2026 17:18:15 +0530 Subject: [PATCH 1/4] docs: add Stats Table documentation to Reporting & Dashboard Co-Authored-By: Claude Sonnet 4.6 --- .../09. Understanding the Stats Table.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md diff --git a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md new file mode 100644 index 000000000..fc4c0d1d4 --- /dev/null +++ b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md @@ -0,0 +1,147 @@ +# Understanding the Stats Table in Glific + +The Stats table is Glific's built-in analytics system. It automatically records activity data for your organisation across different time windows so you can track how your bot is performing over time. + +--- + +## Time Periods + +Every stat record belongs to one of five time periods. The same metrics are calculated for each period independently. + +| Period | What it covers | +|---|---| +| **Hour** | A single hour of activity | +| **Day** | A full calendar day (midnight to midnight) | +| **Week** | A full calendar week (Monday to Sunday) | +| **Month** | A full calendar month | +| **Summary** | A special snapshot generated at the end of each week and month — it covers the entire week or month in one calculation and is the most reliable figure to use for reporting | + +> **Recommendation**: Always use the **Summary** period for reporting to stakeholders. It is calculated in a single pass and avoids the inconsistencies that can appear when comparing daily rows. + +--- + +## Fields + +### `contacts` + +**What it means**: The number of new contacts who were added to your organisation during this period. + +**How it is calculated**: Counts contacts whose creation date falls within the time window. A contact who joined on December 3rd will appear in the December 3rd daily stat, the December weekly stat, and the December monthly stat. + +**What to watch for**: This is a count of *new* additions only, not your total contact base. The Summary period is an exception — it returns your all-time total contact count. + +--- + +### `active` + +**What it means**: The number of contacts who had any message exchange during this period — whether they sent a message to the bot or the bot sent a message to them. + +**How it is calculated**: Counts contacts whose "last messaged at" date falls within the time window. + +**Important limitation**: A contact's "last messaged at" date is always updated to their most recent interaction. This means if a contact was active on December 1st but also sent a message on December 15th, they will no longer appear in the December 1st daily count. Historical daily active counts therefore decrease over time and should not be used for retrospective reporting. The monthly or summary figure is far more stable. + +--- + +### `optin` + +**What it means**: Among the contacts who were active during this period, how many have opted in to receive messages from your organisation. + +**How it is calculated**: Takes the set of active contacts for the period (same as the `active` count) and filters down to those who have an opt-in recorded at any point in the past. + +**Critical clarification — this is not "who opted in this period"**: This field does not tell you how many people opted in during this specific time window. It tells you how many of the *currently active* contacts have ever opted in. If you want to know how many contacts opted in during a specific month, the contacts table needs to be queried directly. This is also the most likely reason for discrepancies if you have been cross-checking opt-in numbers. + +--- + +### `optout` + +**What it means**: Among the contacts who were active during this period, how many have opted out. + +**How it is calculated**: Same approach as `optin` — takes the active contacts and filters to those who have an opt-out recorded at any point in the past. + +**Same caveat as optin**: This is not "who opted out this period." It is the overlap between active contacts and contacts who have ever opted out. + +--- + +### `messages` + +**What it means**: The total number of messages sent and received during this period, across both directions. + +**How it is calculated**: Counts all message records (inbound + outbound) created within the time window. + +--- + +### `inbound` + +**What it means**: The number of messages sent *to* the bot by contacts during this period. + +**How it is calculated**: Counts only messages where the flow direction is inbound (contact → bot). + +**Use case**: This is the closest proxy to genuine user engagement — a contact actively chose to send a message. + +--- + +### `outbound` + +**What it means**: The number of messages sent *from* the bot to contacts during this period. + +**How it is calculated**: Counts only messages where the flow direction is outbound (bot → contact). + +--- + +### `hsm` + +**What it means**: The number of template messages sent during this period. HSM stands for Highly Structured Message, which is WhatsApp's term for pre-approved message templates. + +**How it is calculated**: Counts outbound messages that are marked as HSM/template messages. + +**Why this matters**: Template messages have a cost associated with them and are used to initiate conversations outside the 24-hour session window. Tracking this helps monitor your messaging costs. + +--- + +### `flows_started` + +**What it means**: The number of times a flow (automated conversation sequence) was triggered during this period. + +**How it is calculated**: Counts flow sessions that were created within the time window. One contact going through a flow counts as one flow started, even if they send multiple messages within it. + +--- + +### `flows_completed` + +**What it means**: The number of flows that were completed (reached the end) during this period. + +**How it is calculated**: Counts flow sessions whose completion timestamp falls within the time window. + +**Use case**: Comparing `flows_started` to `flows_completed` gives you a drop-off rate — the percentage of contacts who started a flow but did not finish it. + +--- + +### `users` + +**What it means**: The number of Glific staff/agent users (not contacts) who logged in during this period. + +**How it is calculated**: Counts Glific user accounts whose last login falls within the time window. For the Summary period, it returns the total number of user accounts registered. + +**Note**: This tracks your organisation's internal team activity, not the contacts using your bot. + +--- + +### `conversations` + +**What it means**: The number of billable conversation sessions opened during this period, as recorded by the WhatsApp Business API. + +**How it is calculated**: Counts conversation billing records created within the time window. WhatsApp counts a "conversation" as a 24-hour messaging window between the bot and a contact. + +**Why this matters**: This is directly tied to your WhatsApp API billing. One contact might generate multiple conversation records if they interact with the bot across multiple days. + +--- + +## Common Pitfalls + +1. **Do not use daily `active` counts for historical reporting.** They are revised downward as contacts continue to message after that date. Use monthly or summary figures instead. + +2. **The `optin` and `optout` columns are not cohort counts.** They do not tell you who opted in or out during that period. They tell you which active contacts have an opt-in or opt-out on record. + +3. **Weekly and daily figures may not add up perfectly.** Each is calculated independently, so small differences are expected. The Summary figure is always the authoritative number for a given period. + +4. **`messages` = `inbound` + `outbound` (approximately).** There may be a small difference due to system-generated messages, but these three fields should roughly balance. From 529e01405b1a9a21f254617399f52900fa3c3fe0 Mon Sep 17 00:00:00 2001 From: Shijith Karumathil Date: Thu, 11 Jun 2026 17:23:14 +0530 Subject: [PATCH 2/4] docs: clarify active count as contacts who messaged the bot Co-Authored-By: Claude Sonnet 4.6 --- .../09. Understanding the Stats Table.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md index fc4c0d1d4..036ee17ce 100644 --- a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md +++ b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md @@ -34,7 +34,7 @@ Every stat record belongs to one of five time periods. The same metrics are calc ### `active` -**What it means**: The number of contacts who had any message exchange during this period — whether they sent a message to the bot or the bot sent a message to them. +**What it means**: The number of contacts who sent a message to the bot during this period. **How it is calculated**: Counts contacts whose "last messaged at" date falls within the time window. From a47bd0b42b8e36362ca60884813ea6dbb0a1ac90 Mon Sep 17 00:00:00 2001 From: Shijith Karumathil Date: Thu, 11 Jun 2026 17:27:04 +0530 Subject: [PATCH 3/4] docs: remove conversations field from Stats Table documentation Co-Authored-By: Claude Sonnet 4.6 --- .../09. Understanding the Stats Table.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md index 036ee17ce..f05b3dfe5 100644 --- a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md +++ b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md @@ -126,15 +126,6 @@ Every stat record belongs to one of five time periods. The same metrics are calc --- -### `conversations` - -**What it means**: The number of billable conversation sessions opened during this period, as recorded by the WhatsApp Business API. - -**How it is calculated**: Counts conversation billing records created within the time window. WhatsApp counts a "conversation" as a 24-hour messaging window between the bot and a contact. - -**Why this matters**: This is directly tied to your WhatsApp API billing. One contact might generate multiple conversation records if they interact with the bot across multiple days. - ---- ## Common Pitfalls From 842f208259e277afa33b5fb049514a1714803c27 Mon Sep 17 00:00:00 2001 From: Shijith Karumathil Date: Thu, 11 Jun 2026 17:31:49 +0530 Subject: [PATCH 4/4] docs: clean up Stats Table documentation Co-Authored-By: Claude Sonnet 4.6 --- .../09. Understanding the Stats Table.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md index f05b3dfe5..2348a25c2 100644 --- a/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md +++ b/docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md @@ -38,7 +38,7 @@ Every stat record belongs to one of five time periods. The same metrics are calc **How it is calculated**: Counts contacts whose "last messaged at" date falls within the time window. -**Important limitation**: A contact's "last messaged at" date is always updated to their most recent interaction. This means if a contact was active on December 1st but also sent a message on December 15th, they will no longer appear in the December 1st daily count. Historical daily active counts therefore decrease over time and should not be used for retrospective reporting. The monthly or summary figure is far more stable. +**Important limitation**: A contact's "last messaged at" date is always updated to their most recent interaction. This means if a contact was active on December 1st but also sent a message on December 15th, they will no longer appear in the December 1st daily count. ---