Bulk Template Message API Documentation — v2

This API allows you to send template messages to multiple recipients simultaneously through the WhatsApp channel.

Message delivery is processed asynchronously; the API request immediately returns a bulkOperationId, while messages are queued and processed in the background.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/send.js

Response format

Every endpoint in this document is a custom function. The HTTP response body carries the function's own fields (_id, title, pathString…) and the endpoint's actual response under result. The response examples in this document show the content of result:

{
  "_id": "function_id",
  "title": "Show",
  "pathString": "/bulk-message-api-app/api/v2/bulk-operation/show.js",
  "result": {
    "bulkOperation": { "_id": "abc123xyz789", "status": "running" }
  }
}

Migrating from v1

v2 runs side by side with v1, so you can migrate on your own schedule. The v1 endpoints (/api/bulk-message/…, /api/bulk-message-records/…) will be retired; new integrations should use v2.

Move the endpoint paths to v2: …/api/bulk-message/… becomes …/api/v2/bulk-operation/…, and …/api/bulk-message-records/… becomes …/api/v2/bulk-operation-items/…. The send request body does not change; a single request now takes up to 100,000 recipients instead of 5,000.
Send bulkOperationId instead of bulkMessageId in requests.
Replace stats.js with show.js.
Read the responses with the new field names in the table below.

The v2 endpoints only know bulk operations created with the v2 send. To track a bulk message created with v1 before you switched, keep using the v1 endpoints for it.

Endpoints

v1	v2	What changes in the response
`bulk-message/send.js`	`v2/bulk-operation/send.js`	`{ bulkMessageId }` becomes `{ bulkOperationId }`
`bulk-message/stats.js`	`v2/bulk-operation/show.js`	`{ bulkMessage, stats }` becomes `{ bulkOperation }`
`bulk-message/message-stats.js`	`v2/bulk-operation/message-stats.js`	The counters are at the root instead of under `messageStats`
`bulk-message/stop.js`	`v2/bulk-operation/stop.js`	Nothing
`bulk-message-records/list.js`	`v2/bulk-operation-items/list.js`	`bulkMessageRecords` becomes `bulkOperationItems`
`bulk-message-records/list-with-messages.js`	`v2/bulk-operation-items/list-with-messages.js`	Same as `list`, and each item also carries `session`

Field names

