Send message
Send a single WhatsApp template message to a recipient. Supports personalized variables for headers, body text, and buttons.
/messages/send Request body
Section titled “Request body”Content-Type required
All POST requests must include the Content-Type: application/json header.
channelId string Required to string Required templateName string Required language string Required en_US)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 object Optional Show 1 child field Hide 1 child field
state string Optional contact object Optional Show 2 child fields Hide 2 child fields
name string Optional tags array Optional Media templates
If the template has an IMAGE, VIDEO, or DOCUMENT header, the media.url field is required. The URL must be publicly accessible. If the template does not have a media header, do not include the media field.
WhatsApp Flow templates
If the template has a WhatsApp Flow button, the button is attached automatically — you don’t need to build it. Use flow only to supply your own correlation token (flow.state). Sending a flow field against a template with no Flow button returns VAL_012 FLOW_NOT_SUPPORTED.
Response
Section titled “Response”Returns 200 OK with the WhatsApp message ID and the contact the message went to.
sendId
When the template has a WhatsApp Flow button, the response also includes a sendId field. It’s carried on the completion webhook as data.sendId, letting you correlate this send with the customer’s submission. See Flow Events.
curl -X POST \ https://app.dutiesbook.com/api/external/v1/messages/send \ -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", "to": "+xxxxxxxxxxx", "templateName": "template_name", "language": "en_US", "variables": { "body": { "1": "value1", "2": "value2" } } }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/messages/send', { 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", "to": "+xxxxxxxxxxx", "templateName": "template_name", "language": "en_US", "variables": { "body": { "1": "value1", "2": "value2" } } }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/messages/send", 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", "to": "+xxxxxxxxxxx", "templateName": "template_name", "language": "en_US", "variables": { "body": { "1": "value1", "2": "value2", }, }, },)
result = response.json(){ "success": true, "data": { "messageId": "wamid.HBgLMTIzNDU2Nzg5MA==", "status": "sent", "to": "+1234567890", "templateName": "order_confirmation", "contact": { "uuid": "contact-uuid", "displayName": "John Doe", "isNew": false }, "sentAt": "2024-01-15T10:30:00Z" }}More examples
Section titled “More examples”With media, contact and button variables
Section titled “With media, contact and button variables”curl -X POST \ https://app.dutiesbook.com/api/external/v1/messages/send \ -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", "to": "+xxxxxxxxxxx", "templateName": "template_name", "language": "en_US", "variables": { "header": { "1": "value1" }, "body": { "1": "value1", "2": "value2" }, "buttons": { "1": "value1" } }, "media": { "url": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf", "filename": "filename.pdf" }, "contact": { "name": "Contact Name", "tags": [ "tag1", "tag2" ] } }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/messages/send', { 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", "to": "+xxxxxxxxxxx", "templateName": "template_name", "language": "en_US", "variables": { "header": { "1": "value1" }, "body": { "1": "value1", "2": "value2" }, "buttons": { "1": "value1" } }, "media": { "url": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf", "filename": "filename.pdf" }, "contact": { "name": "Contact Name", "tags": [ "tag1", "tag2" ] } }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/messages/send", 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", "to": "+xxxxxxxxxxx", "templateName": "template_name", "language": "en_US", "variables": { "header": { "1": "value1", }, "body": { "1": "value1", "2": "value2", }, "buttons": { "1": "value1", }, }, "media": { "url": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf", "filename": "filename.pdf", }, "contact": { "name": "Contact Name", "tags": [ "tag1", "tag2", ], }, },)
result = response.json()With a WhatsApp Flow
Section titled “With a WhatsApp Flow”curl -X POST \ https://app.dutiesbook.com/api/external/v1/messages/send \ -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", "to": "+xxxxxxxxxxx", "templateName": "appointment_booking_flow", "language": "en_US", "variables": { "body": { "1": "John" } }, "flow": { "state": "order-58212" } }'// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/messages/send', { 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", "to": "+xxxxxxxxxxx", "templateName": "appointment_booking_flow", "language": "en_US", "variables": { "body": { "1": "John" } }, "flow": { "state": "order-58212" } }),});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/messages/send", 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", "to": "+xxxxxxxxxxx", "templateName": "appointment_booking_flow", "language": "en_US", "variables": { "body": { "1": "John", }, }, "flow": { "state": "order-58212", }, },)
result = response.json()The response for a Flow template also carries sendId:
{ "success": true, "data": { "messageId": "wamid.HBgLMTIzNDU2Nzg5MA==", "status": "sent", "to": "+1234567890", "templateName": "appointment_booking_flow", "sendId": "fsend_abc123xyz", "contact": { "uuid": "contact-uuid", "displayName": "John Doe", "isNew": false }, "sentAt": "2024-01-15T10:30:00Z" }}Variables format
Section titled “Variables format”Variable numbering
Variables must be provided as objects with numbered keys matching template placeholders.
Template with body variables
Section titled “Template with body variables”Template text: Hello {{1}}, your order {{2}} is confirmed.
{ "variables": { "body": { "1": "John", "2": "#12345" } }}Template with header and body variables
Section titled “Template with header and body variables”{ "variables": { "header": { "1": "Order Update" }, "body": { "1": "John", "2": "#12345" } }}Template with button variables
Section titled “Template with button variables”For URL buttons with dynamic suffixes:
{ "variables": { "body": { "1": "John" }, "buttons": { "1": "track-12345" } }}Contact auto-creation
Section titled “Contact auto-creation”Automatic contact creation
When sending to a new phone number, a contact is automatically created in your organization.
Contact name
The recipient’s real WhatsApp profile name is not available until they reply to your message. Until then, contact.name is used as a temporary display name. If not provided, the phone number is used instead.
contact.name contact.tags Example response with new contact:
{ "contact": { "uuid": "new-contact-uuid", "displayName": "John Doe", "isNew": true }}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_005 400 Invalid variables format.
RES_001 404 The specified channel was not found.
RES_002 404 The specified template 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_003 422 Template is disabled locally. Please enable the template to use it.
BIZ_004 422 Payment method required. Please add a payment method to your WhatsApp Business Account.
BIZ_005 422 Template variable count mismatch.
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.
VAL_013 400 WhatsApp rejected the message because it does not match the template. Check variables, media, and flow fields against the template definition.
SRV_002 500 Failed to send message via WhatsApp API.
Error response example
Section titled “Error response example”{ "success": false, "error": { "code": "BIZ_005", "message": "Template requires 3 body variables but 2 were provided" }}