cometchat · aaryan-rawat · May 25, 2026 · May 26, 2026 · May 26, 2026
diff --git a/campaigns-apis.json b/campaigns-apis.json
diff --git a/campaigns.mdx b/campaigns.mdx
@@ -0,0 +1,86 @@
+---
+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.
+- **Run scheduled and batch campaigns** — Send to a handful of users immediately or to tens of thousands through batch and CSV-driven flows.
+- **Track delivery and engagement** — Capture delivered, read, clicked, and interacted signals for analytics and unread counts.
+- **Administer the in-app feed** — Soft-delete feed items, audit per-user delivery, and manage retention.
+
+## 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 → Set status to "Approved".
+  </Step>
+  <Step title="Send a Notification">
+    Either via Dashboard (Create a Campaign → Select template → Add recipients → Send Now) or via API (`POST /notifications/messages`).
+  </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 notification (realtime) | 10 |
+| Recipients per notification (batch) | 10,000 |
+| Pagination page size | Max 100 |
+| Max campaigns | No hard limit |
+| Max templates | No hard limit |
+
+## 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/overview">
+    Create and manage targeted notification campaigns
+  </Card>
+</CardGroup>
diff --git a/campaigns/analytics.mdx b/campaigns/analytics.mdx
@@ -0,0 +1,60 @@
+---
+title: "Analytics"
+description: "Track notification delivery and engagement metrics across campaigns, templates, channels, and users."
+---
+
+The Campaigns analytics surface gives you visibility into how notifications perform after they leave the system. Metrics are available in the Dashboard and through the analytics API, broken down by three primary dimensions.
+
+### Dimensions
+
+#### Campaigns
+
+Track delivery and engagement at the campaign level. Useful for comparing the performance of different sends, A/B testing subject lines, or evaluating whether a scheduled campaign hit its target audience.
+
+#### Templates
+
+Measure how a specific template performs across all sends that use it. Since every notification flows through a template, this is the most granular content-level view. Compare open rates between an "order shipped" template and a "weekly digest" template to understand which content resonates.
+
+#### Channels
+
+Evaluate per-channel effectiveness. If your app uses both in-app and push, the channel dimension shows which channel drives more engagement and where delivery failures concentrate.
+
+#### Tags
+
+Group notifications by any free-form label set on the template (`transactional`, `launch`, `re-engagement`, team or campaign cohort). Tags cut across templates and channels, so they're the right dimension when you want a marketing-style rollup without forcing one template per cohort.
+
+### Metrics tracked
+
+| Metric       | Description                                                                 |
+| ------------ | --------------------------------------------------------------------------- |
+| Requested    | Notifications dispatched to the delivery layer for this channel.            |
+| Delivered    | Confirmed delivered to the user (device acknowledgement or feed write).     |
+| Viewed       | User scrolled the item into view or opened the notification.                |
+| Clicked      | User tapped a CTA or link within the notification.                          |
+| Interacted   | User performed a custom interaction (e.g. dismissed, snoozed, replied).     |
+| Failed       | Delivery failed (provider error, invalid token, user not reachable).        |
+
+### Per-user insights
+
+You can also query engagement at the individual user level. This returns aggregate counts for a specific user over a date range:
+
+- Total viewed, clicked, and interacted counts.
+- Last engagement timestamp.
+
+This is useful for building user-level health scores, identifying disengaged users, or powering re-engagement logic in your backend.
+
+### Filtering
+
+All analytics queries support:
+
+- **Date range.** Specify `startDate` and `endDate` to scope the window.
+- **Period.** Choose `hourly` or `daily` granularity for time-series data.
+
+### Multi-device deduplication
+
+When a user receives or interacts with a notification on multiple devices, the same event is deduplicated and counted once. For example, if a push notification is delivered to both a phone and a tablet, it counts as a single delivery in the analytics.
+
+### Where to access
+
+- **Dashboard.** Navigate to Campaigns > Analytics for visual charts and drill-downs.
+- **API.** Programmatic access to the same data via the analytics endpoints is part of the admin API surface (rolling out separately). For now, use the Dashboard for visual reports.
diff --git a/campaigns/campaigns.mdx b/campaigns/campaigns.mdx
@@ -0,0 +1,101 @@
+---
+title: "Campaigns"
+sidebarTitle: "Campaigns"
+description: "Create, schedule, and manage targeted notification campaigns for batch user delivery."
+---
+
+A campaign is a batch notification send to a targeted list of users. Campaigns provide scheduling, delivery tracking, and lifecycle management on top of the core notification send.
+
+## Campaign vs Direct Notification
+
+| | Campaign | Direct Notification |
+|-|----------|-------------------|
+| Entry point | Dashboard wizard | API: `POST /notifications/messages` |
+| Recipients | CSV upload, User picker | `receivers` array in request body |
+| Scheduling | Immediate or scheduled | Always immediate |
+| Tracking | Full lifecycle (status, sent/failed counts) | Notification row created, no campaign-level tracking |
+| Sequences | Supported (multi-step) | Not supported |
+
+## 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 (Unix timestamp) |
+| Recurring | Not supported |
+
+<Note>
+You can click "Send Now" on a scheduled campaign to override the schedule and send immediately.
+</Note>
+
+## Campaign Status Flow
+
+```mermaid
+flowchart LR
+    A[draft] --> B[sending]
+    A --> C[scheduled]
+    C --> B
+    C --> D[cancelled]
+    B --> E[completed]
+    B --> F[failed]
+    B --> G[partially_failed]
+```
+
+| 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.
+- **Pause** — Not supported. Once sending starts, it runs to completion.
+- **Delete** — Only draft campaigns can be deleted. Cancelled campaigns cannot be deleted.
+
+## Campaign Properties
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Campaign name |
+| `templateId` | string | Template CUID |
+| `templateVersion` | number | Pinned template version |
+| `status` | enum | `draft` \| `scheduled` \| `sending` \| `completed` \| `failed` \| `partially_failed` \| `cancelled` |
+| `scheduledAt` | number | Unix timestamp (null for immediate) |
+| `totalTargets` | number | Total recipients |
+| `sentCount` | number | Successfully delivered |
+| `failedCount` | number | Failed deliveries |
+| `tag` | string | Optional analytics tag |
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max recipients per campaign | 10,000 |
+| Max concurrent campaigns | No hard limit |
+| Max campaigns per app | No hard limit |
diff --git a/campaigns/categories.mdx b/campaigns/categories.mdx
@@ -0,0 +1,52 @@
+---
+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.
+
+## How Categories Work
+
+```mermaid
+flowchart LR
+    A[Category] --> B[Template]
+    B --> C[Feed Item]
+    C --> D[User Feed filtered by category]
+```
+
+- A template has a `templateCategory` field (category name)
+- Feed items inherit `templateCategory` and `categoryId` from the template
+- The feed API supports filtering: `GET /notification-feed?category=Marketing`
+- The `categoryFilterEnabled` flag on the template channel controls whether filtering is active
+
+## 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:
+
+```
+GET /notification-feed?category=Marketing
+```
+
+This only works when `categoryFilterEnabled` is set to `true` on the template's channel configuration.
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max categories per app | No hard limit |
+| Duplicate names | Not allowed (returns 409 error) |
diff --git a/campaigns/channels.mdx b/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
+4. Click **Save**
+
+## 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 |
+
+<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 |