Skip to content
DutiesBook API
Open app

Bulk messaging

Send template messages to multiple recipients in a single request. Supports up to 10,000 recipients with optional per-recipient personalization.

Use cases

  • Marketing campaigns: Promotional messages to opted-in customers
  • Appointment reminders: Personalized reminders with individual times
  • Order updates: Shipping notifications for multiple orders
  • Announcements: Service updates to all users
POST /messages/bulk

Queue messages for delivery to multiple recipients. Messages are processed asynchronously.

channelId string Required
Channel UUID
name string Required
Broadcast name (max 100 chars)
recipients array Required
Phone numbers or recipient objects (max 10,000). See Recipient object fields.
templateName string Required
Template name
language string Required
Template language code
variables object Optional
Default template variables (applies to all recipients)
Show 3 child fields Hide 3 child fields
header object Optional
Header variables {"1": "value"}
body object Optional
Body variables {"1": "value", "2": "value"}
buttons object Optional
Button variables for URL buttons with dynamic suffixes {"1": "value"}
media object Optional
Media attachment for templates with IMAGE/VIDEO/DOCUMENT headers
Show 2 child fields Hide 2 child fields
url string Conditional
Public URL of the media file. Required when template has a media header.
filename string Optional
Custom filename for the media file (e.g., report.pdf)

flow.state is per-recipient only

For templates with a WhatsApp Flow button, a single correlation token reused across thousands of recipients can’t identify who submitted the Flow. Set flow.state per recipient instead — see Recipient object fields.

phone string Required
Phone number (E.164 format)
name string Optional
Contact display name
tags array Optional
Tags to assign to contact
variables object Optional
Per-recipient template variables (overrides top-level variables)
Show 3 child fields Hide 3 child fields
header object Optional
Header variables {"1": "value"}
body object Optional
Body variables {"1": "value", "2": "value"}
buttons object Optional
Button variables {"1": "value"}
flow object Optional
Only valid when the template has a WhatsApp Flow button
Show 1 child field Hide 1 child field
state string Optional
This recipient's correlation token (max 1000 chars), returned on the Flow completion webhook

Fallback variables

When using per-recipient variables, any variable keys missing from a recipient’s variables must have a fallback value in the top-level variables object. For example, if a recipient only provides body variables but the template also uses header variables, the top-level variables.header must be set.

Partial success

If some recipients have invalid phone numbers, they’ll be listed in invalidRecipients. Valid recipients will still receive messages.

curl -X POST \
https://app.dutiesbook.com/api/external/v1/messages/bulk \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Broadcast Name",
"recipients": [
{
"phone": "+xxxxxxxxxxx",
"variables": {
"body": {
"1": "value1",
"2": "value2"
}
}
},
{
"phone": "+xxxxxxxxxxx",
"variables": {
"body": {
"1": "value1",
"2": "value2"
}
}
}
],
"templateName": "template_name",
"language": "en_US"
}'
202 Accepted
{
"success": true,
"data": {
"bulkId": "bulk_abc123xyz",
"status": "queued",
"name": "Order Updates Batch",
"templateName": "order_shipped",
"recipientCount": 2,
"validRecipients": 2,
"invalidRecipients": [],
"statusUrl": "/api/external/v1/messages/bulk/bulk_abc123xyz/status"
}
}
202 Accepted · with invalid recipients
{
"success": true,
"data": {
"bulkId": "bulk_abc123xyz",
"status": "queued",
"recipientCount": 2,
"validRecipients": 2,
"invalidRecipients": [
{
"phone": "invalid-number",
"reason": "Invalid phone number format"
}
]
}
}

Simple format

Array of phone numbers. All recipients receive the same message with shared variables.

Personalized format

Array of recipient objects with individual variables for personalized messages.

All recipients receive the same template variables:

{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Broadcast Name",
"recipients": [
"+xxxxxxxxxxx",
"+xxxxxxxxxxx",
"+xxxxxxxxxxx"
],
"templateName": "template_name",
"language": "en_US",
"variables": {
"body": {
"1": "value1",
"2": "value2"
}
}
}

Personalized format (per-recipient variables)

Section titled “Personalized format (per-recipient variables)”

Each recipient can have their own variables:

{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Broadcast Name",
"recipients": [
{
"phone": "+xxxxxxxxxxx",
"name": "Contact Name",
"tags": ["tag1"],
"variables": {
"header": {
"1": "value1"
},
"body": {
"1": "value1",
"2": "value2"
},
"buttons": {
"1": "value1"
}
}
},
{
"phone": "+xxxxxxxxxxx",
"name": "Contact Name",
"tags": ["tag1"],
"variables": {
"header": {
"1": "value1"
},
"body": {
"1": "value1",
"2": "value2"
},
"buttons": {
"1": "value1"
}
}
}
],
"templateName": "template_name",
"language": "en_US"
}

With media (per-recipient variables and fallbacks)

Section titled “With media (per-recipient variables and fallbacks)”

For templates with IMAGE/VIDEO/DOCUMENT headers, include the media field. Per-recipient variables override the top-level variables fallback:

{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Broadcast Name",
"templateName": "template_name",
"language": "en_US",
"media": {
"url": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",
"filename": "filename.pdf"
},
"recipients": [
{
"phone": "+xxxxxxxxxxx",
"variables": {
"body": {
"1": "value1",
"2": "value2",
"3": "value3",
"4": "value4"
}
}
}
],
"variables": {
"body": {
"1": "fallback1",
"2": "fallback2",
"3": "fallback3",
"4": "fallback4"
}
}
}

With a WhatsApp Flow (per-recipient correlation)

Section titled “With a WhatsApp Flow (per-recipient correlation)”

