POST /api/notifications/send Batch notifications deliver messages to multiple users in one request. Set mode to batch and provide up to 10,000 user IDs in the targets array. Each user can receive personalized content through per-user template variables.
This uses the same endpoint as realtime notifications. The difference is mode: "batch" and multiple targets.

​
How does batch delivery work?

  1. You send a single request with up to 10,000 target user IDs
  2. The platform validates the template and per-user variables
  3. The response returns immediately with a notificationId (fire-and-forget)
  4. Delivery happens asynchronously — messages are queued and processed in batches
  5. Track delivery status through the Analytics API
Batch mode has a maximum of 10,000 inline targets. For larger audiences (up to 100,000 users), use the CSV upload flow instead.

​
Headers

​
appid
string
required
Your CometChat App ID.
​
apikey
string
required
Your CometChat API Key.

​
Request body

​
template
object
required
Template configuration for the notification.
​
template.key
string
The template key (slug). Provide either key or id.
​
template.id
string
The template MongoDB ObjectId. Provide either key or id.
​
template.variables
object
Per-user variables keyed by user ID. Each user ID maps to an object of variable key-value pairs matching the template’s variableSchema.
​
template.notificationPushData
object
Optional custom key-value pairs included in push notification payloads.
​
targets
string[]
required
Array of user IDs to receive the notification. Minimum 1, maximum 10,000 for batch mode.
​
mode
string
required
Must be batch for batch delivery.
​
title
string
Optional label for organizing and tracking this notification.
​
tag
string
Optional grouping key for analytics categorization.

​
How do per-user variables work in batch mode?

Each target user can receive different content by providing user-specific variable values. The template.variables object is keyed by user ID: 
{
  "template": {
    "key": "appointment-reminder",
    "variables": {
      "user_1": {
        "name": "Bob",
        "appointment_number": "32893"
      },
      "user_2": {
        "name": "Alice",
        "appointment_number": "44521"
      },
      "user_3": {
        "name": "Charlie",
        "appointment_number": "55102"
      }
    }
  },
  "targets": ["user_1", "user_2", "user_3"],
  "mode": "batch"
}
The platform substitutes {{name}} and {{appointment_number}} placeholders in the template content with each user’s specific values before delivery.
If a user ID appears in targets but not in template.variables, the notification is sent with unsubstituted template content. If a required variable is missing for a user, that user’s delivery fails but other users still receive their notifications.

​
What variable types are supported?

TypeValue formatExample
stringPlain text"name": "Bob"
imageObject with url, width, height"photo": { "url": "https://...", "width": 100, "height": 100 }
actionObject with type and data"cta": { "type": "web", "data": "https://example.com/view" }
See Template Variables for details on defining variable schemas.

​
Example request — batch with per-user variables

curl -X POST https://{appId}.api-{region}.cometchat.io/v3/business-messaging/api/notifications/send \
  -H "appid: YOUR_APP_ID" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "key": "appointment-reminder",
      "variables": {
        "user_1": {
          "name": "Bob",
          "appointment_number": "32893",
          "photo": { "url": "https://example.com/bob.jpg", "width": 100, "height": 100 },
          "cta": { "type": "web", "data": "https://example.com/appointments/32893" }
        },
        "user_2": {
          "name": "Alice",
          "appointment_number": "44521",
          "photo": { "url": "https://example.com/alice.jpg", "width": 100, "height": 100 },
          "cta": { "type": "web", "data": "https://example.com/appointments/44521" }
        }
      }
    },
    "targets": ["user_1", "user_2"],
    "mode": "batch",
    "title": "Appointment Reminder",
    "tag": "appointments"
  }'

​
Example request — batch without variables

curl -X POST https://{appId}.api-{region}.cometchat.io/v3/business-messaging/api/notifications/send \
  -H "appid: YOUR_APP_ID" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "key": "system-maintenance-notice"
    },
    "targets": ["user_1", "user_2", "user_3", "user_4", "user_5"],
    "mode": "batch",
    "title": "Scheduled Maintenance",
    "tag": "system"
  }'

​
Example response

{
  "notificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "templateKey": "appointment-reminder",
  "channels": [
    { "key": "in-app-alerts", "type": "in_app" },
    { "key": "mobile-push", "type": "push" }
  ],
  "mode": "batch",
  "title": "Appointment Reminder",
  "tag": "appointments",
  "sentFrom": { "type": "api", "value": "****abcd" },
  "createdAt": "2026-04-15T10:30:00.000Z"
}
The response returns immediately after the batch is queued. Actual delivery happens asynchronously. Use the Analytics API to track delivery, view, and click metrics.

​
Response fields

​
notificationId
string
Unique identifier for tracking this batch notification.
​
templateKey
string
The template key used.
​
channels
array
Array of channel objects with key and type showing which delivery channels were used.
​
mode
string
Always batch for batch notifications.
​
sentFrom
object
Origin info with type (always api) and value (masked API key).
​
createdAt
string
ISO 8601 timestamp when the notification was created.

​
Error codes

CodeHTTPDescription
ERR_BAD_REQUEST400Missing required fields or invalid body
ERR_TEMPLATE_NOT_APPROVED409Template must be in approved status
ERR_INVALID_VARIABLES400Per-user variables don’t match template schema
ERR_TARGET_LIMIT_EXCEEDED400More than 10,000 targets in batch mode
ERR_INVALID_MODE400Mode must be realtime or batch
ERR_NO_CHANNELS400Template has no enabled channels

​
What are the limits?

ConstraintLimit
Inline targets (batch mode)10,000 users
Inline targets (realtime mode)1 user
CSV upload targets100,000 users
For audiences larger than 10,000, use the CSV upload flow.