v1	v2
`stats.success`	`bulkOperation.progress.succeeded`
`stats.pending`, `stats.failed`, `stats.cancelled`, `stats.total`	`bulkOperation.progress.pending`, `.failed`, `.cancelled`, `.total`
—	`bulkOperation.progress.unknown`, `bulkOperation.status`, `bulkOperation.result.outcome`
`bulkMessage` (bulk message)	`bulkOperation` (bulk operation)
`bulkMessageRecord` (record)	`bulkOperationItem` (item)
`bulkMessageId` in requests, in the `send` response and on records	`bulkOperationId`
record `username` / `userId` / `sessionId` as sent	`payload.username` / `payload.userId` / `payload.sessionId`
record `referenceId`	`payload.referenceId`
record `payload` (the recipient's template payload)	`payload.payload`
record `userId`, `sessionId`, `messageId` after sending	`result.userId`, `result.sessionId`, `result.messageId`
record status `success`	`succeeded`
record `errorMessage` on failed records	`error.message`, next to `error.code` and `error.retryable`
—	`position` (the recipient's index in `recipients`)
filter `{"status": "success"}`	`{"status": "succeeded"}`
filter `{"referenceId": "…"}`	`{"payload.referenceId": "…"}`
`send` errors `schema-error`, `invalidRequest`	`zod-schema-error`, with the path of the invalid field in the message

Key Features

Send bulk template messages to 1–100,000 recipients in a single request
Personalized variables for each recipient (HEADER, BODY, BUTTONS, CAROUSEL)
Shared defaultPayload for all recipients with recipient-specific payload merging (isMerge)
Scheduled delivery (scheduleAt)
Specify recipients using username (phone number), userId, or sessionId
Send multiple messages to the same user within a single bulk request
Optional referenceId for tracking records with external systems
Automatically assign conversations to a user or workgroup after sending (action)

warning

This API can only send templates that have been approved by Meta.

The template name and language code must exactly match the template registered in Meta Business Manager.

Request Parameters

Top-Level Parameters

Parameter	Type	Required	Description
`channelUsername`	string	Yes	WhatsApp channel number used to send the message (e.g. `"908506669933"`)
`connectorBrand`	string	Yes	Channel connector brand. Currently supported value: `"whatsapp"`
`title`	string	No	Campaign title. Used for display in the dashboard. Default: `"-"`
`scheduleAt`	string (ISO 8601)	No	Scheduled delivery date and time (e.g. `"2026-06-10T10:00:00.000Z"`). If omitted, messages are sent immediately.
`defaultPayload`	object	Conditional*	Default template payload applied to all recipients. Required if a recipient does not provide its own `payload`.
`recipients`	array	Yes	Recipient list. Minimum 1, maximum 100,000 recipients.
`action`	object	No	Action applied to the conversation after sending. `assign-to-user` or `assign-to-workgroup`.

*If every recipient provides its own payload, defaultPayload is optional.

Recipient Structure

For each recipient, exactly one of username, userId, or sessionId must be provided. Multiple identifiers cannot be used together, and omitting all of them will result in an error.

To send multiple messages to the same user within a single bulk request, add the same identifier to the recipient list multiple times.

Field	Type	Description
`username`	string	Recipient's phone number (e.g. `"905554443322"`). If the user does not exist in the system, it is created automatically.
`userId`	string	ID of an existing user in the system.
`sessionId`	string	ID of an existing conversation session in the system.
`referenceId`	string	Optional reference ID (max 256 characters) for matching with external system records (CRM, order, ticket, etc.). Must be unique within the bulk if provided.
`payload`	object	Recipient-specific template payload (optional). If `isMerge: true`, it is merged with `defaultPayload`.
`isMerge`	boolean	Overrides merge behavior for this recipient (optional). If omitted, `defaultPayload.isMerge` is used.

Action Structure

Field	Type	Description
`action.key`	string	`"assign-to-user"` assigns the conversation to a specific agent; `"assign-to-workgroup"` assigns it to a workgroup.
`action.value`	string	ID of the target user or workgroup.

Template Payload Structure

defaultPayload and recipient-specific payload share the same structure. For template messages, type: "template" must be specified.

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",
    "languageCode": "tr-TR",
    "variables": []
  },
  "isMerge": true
}

Field	Type	Required	Description
`type`	string	Yes	Payload type. For template messages: `"template"`
`template.templateName`	string	Yes*	Template name registered in Meta. Optional in recipient payloads when `isMerge: true` is used (inherits from default).
`template.languageCode`	string	No	Template language code (e.g. `"tr"`, `"en"`, `"tr-TR"`, `"en-US"`). Must exactly match the language registered in Meta.
`template.variables`	array	No	List of variables applied to template components. Detailed below.
`isMerge`	boolean	No	`true`: recipient payload is deep-merged with `defaultPayload`. `false` or omitted: recipient payload completely replaces `defaultPayload`.

isMerge Behavior

If defaultPayload.isMerge: true and the recipient provides its own payload, a deep merge is applied.
With deep merge, the recipient may provide only variables; templateName and languageCode are inherited from the default payload.
The recipient's isMerge field overrides defaultPayload.isMerge.
If a recipient does not provide a payload, defaultPayload is always used.

Variables Structure

Each item in the variables array corresponds to a template component. A component type (type) may appear only once in the array.

type	Description	parameters	cards
`"HEADER"`	Template header component. Text variable or media URL (image, video, document)	Yes	—
`"BODY"`	Template body text variables	Yes	—
`"BUTTONS"`	Dynamic URL suffix variables for buttons	Yes	—
`"CAROUSEL"`	Card components for carousel templates	—	Yes

Parameter Formats

