Skip to content
DutiesBook API
Open app

Send message

Send a single WhatsApp template message to a recipient. Supports personalized variables for headers, body text, and buttons.

POST /messages/send

Content-Type required

All POST requests must include the Content-Type: application/json header.

channelId string Required
Channel UUID
to string Required
Recipient phone (E.164 format)
templateName string Required
Template name
language string Required
Template language code (e.g., en_US)
variables object Optional
Template 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 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 object Optional
Only valid when the template has a WhatsApp Flow button. Otherwise omit this field entirely.
Show 1 child field Hide 1 child field
state string Optional
Your own correlation token (max 1000 chars), returned unchanged on the Flow completion webhook
contact object Optional
Contact information for auto-creation
Show 2 child fields Hide 2 child fields
name string Optional
Temporary display name for the contact. The real profile name is only available after the recipient replies.
tags array Optional
Tags to assign to the contact

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.

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"
}
}
}'
200 OK
{
"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"
}
}
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"
]
}
}'
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"
}
}'

The response for a Flow template also carries sendId:

200 OK
{
"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"
}
}

Variable numbering

Variables must be provided as objects with numbered keys matching template placeholders.

Template text: Hello {{1}}, your order {{2}} is confirmed.

{
"variables": {
"body": {
"1": "John",
"2": "#12345"
}
}
}
{
"variables": {
"header": {
"1": "Order Update"
},
"body": {
"1": "John",
"2": "#12345"
}
}
}

For URL buttons with dynamic suffixes:

{
"variables": {
"body": {
"1": "John"
},
"buttons": {
"1": "track-12345"
}
}
}

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
If provided, it's used as a temporary display name until the recipient responds.
contact.tags
If provided, they're assigned to the contact.

Example response with new contact:

{
"contact": {
"uuid": "new-contact-uuid",
"displayName": "John Doe",
"isNew": true
}
}
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_005 400
INVALID_VARIABLES

Invalid variables format.

RES_001 404
CHANNEL_NOT_FOUND

The specified channel was not found.

RES_002 404
TEMPLATE_NOT_FOUND

The specified template 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_003 422
TEMPLATE_DISABLED

Template is disabled locally. Please enable the template to use it.

BIZ_004 422
PAYMENT_METHOD_REQUIRED

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

BIZ_005 422
VARIABLE_COUNT_MISMATCH

Template variable count mismatch.

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.

VAL_013 400
META_PARAMETER_ERROR

WhatsApp rejected the message because it does not match the template. Check variables, media, and flow fields against the template definition.

SRV_002 500
META_API_ERROR

Failed to send message via WhatsApp API.

422 Unprocessable Entity
{
"success": false,
"error": {
"code": "BIZ_005",
"message": "Template requires 3 body variables but 2 were provided"
}
}