POST /api/notifications/send Send a personalized notification using a template. Supports realtime delivery to a single user or batch delivery to up to 10,000 targets.

​
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 ID. Provide either key or id.
​
template.variables
object
Key-value pairs matching the template’s variableSchema. All declared variables must be supplied.
​
template.notificationPushData
object
Optional push notification payload overrides.
​
targets
string[]
required
Array of user IDs to receive the notification. Realtime mode allows 1 target; batch mode allows up to 10,000.
​
mode
string
required
Delivery mode. One of realtime or batch.
​
title
string
Optional notification title for tracking and display.
​
tag
string
Optional tag for categorizing and filtering notifications.

​
Example request

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": "order-confirmation",
      "variables": {
        "customerName": "Jane",
        "orderId": "ORD-12345"
      }
    },
    "targets": ["user-jane-123"],
    "mode": "realtime",
    "title": "Order Confirmed",
    "tag": "orders"
  }'

​
Example response

{
  "notificationId": "notif_abc123",
  "templateKey": "order-confirmation",
  "channels": ["in_app", "push"],
  "mode": "realtime",
  "title": "Order Confirmed",
  "tag": "orders",
  "sentFrom": "api",
  "createdAt": "2024-01-15T09:30:00.000Z"
}

​
Response fields

​
notificationId
string
Unique identifier for the sent notification.
​
templateKey
string
The template key used for this notification.
​
channels
string[]
Array of channel types the notification was delivered through.
​
mode
string
The delivery mode used (realtime or batch).
​
title
string
The notification title.
​
tag
string
The notification tag.
​
sentFrom
string
Origin of the send request (e.g., api).
​
createdAt
string
ISO 8601 timestamp of when the notification was created.

​
Error codes

CodeDescription
ERR_BAD_REQUESTInvalid request body or missing required fields
ERR_TEMPLATE_NOT_APPROVEDTemplate is not in approved status
ERR_INVALID_VARIABLESMissing or invalid variables for the template schema
ERR_TARGET_LIMIT_EXCEEDEDToo many targets for the selected mode
ERR_INVALID_MODEMode must be realtime or batch