The parameters field can be provided in three different formats:

// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }

Which format should I use?

If your Meta template uses placeholders like {{1}}, {{2}}, use either the array format or numeric-key object format.
If your template uses named placeholders such as {{firstName}} or {{orderTotal}}, use the named-key object format.
When using arrays, order matters: the first element maps to {{1}}, the second to {{2}}, and so on.

HEADER Component

Use the HEADER component when the template header contains media (image, video, document) or dynamic text.

// Media header (image URL)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// Text header variable
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

BODY Component

Used for dynamic text variables within the template body.

// Array format — when the template uses {{1}}, {{2}}, {{3}}
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Named format — when the template uses {{name}}, {{orderAmount}}
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

BUTTONS Component

Used for buttons with dynamic URL suffixes. If the template contains multiple URL buttons, only buttons with variables are indexed sequentially (buttons without variables or FLOW buttons are ignored).

// Single URL button suffix variable
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Multiple URL button suffix variables (first URL button, second URL button)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

CAROUSEL Component

For carousel templates, component variables are defined separately for each card.

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card1.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product A", "99.00 USD"]
        }
      ]
    },
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card2.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product B", "149.00 USD"]
        }
      ]
    }
  ]
}

warning

The length of the cards array must exactly match the number of cards defined in the template.

Examples

1. Simple Template — No Variables, Same Content for All Recipients

This is the simplest way to send a static template without variables to multiple recipients.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [
    { "username": "905554443301" },
    { "username": "905554443302" },
    { "username": "905554443303" }
  ]
}'

tip

Recipients specified via username are automatically created if they do not already exist in the system
All recipients use the same defaultPayload; no recipient-specific data is required
When isMerge is not specified, each recipient directly uses the defaultPayload

2. Template with Shared Body Variables

The same template is sent to all recipients using identical variable values. The template contains placeholders such as {{1}} and {{2}}.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Summer Campaign",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "promo_notification",
      "languageCode": "tr-TR",
      "variables": [
        {
          "type": "BODY",
          "parameters": ["30%", "July 31, 2026"]
        }
      ]
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}

tip

In this example, the template body might contain content such as: "Enjoy a {{1}} discount in our campaign! Offer valid until {{2}}."
parameters[0] replaces {{1}}, while parameters[1] replaces {{2}}

3. Personalized Template — Per-Recipient Variables with isMerge

Different variable values are used for each recipient. By setting isMerge: true in the defaultPayload, recipients only need to provide variables; templateName and languageCode are inherited from the default payload.

In this example, the template includes both a media header and personalized body variables.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Personal Order Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "order_confirmation",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-a.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Ahmet", "ORD-001", "150.00 TRY"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-b.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Fatma", "ORD-002", "289.00 TRY"]
            }
          ]
        }
      }
    }
  ]
}

tip

Thanks to isMerge: true, templateName does not need to be repeated in each recipient payload
Each recipient's variables array is completely independent
The header media URL must be publicly accessible
If type is omitted in the recipient payload, defaultPayload.type is inherited

4. URL Button Variable

Use the BUTTONS component when the template contains a button with a dynamic URL suffix. For example, a tracking number appended to the base URL https://example.com/track/.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Shipment Tracking Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "shipment_tracking",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Ahmet", "TK-98765"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-98765"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Recep", "TK-12345"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-12345"]
            }
          ]
        }
      }
    }
  ]
}

tip

BUTTONS parameters are matched according to the order of buttons that contain variables
FLOW buttons and buttons without variables are ignored; indexing only applies to dynamic URL buttons
If the template button URL is https://example.com/track/{{1}}, then parameters[0] replaces {{1}}

5. Scheduled Delivery

Schedule a message to be sent at a future date and time. scheduleAt must be provided as an ISO 8601 UTC timestamp.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Morning Campaign Message",
  "scheduleAt": "2026-06-10T07:00:00.000Z",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "morning_campaign",
      "languageCode": "en-US"
    },
    "isMerge": true
  },
  "action": {
    "key": "assign-to-workgroup",
    "value": "WORKGROUP_ID"
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Ahmet", "discountRate": "25" }
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Zeynep", "discountRate": "40" }
            }
          ]
        }
      }
    }
  ]
}

