docs: Add Stats Table documentation to Reporting & Dashboard

docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md

@@ -0,0 +1,138 @@
+# 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 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.
+
+**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.
+
+---
+
+### `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.
+
+---
+
+
+## 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.