docs(campaigns): Campaigns REST API public docs

campaigns.mdx

@@ -0,0 +1,81 @@
+---
+title: "Overview"
+sidebarTitle: "Overview"
+description: "Send transactional notifications, run scheduled campaigns, and manage the per-user in-app feed across in-app and push channels."
+---
+
+CometChat Campaigns is a notification management system that lets you design, target, and deliver in-app and push notifications to your users. It provides a visual dashboard for creating notification templates, managing delivery channels, and sending targeted campaigns — either immediately or on a schedule. Your backend can also send notifications programmatically via API.
+
+## Key Capabilities
+
+- **Send transactional notifications** — Deliver a templated message to one or many users in real time, with per-recipient variable resolution.
+- **Organise content with templates** — Author reusable templates with typed variables, categories, and tags. Every notification flows through a template.
+- **Immediate and scheduled campaigns** — Send notifications right away or schedule them for a future date and time.
+- **Track delivery and engagement** — Capture delivered, read, clicked, and interacted signals for analytics and unread counts.
+
+## Supported Channels
+
+| Channel | Description |
+|---------|-------------|
+| `in_app` | In-app notification feed rendered client-side via SDK |
+| `push` | Push notifications delivered via FCM/APNs through CometChat's push infrastructure |
+
+## Setup Flow
+
+The typical setup to send your first notification:
+
+<Steps>
+  <Step title="Create a Channel">
+    Go to Channels → Create Channel → Select type (`in_app` or `push`) → Name it → Save.
+  </Step>
+  <Step title="Create a Category (optional)">
+    Go to Categories → Create → Name it (e.g., "Marketing", "Alerts").
+  </Step>
+  <Step title="Create a Template">
+    Go to Templates → Create Template → Enter name → Select channel(s) → Design content in the visual builder.
+  </Step>
+  <Step title="Send a Notification">
+    Either via Dashboard (Create a Campaign → Select template → Add recipients → Send Now) or via [Send Notification API](/rest-api/campaigns-apis/notifications/send-notification).
+  </Step>
+</Steps>
+
+## Prerequisites
+
+- A CometChat app with `appId` and `apiKey`
+- At least one enabled channel created
+- At least one approved template
+- Users registered in CometChat (targeted by their UID)
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Recipients per API call | 10,000 |
+
+## Common Use Cases
+
+### Transactional alerts
+Order shipped, payment receipt, password reset, security alert. One templated message per event, dispatched in real time, with per-recipient variable substitution (`{{order_id}}`, `{{user_name}}`).
+
+### Marketing campaigns
+Product launches, promotional offers, re-engagement nudges. Schedule the send, upload a recipient list, and deliver across in-app and push channels.
+
+### Operational messages
+Maintenance windows, policy updates, account changes. Dispatched to a broad audience and routed through the in-app feed so users can revisit them.
+
+## Quick Navigation
+
+<CardGroup cols={2}>
+  <Card title="Channels" icon="tower-broadcast" href="/campaigns/channels">
+    Configure delivery channels for in-app and push notifications
+  </Card>
+  <Card title="Categories" icon="folder" href="/campaigns/categories">
+    Organize notifications with categories for filtering
+  </Card>
+  <Card title="Templates" icon="file-lines" href="/campaigns/templates">
+    Create reusable notification templates with variables and versioning
+  </Card>
+  <Card title="Campaigns" icon="paper-plane" href="/campaigns/campaigns">
+    Create and manage targeted notification campaigns
+  </Card>
+</CardGroup>

campaigns/analytics.mdx

@@ -0,0 +1,41 @@
+---
+title: "Analytics"
+description: "Track notification delivery and engagement metrics from the Campaigns dashboard."
+---
+
+The Analytics page gives you a snapshot of how your notifications are performing — how many were delivered, read, and engaged with.
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| Delivered | Total notifications confirmed delivered |
+| Read | Total feed items marked as read |
+| Engagement | Total interactions (interacted events) |
+
+## Engagement Funnel
+
+A visual breakdown showing the progression from sent to engaged:
+
+- **Sent** — total notifications dispatched
+- **Delivered** — as a percentage of sent
+- **Read** — as a percentage of sent
+- **Engagement** — as a percentage of sent
+
+## Recent Campaigns
+
+A table showing your most recent campaigns. Clicking a campaign row opens the campaign details page.
+
+## Campaign Details
+
+Shows per-campaign metrics: sent, delivered, read, and interacted breakdown for a specific campaign.
+
+## Template Details
+
+Available from the templates list under analytics. Shows how a specific template performs across all sends that use it.
+
+## Per-User Engagement
+
+Per-user engagement data is not on this page — it's available on the individual User Detail page.
+
+For programmatic access to analytics data, see the [Analytics API](/rest-api/campaigns-apis/analytics/overview-metrics).