tip

scheduleAt must be provided in the UTC time zone (e.g., for 10:00 AM Turkey time, use 07:00:00.000Z)
This example uses the named parameter format; the template should contain placeholders such as {{name}} and {{discountRate}}
With action, conversations created by the message delivery are automatically assigned to the specified workgroup

Response

A successful request returns a bulkOperationId, which can be used to track the delivery process:

{
  "bulkOperationId": "abc123xyz789"
}

Error Responses

Status	Description
`recipients field is required`	The `recipients` field was not sent
`Channel not found`	No verified channel matching `channelUsername` and `connectorBrand` was found
`Channel is not verified`	The matched channel exists but has not yet been verified
`zod-schema-error`	A field in the request body failed schema validation (missing required field, incorrect type, unsupported value, more than one identifier on a recipient, or a missing `payload`). The message names the field, e.g. `recipients.0.referenceId: referenceId must be unique`

The returned bulkOperationId can be used with the endpoints below to query delivery statistics and stop the delivery process.

Show — Bulk Operation Status and Statistics

Retrieves the bulk operation with its current status and the delivery counters of its items, under the bulkOperation key.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/show.js

Request Parameters

Parameter	Type	Required	Description
`bulkOperationId`	string	Yes	ID of the bulk operation to track (returned from `send`)

{
  "bulkOperationId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/show.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkOperationId": "abc123xyz789"
}'

Response

{
  "bulkOperation": {
    "_id": "abc123xyz789",
    "type": "send-bulk-message",
    "slug": "my-workspace",
    "userId": "agent_user_id",
    "payload": {
      "title": "Campaign Title",
      "channelUsername": "908506669933",
      "connectorBrand": "whatsapp",
      "connectorSlug": "om2WabVegaCloud",
      "defaultLanguageCode": "tr-TR",
      "sentUser": { "firstname": "John", "lastname": "Doe" },
      "defaultPayload": {
        "type": "template",
        "template": { "templateName": "order_confirmation", "languageCode": "tr-TR" },
        "isMerge": true
      },
      "source": { "type": "recipients", "bulkOperationInputGroupId": "group_id" }
    },
    "status": "running",
    "result": { "outcome": "unknown", "hasErrors": false },
    "progress": {
      "total": 100,
      "pending": 45,
      "succeeded": 42,
      "failed": 3,
      "cancelled": 10,
      "unknown": 0
    },
    "scheduleAt": "2026-06-10T07:00:00.000Z",
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-10T07:00:30.000Z",
    "startedAt": "2026-06-10T07:00:05.000Z"
  }
}

Show Fields

The fields are under bulkOperation.

Field	Type	Description
`status`	string	Bulk operation status: `preparing`, `scheduled`, `pending`, `running`, `stopping`, `stopped`, `completed`, `failed`
`progress.total`	number	Total number of items
`progress.pending`	number	Items still waiting in the queue
`progress.succeeded`	number	Items successfully processed for delivery
`progress.failed`	number	Items that encountered a delivery error
`progress.cancelled`	number	Items cancelled by `stop`
`progress.unknown`	number	Items whose result could not be determined
`result.outcome`	string	Final outcome once the bulk operation has finished: `success`, `partial`, `all-failed`, `cancelled`, `unknown`
`result.hasErrors`	boolean	`true` if at least one item failed
`scheduleAt`	string	Scheduled delivery time (only for scheduled bulk operations)
`startedAt`, `completedAt`	string	When delivery started and finished

note

progress.succeeded indicates that the message was successfully handed off by the system. It does not guarantee that Meta delivered the message to the recipient. Subsequent status updates generated by Meta (such as delivered, read, or failed) do not affect this counter and are not reflected here.

Show vs Message Stats