For templates with a Flow button, each recipient can carry its own correlation token so the completion webhook can be tied back to that recipient:

{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Appointment Booking Flow",
"templateName": "appointment_booking_flow",
"language": "en_US",
"recipients": [
{
"phone": "+xxxxxxxxxxx",
"variables": {
"body": {
"1": "John"
}
},
"flow": {
"state": "order-58212"
}
}
]
}
GET /messages/bulk/{bulkId}/status

Get the status and progress of a bulk send operation.

queued
Waiting to be processed
sending
Currently sending messages
sent
All messages sent
failed
Bulk send failed
total
Total number of recipients
sent
Messages successfully sent to Meta
delivered
Messages delivered to recipient
read
Messages read by recipient
failed
Messages that failed to send
pending
Messages waiting to be sent
curl \
https://app.dutiesbook.com/api/external/v1/messages/bulk/bulk_abc123xyz/status \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
200 OK
{
"success": true,
"data": {
"bulkId": "bulk_abc123xyz",
"name": "Order Updates Batch",
"status": "sending",
"progress": {
"total": 1000,
"sent": 750,
"delivered": 600,
"read": 200,
"failed": 10,
"pending": 250
},
"startedAt": "2024-01-15T10:30:00Z",
"completedAt": null
}
}
GET /messages/bulk/{bulkId}/recipients

Get a paginated, per-recipient breakdown of a bulk send — phone number, delivery status, message ID, timestamps, and error details.

status string Optional
Filter by recipient status: pending, sending, sent, delivered, read, failed
page number Optional
Page number (default: 1)
limit number Optional
Items per page (default: 50, max: 200)
phone string
Recipient phone number
status string
Current delivery status
flowState string
This recipient's flow.state correlation token, if the send used a WhatsApp Flow template. null otherwise.
flowSubmission object
The Flow answers this recipient submitted, keyed by Meta's field names. null until they complete the Flow.
flowCompletedAt string
Timestamp the recipient completed the Flow. null until then.
messageId string
WhatsApp message ID, once sent
sentAt string
Timestamp the message was sent to Meta
deliveredAt string
Timestamp the message was delivered
readAt string
Timestamp the message was read
failedAt string
Timestamp the message failed, if applicable
error object
Structured failure detail (code, category, title, detail). null unless the recipient failed.
retryCount number
Number of automatic retry attempts made for this recipient

Field labels for flowSubmission

flowSubmission keys are Meta’s own field names, passed through verbatim — see the payload contract in Flow Events.

curl \
https://app.dutiesbook.com/api/external/v1/messages/bulk/bulk_abc123xyz/recipients?status=failed&page=1&limit=50 \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
200 OK
{
"success": true,
"data": {
"bulkId": "bulk_abc123xyz",
"recipients": [
{
"phone": "+1234567890",
"status": "failed",
"flowState": null,
"flowSubmission": null,
"flowCompletedAt": null,
"messageId": null,
"sentAt": null,
"deliveredAt": null,
"readAt": null,
"failedAt": "2024-01-15T10:31:00Z",
"error": {
"code": 131026,
"category": "TRANSIENT",
"title": "Message undeliverable",
"detail": "The message could not be delivered to this recipient."
},
"retryCount": 1
},
{
"phone": "+0987654321",
"status": "delivered",
"flowState": "order-58212",
"flowSubmission": {
"screen_0_Preferred_time_1": "Mon 10am"
},
"flowCompletedAt": "2024-01-15T10:32:40Z",
"messageId": "wamid.HBgLMTIzNDU2Nzg5MA==",
"sentAt": "2024-01-15T10:30:05Z",
"deliveredAt": "2024-01-15T10:30:12Z",
"readAt": null,
"failedAt": null,
"error": null,
"retryCount": 0
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 2,
"pages": 1
}
}
}
VAL_001 400
INVALID_PHONE_NUMBER

Invalid phone number format. Use E.164 format.

VAL_004 400
MISSING_REQUIRED_FIELD

Missing required field in request body.

VAL_006 400
TOO_MANY_RECIPIENTS

Maximum 10,000 recipients per request. Split into multiple requests if needed.

VAL_009 400
MISSING_FALLBACK_VARIABLES

Recipient variables are missing keys that are not covered by fallback variables.

VAL_010 400
MEDIA_REQUIRED

This template has a media header (IMAGE/VIDEO/DOCUMENT). Please provide a media.url field.

VAL_011 400
MEDIA_NOT_SUPPORTED

This template does not have a media header. Remove the media field.

VAL_012 400
FLOW_NOT_SUPPORTED

This template does not have a WhatsApp Flow button. Remove the flow field.

RES_001 404
CHANNEL_NOT_FOUND

The specified channel was not found.

RES_002 404
TEMPLATE_NOT_FOUND

The specified template was not found.

RES_003 404
BULK_NOT_FOUND

The specified bulk send was not found.

AUTH_008 403
CHANNEL_ACCESS_DENIED

This API key is restricted to specific channels and does not have access to this channel.

BIZ_001 422
CHANNEL_NOT_CONNECTED

The channel is not currently connected.

BIZ_002 422
TEMPLATE_NOT_APPROVED

The template is not approved for use.

BIZ_004 422
PAYMENT_METHOD_REQUIRED

Payment method required. Please add a payment method to your WhatsApp Business Account.

SRV_002 500
META_API_ERROR

Failed to send message via WhatsApp API.

Best practices

  • Use personalized format for better engagement when you have per-recipient data
  • Batch large lists into multiple requests if you have more than 10,000 recipients
  • Poll status periodically to track delivery progress
  • Handle invalid recipients in the response - they won’t be sent messages
  • Use descriptive names for bulk sends to easily identify them later