ab-ecosystem-cpass 1.0.6 → 1.0.8

package/docs/audience/canned-replies.md

@@ -0,0 +1,302 @@
+# Canned replies
+
+`crm.cannedReplies` — `/v1/audience/canned-replies`
+
+Message payloads an agent sends into a chat without retyping them. The panel
+offers them when an agent types `/` followed by the reply's name.
+
+Two kinds, and the difference is who gets the last word:
+
+- **`CANNED`** — every message the reply holds is sent exactly as stored, in
+  order, the moment it is picked. A three-message reply puts three messages on
+  the contact's phone from one keystroke.
+- **`QUICK`** — the reply's text lands in the agent's composer to edit before
+  sending. Exactly one message, of type `text`: there is one composer, and
+  nowhere in it to put a second message or an image.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/canned-replies` | `canned_replies:read` |
+| [`get`](#get) | `GET /v1/audience/canned-replies/:reply` | `canned_replies:read` |
+| [`create`](#create) | `POST /v1/audience/canned-replies` | `canned_replies:write` |
+| [`update`](#update) | `PATCH /v1/audience/canned-replies/:reply` | `canned_replies:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/canned-replies/:reply` | `canned_replies:write` |
+
+## Addressing a reply: `:reply` is an id **or** a name
+
+A 24-hex-character path segment is read as an **id**; anything else as a
+**name**. Names are unique per account, which is what makes addressing by the
+name an agent typed safe — and it is the only identifier the panel has at the
+moment of picking one.
+
+There is no fallback between the two. A 24-hex id that no longer exists is a
+`404`, never a name lookup, so a request for a deleted reply cannot quietly match
+a different one that happened to be named after its id. The one real ambiguity is
+a reply *named* 24 hex characters: it would be read as an id and 404. Rename it.
+
+## The reply object
+
+```ts
+interface CannedReply {
+  id: string;
+  name: string;                      // unique per account; what the agent types after `/`
+  type: 'CANNED' | 'QUICK';
+  channel: 'whatsapp' | 'sms' | 'email' | 'rcs' | 'webchat';
+  messages: CannedReplyMessage[];
+  createdAt: string;                 // ISO
+  updatedAt: string;                 // ISO
+}
+```
+
+`channel` is a channel **type**, never a channel id, so one reply works across
+every number on the account. `whatsapp` is the only value the panel offers today,
+and the reason is `whatsapp_api` below: a stored message is a literal WhatsApp
+Cloud API message object, so a reply is only sendable on a channel that speaks
+that shape.
+
+`messages` comes back in full from **every** endpoint, `list` included. It is the
+entire point of the record, and a picker that had to fetch each reply before it
+could show what the reply says would make one request per keystroke.
+
+## The message object
+
+```ts
+interface CannedReplyMessageV2 {
+  version: '2';
+  whatsapp_api: MessageContent;      // the payload as the provider takes it
+  internal?: Record<string, unknown>; // the editor's working copy; never read by the server
+}
+```
+
+`whatsapp_api` is the same object `crm.inbox.messages.send()` accepts as
+`content`. That is the point: picking a reply *is* sending its payloads, with no
+translation step in between.
+
+```json
+{ "version": "2",
+  "whatsapp_api": { "type": "text", "text": { "body": "Hi!", "preview_url": false } } }
+```
+
+```json
+{ "version": "2",
+  "whatsapp_api": { "type": "image", "image": { "link": "https://...", "caption": "Our menu" } } }
+```
+
+```json
+{ "version": "2",
+  "whatsapp_api": { "type": "interactive", "interactive": {
+      "type": "button",
+      "body": { "text": "Pick one" },
+      "action": { "buttons": [ { "type": "reply", "reply": { "id": "btn_0", "title": "Yes" } } ] } } } }
+```
+
+`internal` is the form state a composer needs to **reopen** the message for
+editing — which media type was chosen, whether the upload was still local, the
+button rows before they were flattened into an action. Stored and returned
+verbatim, never read by the server. It is optional: a reply created through the
+API without one is valid, and an editor just opens it in whatever state it can
+infer from `whatsapp_api`.
+
+### Variables are not substituted here
+
+`{{first_name}}` and friends are stored **literally**. Substitution happens at
+the moment of sending, against the contact in front of the agent — there is no
+contact when a reply is written, so there is nothing here to substitute against.
+
+### Reading older rows
+
+Rows written by the previous editor are still in the collection and carry a
+different shape entirely: a flat `type` plus a `components` array in template
+form. They come back exactly as stored, because synthesising a `whatsapp_api` for
+them would mean inventing a payload nobody approved.
+
+Narrow before you read:
+
+```ts
+for (const message of reply.messages) {
+  if (message.version === '2') {
+    send(message.whatsapp_api);
+  } else {
+    // A v1 row. Render it read-only, or ask the user to re-save the reply.
+  }
+}
+```
+
+New writes are v2 only — there is no way to create a v1 row through this API.
+
+---
+
+## list
+
+```ts
+crm.cannedReplies.list(query?: Partial<ListCannedRepliesQuery>): Promise<Paginated<CannedReply>>
+```
+
+`GET /v1/audience/canned-replies` · `canned_replies:read` · **200**
+
+Offset paginated, newest first.
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the **name**, case-insensitively, anywhere in it. The term is escaped, so `(` and `.` are searched for rather than compiled. |
+| `type` | `'CANNED' \| 'QUICK'` | — | — |
+| `channel` | channel **type** | — | e.g. `whatsapp`. Not a channel id. |
+
+```ts
+// What the chat panel asks for: the replies usable on the open chat's channel.
+const { data } = await crm.cannedReplies.list({ channel: 'whatsapp', rows: 100 });
+```
+
+To count without fetching, ask for one row and read the total:
+
+```ts
+const { pagination } = await crm.cannedReplies.list({ rows: 1 });
+pagination.total; // how many replies the account has
+```
+
+> There is no `isListing` flag. Legacy had one, and all it dropped from the
+> response was `createdAt` and `updatedAt` — it kept `messages`, the only field
+> in the record with any weight.
+
+---
+
+## get
+
+```ts
+crm.cannedReplies.get(ref: string): Promise<CannedReply>
+```
+
+`GET /v1/audience/canned-replies/:reply` · `canned_replies:read` · **200**
+
+`ref` is an id or a name — see [addressing](#addressing-a-reply-reply-is-an-id-or-a-name).
+
+`404 not_found` if the reply is not the caller's.
+
+```ts
+const reply = await crm.cannedReplies.get('price list');
+```
+
+---
+
+## create
+
+```ts
+crm.cannedReplies.create(input: CreateCannedReplyInput): Promise<CannedReply>
+```
+
+`POST /v1/audience/canned-replies` · `canned_replies:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes | — | Trimmed, 1–120 chars. Unique per account. |
+| `type` | `'CANNED' \| 'QUICK'` | yes | — | — |
+| `channel` | channel type | no | `'whatsapp'` | — |
+| `messages` | `CannedReplyMessageInput[]` | yes | — | 1–10 entries. See [the message object](#the-message-object). |
+
+`messages[].version` defaults to `'2'` and is the only accepted value;
+`messages[].whatsapp_api` is required; `messages[].internal` is optional.
+
+```ts
+const reply = await crm.cannedReplies.create({
+  name: 'price list',
+  type: 'CANNED',
+  channel: 'whatsapp',
+  messages: [
+    { version: '2', whatsapp_api: { type: 'text', text: { body: 'Here you go' } } },
+    { version: '2', whatsapp_api: {
+        type: 'document',
+        document: { link: 'https://.../prices.pdf', filename: 'prices.pdf' } } },
+  ],
+});
+```
+
+### Errors
+
+| Status | Code | When |
+| --- | --- | --- |
+| 409 | `conflict` | The name is already used on this account. |
+| 422 | `invalid_canned_reply` | A `QUICK` reply holds more than one message, or one that is not `text`. |
+| 422 | `validation_failed` | `messages` is empty or longer than 10; a message has no `whatsapp_api.type`; `name` is blank. |
+
+The `QUICK` rule is enforced here because legacy did not: it stored a `QUICK`
+reply holding an image happily, and the panel then refused to use it forever —
+the only explanation being a toast at the moment an agent reached for it.
+
+---
+
+## update
+
+```ts
+crm.cannedReplies.update(ref: string, input: UpdateCannedReplyInput): Promise<CannedReply>
+```
+
+`PATCH /v1/audience/canned-replies/:reply` · `canned_replies:write` · **200**
+
+`ref` is an id or a name. The body is any subset of `create`'s.
+
+`messages` is replaced **whole**, never merged: a reply is an ordered sequence,
+and there is no sensible way to patch element two of a list whose length is also
+changing. Send the array you want stored.
+
+Renaming works. It silently did not in legacy, whose update built its `$set` from
+`messages` alone and discarded every other field — while still *requiring* `type`
+and `channel` in the request it then ignored.
+
+An empty body is a no-op and returns the reply as it stands.
+
+### Errors
+
+| Status | Code | When |
+| --- | --- | --- |
+| 404 | `not_found` | No such reply on this account. |
+| 409 | `conflict` | A rename into a name that is already used. |
+| 422 | `invalid_canned_reply` | The **merged** result breaks the `QUICK` rule. |
+
+That last one is checked against the merge, so flipping a three-message reply to
+`QUICK` is refused — while renaming one that *already* breaks the rule is not.
+The check runs only when the patch touches `type` or `messages`: a rename alone
+leaves a reply exactly as valid as it already was, and running the rule
+regardless would make a v1 row unrenameable, punishing existing data for a rule
+introduced after it was written.
+
+```ts
+await crm.cannedReplies.update('price list', {
+  messages: [{ version: '2', whatsapp_api: { type: 'text', text: { body: 'Updated prices attached' } } }],
+});
+```
+
+---
+
+## delete
+
+```ts
+crm.cannedReplies.delete(ref: string): Promise<void>
+```
+
+`DELETE /v1/audience/canned-replies/:reply` · `canned_replies:write` · **204**, no body.
+
+`ref` is an id or a name. `404 not_found` if the reply is not the caller's.
+
+Nothing else holds a reference to a canned reply — a sent message is a message
+row, with its own copy of the content — so a delete leaves nothing dangling.
+
+---
+
+## Events
+
+Each write publishes one, for panels that cache the list:
+
+| Event | Payload |
+| --- | --- |
+| `canned_reply.created` | the full `CannedReply` |
+| `canned_reply.updated` | the full `CannedReply` |
+| `canned_reply.deleted` | `{ id, name }` |
+
+The delete carries the **name** as well as the id, because a panel caching
+replies by name — which is how an agent picks them — has no id to evict by.

package/docs/audience/notifications.md

@@ -261,3 +261,102 @@ if (Notification.permission === 'granted') {
 
 That also repairs the two cases a stored flag gets wrong: a rotated token, and a
 row pruned for staleness.
+
+---
+
+## What a device actually receives
+
+Subscribing is only half the story. This is what arrives, so a frontend can
+render it and an app can deep-link from it.
+
+Today one thing notifies: **a message on a chat the device's owner is
+responsible for.** The payload is FCM's, with the application's own keys under
+`data`:
+
+```json
+{
+  "notification": { "title": "Priya", "body": "Is this still available?" },
+  "data": {
+    "chat": "68f1c2a39b4e5d6f70812345",
+    "action_title": "View In Chat Panel",
+    "link": "https://app.acme.com/products/crmv2/chat/68f1c2a39b4e5d6f70812345",
+    "click_action": "https://app.acme.com/products/crmv2/chat/68f1c2a39b4e5d6f70812345",
+    "icon": "https://cdn.acme.com/push-192.png",
+    "badge": "https://cdn.acme.com/push-192.png"
+  },
+  "webpush": {
+    "notification": { "icon": "https://cdn.acme.com/push-192.png" },
+    "fcmOptions": { "link": "https://app.acme.com/products/crmv2/chat/68f1c2a39b4e5d6f70812345" }
+  }
+}
+```
+
+| Key | What it is |
+| --- | --- |
+| `notification.title` | Who wrote — the contact's first name, or `New User`. Not the agency's sender name, which is what every other notification would use. |
+| `notification.body` | The message text, cut to 180 characters. A non-text message is named by its type instead: `Image Message`, `Location Message`. |
+| `data.chat` | The chat id. The same id the inbox endpoints take. |
+| `data.click_action` | **Web:** the absolute panel URL. **Android/iOS:** the bare chat id, because an app resolves a record rather than opening a URL. |
+| `data.link` | Always the absolute URL, on every platform, so a native client can open the panel if it would rather. |
+| `data.image` | An image message's media URL, for a preview. Absent otherwise. |
+| `data.icon`, `data.badge` | The agency's notification icon, for a client drawing the notification itself. |
+| `webpush.fcmOptions.link` | What a **browser** opens on click. This is the mechanism, not `click_action`. |
+
+The host in every URL is the one configured for that device's surface, so the
+same notification deep-links to `app.acme.com` for one reseller's user and
+`portal.other.com` for another's.
+
+### Which messages notify
+
+| The message | Notifies |
+| --- | --- |
+| A contact wrote in | yes |
+| Somebody replied from the WhatsApp Business app | yes |
+| An agent replied from the panel | no |
+| A bot replied | no |
+| A campaign sent | no |
+| An API send | no |
+| A delivery receipt moved to delivered or read | no |
+
+A tick changing on a screen is not worth interrupting anyone for, and nobody
+needs telling about a message they just sent themselves.
+
+### Who it reaches
+
+The chat's **assigned agent**, or the **account owner** while it is unassigned
+— one person, not the team. An unassigned chat belongs to whoever is minding
+the queue.
+
+There is no presence check: an agent with the conversation open on screen still
+gets the push on their phone. That is the behaviour the panel has always had, and
+changing it is a product decision rather than a detail of delivery.
+
+### Rendering it in a browser
+
+If the payload carries a `notification` block, FCM displays it and opens
+`webpush.fcmOptions.link` on click with no code from you — which is the
+default worth keeping. A service worker that wants to draw its own instead
+should read the `data` keys above:
+
+```js
+messaging.onBackgroundMessage((payload) => {
+  self.registration.showNotification(payload.notification.title, {
+    body: payload.notification.body,
+    icon: payload.data.icon,
+    image: payload.data.image,
+    data: { url: payload.data.link },
+  });
+});
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+  event.waitUntil(clients.openWindow(event.notification.data.url));
+});
+```
+
+Two things to know if you are porting the existing worker. A notification FCM
+displayed itself nests the payload under `notification.data.FCM_MSG`, so reading
+`event.notification.data.click_action` off it finds nothing — take the link
+from your own `showNotification` call, as above. And `localStorage` does not
+exist in a service worker: a gate written against it throws, and the handler
+around it never runs.

package/docs/campaign/campaign-messages.md

@@ -0,0 +1,282 @@
+# Campaign messages (reporting)
+
+`crm.campaignMessages` — `/v1/campaigns/:id/report`
+
+What actually happened to each message a campaign sent. One row per attempted
+send: who it went to, how far it got, what came back, and why it failed.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`stats`](#stats) | `GET /v1/campaigns/:id/report` | `campaigns:read` |
+| [`list`](#list) | `GET /v1/campaigns/:id/report/messages` | `campaigns:read` |
+| [`iterate`](#iterate) | the same, paged for you | `campaigns:read` |
+| [`replies`](#replies) | `GET /v1/campaigns/:id/report/replies` | `campaigns:read` |
+
+## The campaign is the path
+
+A report has no meaning without a campaign, so it is addressed as the campaign's
+own sub-resource rather than as a collection of rows that a campaign filters.
+Every method takes the id first, and the options object holds only what
+*narrows* a report that already exists — a message index, a status, a page.
+
+```ts
+await crm.campaignMessages.stats(campaignId);
+await crm.campaignMessages.list(campaignId, { status: 'failed' });
+```
+
+## Where these numbers come from
+
+The campaign manager writes one row as it hands each message to a channel. The
+channel's delivery webhooks — processed **outside the CRM** — then move that
+row's `status` forward as the message is delivered, read and replied to.
+
+So reporting is a **read of those rows, counted when you ask**. There is no
+report collection, no roll-up job, and nothing to regenerate: no `generatedAt` to
+reason about, and no window in which a stored number is quietly wrong because a
+webhook has arrived but the roll-up has not run.
+
+The flip side is that a campaign still going out has moving numbers. Reading
+`stats` seconds after launch under-counts everything, and that is the truth
+rather than a lag.
+
+Nothing in this module writes. There is no endpoint to correct a status: the
+service that owns the lifecycle is the one receiving the webhooks.
+
+## The funnel
+
+`status` is a **single field holding the furthest stage reached** — not a set of
+flags. A row at `read` is also delivered and sent; a row at `replied` is all
+three. So the counts nest:
+
+```
+replied  ⊆  read  ⊆  delivered  ⊆  sent        failed ∥ (outside the funnel)
+```
+
+Which means:
+
+- **Cumulative by default.** `delivered` is everything that got at least as far
+  as delivered — the number a "delivered" tile shows.
+- **Subtract for a stage's own count.** `delivered - read` is "delivered but
+  unread"; `read - replied` is "read but silent".
+- **`failed` is never inside `sent`.** A failed message was never sent anywhere;
+  it is counted on its own.
+- **There is no `queued`.** A row exists only once a send has been attempted, so
+  "waiting to go out" is not a state this collection can have. The campaign's own
+  `status` is where that lives.
+
+`total` counts every row, failures included, and is the number of attempted
+sends.
+
+## The row
+
+```ts
+interface CampaignMessageRecord {
+  id: string;             // the row's own id — what a `selection` retarget takes
+  campaignId: string;
+  messageIndex: number;   // which message of the campaign, zero-based
+  providerMessageId: string; // '' when the send failed
+  channelId: string;
+  contactId: string;      // the recipient's contact id
+  identifier: string;     // the destination: a WhatsApp number, a Telegram id…
+  name: string;           // '' when the contact had no name
+  status: 'sent' | 'delivered' | 'read' | 'replied' | 'failed';
+  sentAt?: string;        // set per stage reached, absent for stages not reached
+  deliveredAt?: string;
+  readAt?: string;
+  repliedAt?: string;
+  failedAt?: string;
+  reply: string;          // '' unless replied
+  replyType: string;      // 'text', 'button', … '' unless replied
+  repliedIn: number;      // seconds between the send and the reply; 0 unless replied
+  error?: string;         // failed rows only
+  createdAt: string;      // when the send was attempted
+}
+```
+
+`id` is worth singling out: it is the handle a **`selection` retarget** campaign
+takes. Collect the ids of the rows you want and the campaign manager resolves
+them back to recipients, which is how "re-send to everyone who did not read it"
+is built.
+
+`CampaignMessageRecord` is not `CampaignMessage`, despite the names. A
+`CampaignMessage` is one of the messages a campaign is *defined* to send — a
+channel, a payload, its polls. A `CampaignMessageRecord` is a record of one of
+those having gone to one person, and there is one per recipient per message.
+
+---
+
+## stats
+
+```ts
+crm.campaignMessages.stats(campaign: string, query?: CampaignMessageStatsQuery): Promise<CampaignMessageStats>
+```
+
+`GET /v1/campaigns/:id/report` · `campaigns:read` · **200**
+
+### Query
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `message` | number | no | One message of a multi-message campaign, zero-based. Omit for the whole campaign. |
+
+```ts
+const overall = await crm.campaignMessages.stats(campaign);
+// { total: 12480, sent: 12410, delivered: 11980, read: 7420, replied: 310, failed: 70 }
+
+const second = await crm.campaignMessages.stats(campaign, { message: 1 });
+```
+
+**No date window**, deliberately. A campaign is a single send — its rows are
+written over the minutes it takes to go out and then only change state — so "the
+campaign's whole life" is the only window that means anything. A repeating
+campaign's runs are separate campaigns, each with its own id.
+
+One aggregation, not five counts. Legacy issued a `countDocuments` per stage,
+which is five passes for numbers that all come from one grouping, and could
+return a `read` higher than its own `delivered` when a webhook landed between
+two of the passes.
+
+`404 not_found` when the campaign is not the caller's — the same answer as a
+campaign that does not exist, so the error cannot be used to probe whether
+someone else's id is real.
+
+---
+
+## list
+
+```ts
+crm.campaignMessages.list(campaign: string, query?: ListCampaignMessagesQuery): Promise<Paginated<CampaignMessageRecord>>
+```
+
+`GET /v1/campaigns/:id/report/messages` · `campaigns:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `message` | number | — | Zero-based index of one campaign message. |
+| `status` | `sent` `delivered` `read` `replied` `failed` | — | Cumulative; see below. Omit for every row. |
+| `exact` | boolean | `false` | Only rows sitting at `status` right now. |
+| `identifier` | string | — | Exact match on one recipient. Not a search. |
+| `reply_type` | string | — | Replied rows only; refused otherwise. |
+| `replied_within_hours` | number | — | Replied rows only; refused otherwise. |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+
+```ts
+// the two queries a report screen actually makes
+const failures = await crm.campaignMessages.list(campaign, { status: 'failed', rows: 100 });
+failures.data[0].error; // why that one did not go
+
+const unread = await crm.campaignMessages.list(campaign, { status: 'delivered', exact: true });
+unread.pagination.total; // equals stats.delivered - stats.read
+```
+
+### `status` and `exact`
+
+`status` filters **cumulatively**, so a drill-down returns exactly the rows the
+matching stat counted: `status: 'delivered'` gives you the `delivered` number's
+rows. `exact: true` switches to the single stage — "delivered but never read" —
+which is the drill-down for `delivered - read`.
+
+`exact` has no effect without `status`, and none on `failed`, which has nothing
+beyond it.
+
+### Reply filters
+
+`reply_type` and `replied_within_hours` are **refused** with
+`422 validation_failed` unless `status` is `replied`. They cannot match anything
+on a non-replied row, and a filter that cannot match is a caller mistake worth
+reporting rather than an empty page.
+
+`replied_within_hours: 2` means the reply arrived within two hours of the send —
+useful for separating people who answered immediately from people who came back
+the next day.
+
+### Ordering
+
+Newest attempt first, by when the row was **written**, not by a stage timestamp.
+Sorting on `deliveredAt` would reorder the list as webhooks arrive, and offset
+paging over a list that reorders itself skips and repeats rows.
+
+---
+
+## iterate
+
+```ts
+crm.campaignMessages.iterate(campaign: string, query?: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>
+```
+
+Every matching row, paged through for you. **This is what an export is** — there
+is no export endpoint, nothing to queue, nothing to poll, and no generated file
+that expires before someone downloads it.
+
+```ts
+for await (const row of crm.campaignMessages.iterate(campaign)) {
+  csv.write([row.identifier, row.name, row.status, row.error ?? '']);
+}
+```
+
+Pages at 100 rows unless you pass `rows` — the server's maximum, and so the
+fewest round trips. A million recipients is ten thousand requests, so run an
+export that size somewhere with low latency to the gateway rather than from a
+browser tab.
+
+The collection is live. Rows are written while a campaign goes out and statuses
+change under an export that takes minutes, and offset paging over moving data can
+repeat or miss a row. For a stable snapshot, export after the campaign completes.
+
+---
+
+## replies
+
+```ts
+crm.campaignMessages.replies(campaign: string, query?: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>
+```
+
+`GET /v1/campaigns/:id/report/replies` · `campaigns:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `message` | number | — | Zero-based index of one campaign message. |
+| `limit` | number | `50` | Distinct replies to return, 1–200. |
+
+```ts
+const { groups, replied, distinct } = await crm.campaignMessages.replies(campaign);
+
+groups;   // [{ reply: 'Yes', replyType: 'button', count: 182 }, { reply: 'No', … }]
+replied;  // 310 — every replied row, whether or not its group is listed
+distinct; // 4   — distinct replies in total
+```
+
+What a poll or a button message is sent to find out. Grouped on the reply **and**
+its type, so a tapped `Yes` and a typed `Yes` stay apart — they say different
+things about how engaged the recipient was. Most common first, ties broken by the
+reply text so the order is stable between reads.
+
+`distinct` against `groups.length` tells you whether the breakdown is complete.
+A campaign that asked an open question has as many groups as it has repliers, so
+a truncated answer there is normal rather than a problem — raise `limit`, or
+treat the tail as "other".
+
+---
+
+## Operational note: the index this needs
+
+Every read here matches on the campaign first, and the collection — which belongs
+to the campaign manager — declares no index on it. Without one, each report is a
+scan of every campaign message ever sent:
+
+```js
+db.newcampaignmessages.createIndex(
+  { cid: 1, cmid: 1, status: 1 },
+  { name: 'Campaign Report', background: true },
+);
+```
+
+One compound index serves all three reads. This service deliberately does **not**
+create it: building an index on a multi-million row collection owned by another
+service, as a side effect of a process starting, is not something that should
+happen by accident.