show endpoint: Shows the delivery status of the items (pending, succeeded, failed, cancelled, unknown)
message-stats endpoint: Shows actual message status (pending, sending, sent, delivered, read, error, etc.)
A item may be succeeded, but the message might not yet be delivered/read

Reference ID

The referenceId is an optional field that you can use to match delivery items with an ID from your own system for tracking purposes (e.g., order number, ticket ID). It is returned on each item as payload.referenceId.

If provided, it must be unique within the bulk (max 256 characters).

Important

Not required for use
Cannot be duplicated within the same bulk operation
Can be reused across different bulk operations

Message Stats — WhatsApp Message Status

Retrieves the message status statistics for a bulk operation. Unlike the show endpoint, this shows the actual message.status of the sent messages instead of the item status.

Possible message statuses: pending, sending, sent, delivered, read, deleted, warning, error, unknown, not-sended

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/message-stats.js

Request Parameters

Parameter	Type	Required	Description
`bulkOperationId`	string	Yes	ID of the bulk operation to query

{
  "bulkOperationId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/message-stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkOperationId": "abc123xyz789"
}'

Response

{
  "pending": 5,
  "sending": 2,
  "sent": 10,
  "delivered": 45,
  "read": 30,
  "deleted": 2,
  "warning": 1,
  "error": 3,
  "unknown": 0,
  "not-sended": 2,
  "no-message": 20,
  "total": 120
}

Message Stats Fields

Field	Type	Description
`pending`	number	Messages not yet sent
`sending`	number	Messages currently being sent
`sent`	number	Messages handed to WhatsApp, not yet delivered
`delivered`	number	Messages delivered to recipient's phone
`read`	number	Messages read by the recipient
`deleted`	number	Deleted messages
`warning`	number	Messages with warnings
`error`	number	Messages with errors
`unknown`	number	Messages with unknown status
`not-sended`	number	Messages that could not be sent
`no-message`	number	Items without a message (still queued, failed or cancelled)
`total`	number	Total item count

Usage Tips

A high no-message count while the bulk operation is running indicates delivery is still in progress
delivered count shows successful message delivery
read count can be used to measure campaign engagement
You can poll this endpoint periodically for real-time tracking

Options Structure — Pagination, Filtering, and Sorting

The options parameter used in list and list-with-messages endpoints provides a standard structure for pagination, filtering, and sorting.

Options Fields

Field	Type	Required	Description
`pagination`	object	No	Pagination settings
`filtering`	object	No	Filtering criteria
`sorting`	object	No	Sorting settings (e.g., `{"position": 1}`)

Pagination Structure

If pagination is not sent, the first page is returned with up to 50 items. If it is sent, currentPage is required.

Field	Type	Default	Description
`currentPage`	number	—	Page number to retrieve (required when `pagination` is sent)
`pageItems`	number	50	Number of items per page (maximum: 50)

Filtering Structure

Filtering is done using MongoDB query format on the item fields, using the field names exactly as they appear in the response (e.g. status, payload.referenceId, result.messageId). In the list-with-messages endpoint, you can also filter by message fields (e.g., message.status).

// Filter by item status
{
  "options": {
    "filtering": {
      "status": "succeeded"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "payload.referenceId": "ORDER-12345"
    }
  }
}

// Filter by message status (only list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Filter by multiple statuses using $in (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Exclude specific statuses using $nin (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

// List items that have no message (only list-with-messages)
{
  "options": {
    "filtering": {
      "message": {
        "$exists": false
      }
    }
  }
}

Sorting Structure

Sorting is done using MongoDB sort format. 1 means ascending, -1 means descending. position is the order of the recipient in the recipients array of the request (starting from 0).

// Sort in the order the recipients were sent in the request
{
  "options": {
    "sorting": {
      "position": 1
    }
  }
}

// Sort by multiple fields
{
  "options": {
    "sorting": {
      "status": 1,
      "position": 1
    }
  }
}

Combined Usage Example

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "position": 1
    }
  }
}

This example lists the second page of delivered messages in recipient order.

Practical Tips

