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
Send bulk messages
Section titled “Send bulk messages”/messages/bulk Queue messages for delivery to multiple recipients. Messages are processed asynchronously.
Request body
Section titled “Request body”channelId string Required name string Required recipients array Required templateName string Required language string Required variables object Optional Show 3 child fields Hide 3 child fields
header object Optional {"1": "value"}body object Optional {"1": "value", "2": "value"}buttons object Optional {"1": "value"}media object Optional Show 2 child fields Hide 2 child fields
url string Conditional filename string Optional 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.
Recipient object fields
Section titled “Recipient object fields”phone string Required name string Optional tags array Optional variables object Optional Show 3 child fields Hide 3 child fields
header object Optional {"1": "value"}body object Optional {"1": "value", "2": "value"}buttons object Optional {"1": "value"}flow object Optional Show 1 child field Hide 1 child field
state string Optional 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" }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/messages/bulk', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, }, body: JSON.stringify({ "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" }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/messages/bulk", headers={ "X-Account-Id": os.environ["DUTIES_ACCOUNT_ID"], "X-Api-Key": os.environ["DUTIES_API_KEY"], "X-Secret-Key": os.environ["DUTIES_SECRET_KEY"], }, json={ "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", },)
result = response.json(){ "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" }}{ "success": true, "data": { "bulkId": "bulk_abc123xyz", "status": "queued", "recipientCount": 2, "validRecipients": 2, "invalidRecipients": [ { "phone": "invalid-number", "reason": "Invalid phone number format" } ] }}Recipient formats
Section titled “Recipient formats”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.
Simple format (same variables)
Section titled “Simple format (same variables)”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" } } ]}Check bulk status
Section titled “Check bulk status”/messages/bulk/{bulkId}/status Get the status and progress of a bulk send operation.
Bulk status values
Section titled “Bulk status values”queued sending sent failed Progress fields
Section titled “Progress fields”total sent delivered read failed pending 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"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/messages/bulk/bulk_abc123xyz/status', { method: 'GET', headers: { 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, },});
const result = await response.json();import osimport requests
response = requests.get( "https://app.dutiesbook.com/api/external/v1/messages/bulk/bulk_abc123xyz/status", headers={ "X-Account-Id": os.environ["DUTIES_ACCOUNT_ID"], "X-Api-Key": os.environ["DUTIES_API_KEY"], "X-Secret-Key": os.environ["DUTIES_SECRET_KEY"], },)
result = response.json(){ "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 }}List bulk recipients
Section titled “List bulk recipients”/messages/bulk/{bulkId}/recipients Get a paginated, per-recipient breakdown of a bulk send — phone number, delivery status, message ID, timestamps, and error details.
Query parameters
Section titled “Query parameters”status string Optional pending, sending, sent, delivered, read, failedpage number Optional limit number Optional Recipient fields
Section titled “Recipient fields”phone string status string flowState string flow.state correlation token, if the send used a WhatsApp Flow template. null otherwise.flowSubmission object null until they complete the Flow.flowCompletedAt string null until then.messageId string sentAt string deliveredAt string readAt string failedAt string error object null unless the recipient failed.retryCount number 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"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/messages/bulk/bulk_abc123xyz/recipients?status=failed&page=1&limit=50', { method: 'GET', headers: { 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, },});
const result = await response.json();import osimport requests
response = requests.get( "https://app.dutiesbook.com/api/external/v1/messages/bulk/bulk_abc123xyz/recipients?status=failed&page=1&limit=50", headers={ "X-Account-Id": os.environ["DUTIES_ACCOUNT_ID"], "X-Api-Key": os.environ["DUTIES_API_KEY"], "X-Secret-Key": os.environ["DUTIES_SECRET_KEY"], },)
result = response.json(){ "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 } }}Errors
Section titled “Errors”VAL_001 400 Invalid phone number format. Use E.164 format.
VAL_004 400 Missing required field in request body.
VAL_006 400 Maximum 10,000 recipients per request. Split into multiple requests if needed.
VAL_009 400 Recipient variables are missing keys that are not covered by fallback variables.
VAL_010 400 This template has a media header (IMAGE/VIDEO/DOCUMENT). Please provide a media.url field.
VAL_011 400 This template does not have a media header. Remove the media field.
VAL_012 400 This template does not have a WhatsApp Flow button. Remove the flow field.
RES_001 404 The specified channel was not found.
RES_002 404 The specified template was not found.
RES_003 404 The specified bulk send was not found.
AUTH_008 403 This API key is restricted to specific channels and does not have access to this channel.
BIZ_001 422 The channel is not currently connected.
BIZ_002 422 The template is not approved for use.
BIZ_004 422 Payment method required. Please add a payment method to your WhatsApp Business Account.
SRV_002 500 Failed to send message via WhatsApp API.
Best practices
Section titled “Best practices”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