campaigns/campaigns.mdx

@@ -0,0 +1,63 @@
+---
+title: "Campaigns"
+sidebarTitle: "Campaigns"
+description: "Create, schedule, and manage targeted notification campaigns for batch user delivery."
+---
+
+A campaign lets you send notifications to a targeted group of users using a pre-designed template. You select recipients, choose a template, personalize content with variables, and either send immediately or schedule for later. The dashboard tracks delivery progress and shows how many notifications were sent, delivered, and failed.
+
+## Creating a Campaign
+
+The dashboard wizard walks you through four steps:
+
+<Steps>
+  <Step title="Recipients">
+    Choose your input mode:
+    - **CSV** — Upload a file with a `user_id` column and optional variable columns
+    - **User picker** — Select from the Users list
+  </Step>
+  <Step title="Select Template">
+    Pick an approved template. The template determines the content and delivery channels.
+  </Step>
+  <Step title="Compose">
+    Enter campaign name, set per-user variables, and add an optional analytics tag.
+  </Step>
+  <Step title="Review & Send">
+    Review the summary. Choose **Send Now** or **Schedule** for a future date/time.
+  </Step>
+</Steps>
+
+## Scheduling
+
+| Option | Description |
+|--------|-------------|
+| Send Now | Immediate dispatch |
+| Schedule | Set a future date/time |
+
+<Note>
+You can click "Send Now" on a scheduled campaign to override the schedule and send immediately.
+</Note>
+
+## Campaign Status Flow
+
+| Status | Description |
+|--------|-------------|
+| `draft` | Campaign created but not yet sent or scheduled |
+| `scheduled` | Queued for future delivery |
+| `sending` | Currently dispatching to recipients |
+| `completed` | All recipients processed successfully |
+| `failed` | All recipients failed |
+| `partially_failed` | Some recipients succeeded, some failed |
+| `cancelled` | Cancelled before send time |
+
+## Cancel and Delete
+
+- **Cancel** — Cancels a scheduled or draft campaign. Cannot cancel once `sending` has started.
+- **Delete** — Only draft campaigns can be deleted.
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Recipients per API call | 10,000 |
+

campaigns/categories.mdx

@@ -0,0 +1,28 @@
+---
+title: "Categories"
+sidebarTitle: "Categories"
+description: "Organize notifications with categories for filtering and user-facing feed segmentation."
+---
+
+Categories are labels used to organize templates and filter notification feed items. When a template has a category assigned, all notifications sent with that template carry the category — allowing end-users to filter their feed by category.
+
+## Managing Categories
+
+1. Go to **Categories** in the sidebar
+2. **Create** — Click "Create Category" → Enter name and optional description → Save
+3. **Edit** — Click a category → Update name or description → Save
+4. **Delete** — Click delete → Confirm removal
+
+## Category Properties
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Category name (unique per app) |
+| `description` | string | Optional description |
+
+## Feed Filtering
+
+End-users can filter their notification feed by category using the SDK or feed API. See [List Feed](/rest-api/campaigns-apis/notification-feed/list-feed) for the full API reference.
+
+This only works when `categoryFilterEnabled` is set to `true` on the template's channel configuration.
+

campaigns/channels.mdx