Combine filtering and pagination for targeted queries
Response includes options.pagination.totalCount and options.pagination.totalPages for navigation
message.status filter only works in the list-with-messages endpoint

Items — Item Details and Listing

Lists all delivery items for a bulk operation. Each item represents one entry of the recipients array.

List — Item List

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation-items/list.js

Request Parameters

Parameter	Type	Required	Description
`bulkOperationId`	string	Yes	ID of the bulk operation to list
`options`	object	No	Pagination, filtering, sorting options. See Options Structure for details.

Request — Basic Usage

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Request — Filter by Specific Status

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "failed"
    }
  }
}

Lists only failed delivery items, with the reason in error.

Response

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 0,
      "payload": {
        "username": "905554443301",
        "referenceId": "ORDER-12345",
        "payload": {
          "template": {
            "variables": [{ "type": "BODY", "parameters": ["Ahmet", "ORD-001"] }]
          }
        }
      },
      "status": "succeeded",
      "attempt": 1,
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    },
    {
      "_id": "item_2",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 1,
      "payload": { "username": "905554443302", "referenceId": "ORDER-12346" },
      "status": "failed",
      "attempt": 1,
      "error": { "code": "error", "message": "Variable missing", "retryable": false },
      "result": { "userId": "user_124", "sessionId": "session_457" },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

List With Messages — List with Message Details

Has the same features as the list endpoint (pagination, filtering, sorting). The difference: each item also carries the related message and session objects when they exist. This allows you to see the message status (delivered, read, error, etc.) and payload in a single query.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation-items/list-with-messages.js

Request — Basic Usage

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Request — Filter by Message Status

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    }
  }
}

This example fetches only messages with "delivered" status.

Request — List Failed Messages

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "error"
    }
  }
}

Used to review messages that encountered delivery errors.

Response

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "position": 0,
      "payload": { "username": "905554443301", "referenceId": "ORDER-12345" },
      "status": "succeeded",
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "message": {
        "_id": "msg_789",
        "type": "template",
        "status": "delivered",
        "payload": {
          "template": {
            "name": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z"
      },
      "session": {
        "_id": "session_456",
        "status": "opened"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

Item Fields

Field	Type	Description
`_id`	string	Item ID
`bulkOperationId`	string	Bulk operation ID this item belongs to
`position`	number	Order of the recipient in the request's `recipients` array, starting from `0`
`payload`	object	The recipient exactly as sent in the request (`username` / `userId` / `sessionId`, `referenceId`, `payload`, `isMerge`)
`status`	string	Item status: `pending`, `succeeded`, `failed`, `cancelled`, `unknown`
`error`	object	Only on `failed` items: `code`, `message` and `retryable`
`result.userId`	string	Recipient user ID
`result.sessionId`	string	Conversation session ID
`result.messageId`	string	Sent message ID (missing if no message was sent)
`completedAt`	string	When the item was processed
`message`	object	Message details (only in list-with-messages)
`session`	object	Conversation details (only in list-with-messages)

List vs List-With-Messages Comparison

Feature	list	list-with-messages
Pagination	Yes	Yes
Filtering	Yes (item fields only)	Yes (item + message fields)
Message / Session	No	Yes (if they exist)
Performance	Fast	Medium (performs JOIN)
message.status Filter	Not available	Available

Usage Scenarios

list: Quickly list all items, filter by referenceId, check item statuses
list-with-messages: View WhatsApp message statuses (delivered, read), inspect message payloads
Filtering examples:
- {"status": "failed"} — Failed delivery items
- {"payload.referenceId": "ORDER-123"} — Specific reference ID
- {"message.status": "delivered"} — Delivered messages (list-with-messages only)
- {"message.status": "read"} — Read messages (list-with-messages only)
- {"message.status": "error"} — Messages with errors (list-with-messages only)
- {"message.status": {"$in": ["delivered", "read"]}} — Messages that are either delivered or read (list-with-messages only)
- {"message.status": {"$nin": ["error", "not-sended"]}} — Messages excluding errors and not-sent (list-with-messages only)
- {"message": {"$exists": false}} — Items without a message (list-with-messages only)
- {"status": {"$in": ["succeeded", "pending"]}} — Items that are successful or pending

Performance and Usage Notes

list endpoint is faster; prefer it for general status checks
Use list-with-messages when message details are needed
Maximum items per page (pageItems) is 50; defaults to 50 if not specified
message.status filter only works in list-with-messages
Items without result.messageId have no message object

Stop — Cancel Delivery

Stops an ongoing bulk operation delivery. All pending items are moved to the cancelled status and the bulk operation becomes stopped. Items that have already been processed as succeeded or failed are not affected. A scheduled bulk operation can also be stopped before its scheduleAt time.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/stop.js

warning

This action cannot be undone. A stopped delivery cannot be resumed.

Request Parameters

Parameter	Type	Required	Description
`bulkOperationId`	string	Yes	ID of the bulk operation to stop

{
  "bulkOperationId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkOperationId": "abc123xyz789"
}'

Response

For a successful request, the response body is empty. An HTTP 200 status indicates that the operation completed successfully.

{}

tip

Only bulk operations created through this API can be stopped
After stopping a delivery, you can use the show endpoint to verify the number of cancelled items (bulkOperation.progress.cancelled)
If the bulk operation cannot be found, the API returns the error: Bulk operation not found.

Migrating from v1​

Endpoints​

Field names​

Key Features​

Request Parameters​

Top-Level Parameters​

Recipient Structure​

Action Structure​

Template Payload Structure​

Variables Structure​

Parameter Formats​

HEADER Component​

BODY Component​

BUTTONS Component​

CAROUSEL Component​

Examples​

1. Simple Template — No Variables, Same Content for All Recipients​

2. Template with Shared Body Variables​

3. Personalized Template — Per-Recipient Variables with isMerge​

4. URL Button Variable​

5. Scheduled Delivery​

Response​

Error Responses​

Show — Bulk Operation Status and Statistics​

Request Parameters​

Response​

Show Fields​

Reference ID​

Message Stats — WhatsApp Message Status​

Request Parameters​

Response​

Message Stats Fields​

Options Structure — Pagination, Filtering, and Sorting​

Options Fields​

Pagination Structure​

Filtering Structure​

Sorting Structure​

Combined Usage Example​

Items — Item Details and Listing​

List — Item List​

Request Parameters​

Request — Basic Usage​

Request — Filter by Specific Status​

Response​

List With Messages — List with Message Details​

Request — Basic Usage​

Request — Filter by Message Status​

Request — List Failed Messages​

Response​

Item Fields​

List vs List-With-Messages Comparison​

Stop — Cancel Delivery​

Request Parameters​

Response​

Migrating from v1

Endpoints

Field names

Key Features

Request Parameters

Top-Level Parameters

Recipient Structure

Action Structure

Template Payload Structure

Variables Structure

Parameter Formats

HEADER Component

BODY Component

BUTTONS Component

CAROUSEL Component

Examples

1. Simple Template — No Variables, Same Content for All Recipients

2. Template with Shared Body Variables

3. Personalized Template — Per-Recipient Variables with isMerge

4. URL Button Variable

5. Scheduled Delivery

Response

Error Responses

Show — Bulk Operation Status and Statistics

Request Parameters

Response

Show Fields

Reference ID

Message Stats — WhatsApp Message Status

Request Parameters

Response

Message Stats Fields

Options Structure — Pagination, Filtering, and Sorting

Options Fields

Pagination Structure

Filtering Structure

Sorting Structure

Combined Usage Example

Items — Item Details and Listing

List — Item List

Request Parameters

Request — Basic Usage

Request — Filter by Specific Status

Response

List With Messages — List with Message Details

Request — Basic Usage

Request — Filter by Message Status

Request — List Failed Messages

Response

Item Fields

List vs List-With-Messages Comparison

Stop — Cancel Delivery

Request Parameters

Response