@@ -0,0 +1,52 @@
+---
+title: "Channels"
+sidebarTitle: "Channels"
+description: "Configure delivery channels for your campaign notifications — in-app feed and push notifications."
+---
+
+Channels define where notifications are delivered. Each template references one or more channel instances, and each channel instance is tied to a specific delivery type.
+
+## Supported Channel Types
+
+| Type | Description |
+|------|-------------|
+| `in_app` | Feed notifications rendered by SDK |
+| `push` | Lock-screen notifications via FCM/APNs |
+
+## Creating a Channel
+
+1. Go to **Channels** → Click **Create Channel**
+2. Select the channel type (`in_app` or `push`)
+3. Configure the channel:
+   - **Name** — Display name (e.g., "Default Feed", "Promotions Feed")
+   - **Channel ID** — Auto-generated slug: `cc-notification-channel-<name>` (immutable after creation)
+   - **Enabled** — Toggle on/off (defaults to disabled)
+4. Click **Create Channel**
+
+## Channel Properties
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name |
+| `channelId` | string | Unique slug (immutable after creation) |
+| `type` | enum | `in_app` \| `push` |
+| `enabled` | boolean | Whether channel is available for template assignment (defaults to `false`) |
+
+<Note>
+Push notification configuration (FCM/APNs keys) is managed at the CometChat app level, not per-channel in Campaigns.
+</Note>
+
+## Multiple Channels
+
+You can create multiple `in_app` channels. For example:
+- "Promotions Feed" (`in_app`) — for marketing notifications
+- "Alerts Feed" (`in_app`) — for transactional alerts
+
+Push channels are limited to one per app. Templates reference a specific channel instance by its `channelId`.
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| `in_app` channels per app | No hard limit |
+| `push` channels per app | 1 |

campaigns/notification-settings.mdx

@@ -0,0 +1,13 @@
+---
+title: "Notification Settings"
+sidebarTitle: "Notification Settings"
+description: "Configure push notification providers for delivering campaign notifications."
+---
+
+The Notification Settings page lets you configure push notification providers (FCM, APNs, Custom) for your app. These credentials are required to deliver push notifications through campaigns.
+
+For detailed setup instructions, provider configuration, and credential management, visit the Push Notifications documentation.
+
+<Card title="Push Notifications Setup" icon="bell" href="/notifications/push-overview">
+  Configure FCM, APNs, and custom push providers
+</Card>

campaigns/sequences.mdx

@@ -0,0 +1,49 @@
+---
+title: "Sequences"
+description: "Control the order and timing of notifications across channels with channel sequencing."
+---
+
+Sequences let you define the order in which notification channels fire and the conditions that stop the sequence early. Instead of broadcasting the same message across all channels simultaneously, you deliver in a prioritised chain where each step waits for a result before deciding whether to proceed.
+
+### Why use sequences
+
+- **Improve deliverability.** Target the channel most likely to reach the user based on their prior engagement pattern.
+- **Avoid notification fatigue.** Stop the chain as soon as the user has seen or acted on the message, rather than hitting them on every channel.
+
+### How it works
+
+Sequences are configured at the template level. When you create or edit a template in the Dashboard:
+
+1. Add two or more channels to the template.
+2. Enable the **Sequence** toggle in the template settings.
+3. Arrange the channels in the desired delivery order. The first channel fires immediately at send time.
+4. For each subsequent step, configure:
+   - **Stop condition.** The engagement signal that halts the sequence. Available conditions depend on the channel:
+     - **In-app:** `delivered` | `read` | `engaged`
+     - **Push:** `delivered` | `clicked`
+   - **Wait window.** How long to wait for the stop condition before moving to the next step: 5, 10, 30, 60, 240, or 1440 minutes.
+
+If the stop condition is met within the wait window, the remaining steps are skipped. If the window expires without the condition being met, the next channel fires.
+
+### Example
+
+A template with two channels configured as a sequence:
+
+| Step | Channel  | Stop condition | Wait   |
+| ---- | -------- | -------------- | ------ |
+| 1    | In-app   | delivered      | 30 min |
+| 2    | Push     | n/a            | n/a    |
+
+At send time, the in-app notification is dispatched immediately. If the item is marked delivered within 30 minutes, the sequence stops and push is never sent. If 30 minutes pass without a delivery signal, push fires as a fallback.
+
+### Metrics
+
+When a template uses sequencing, per-step delivery metrics are available through the Dashboard and the analytics API. Which metrics are reported depends on the channel:
+
+| Channel  | Requested | Delivered | Clicked |
+| -------- | :-------: | :-------: | :-----: |
+| In-app   | ✓         | ✓         | ✓       |
+| Push     | ✓         | ✓         | ✓       |
+
+These metrics help you evaluate whether your sequence order and wait windows are tuned correctly, and where users are dropping off.
+