Send template message
API to send a WhatsApp templated message to recipient.
API to send a WhatsApp templated message to recipient
Optional. Sender WhatsApp number, not required when only 1 WA number is present.
+16501113333
WhatsApp number for recipient.
+16502223333
WhatsApp template name, managed through WhatsApp Cloud API.
bogo_marketing_campaign
Optional. WhatsApp template language, managed through WhatsApp Cloud API.
en
Optional. Campaign name.
test_campaign_2022-03-12
POST /v1/businesses/{businessId}/send/whatsapp_templated_messages HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 306
{
"sender": "+16501113333",
"number": "+16502223333",
"templateName": "bogo_marketing_campaign",
"language": "en",
"parameters": [
{
"name": "body_1 in body text 'Hi, {{1}}!'",
"value": "Harry",
"filename": "doc.pdf"
}
],
"campaignName": "test_campaign_2022-03-12",
"order": {
"parentId": "text",
"strategy": "strategy_unspecified"
}
}
{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}
24 hour WhatsApp restriction
If the recipient has not initiated the conversation first within the last 24 hours you MUST use templated message API /v1/businesses/{businessId}/send/whatsapp_templated_messages
.
Generally, you use
/v1/businesses/{businessId}/send/messages
to reply to the customers who already messaged you first.You use
/v1/businesses/{businessId}/send/whatsapp_templated_messages
to initiate with the customer first.
Select the WhatsApp number you want to send from
The endpoint supports an optional sender field in the body. If you have multiple WhatsApp phone numbers with Connectly you can choose which one you want to send the message from. The payload needs to contain the optional sender
key specifying the phone number.
{
"sender": "+14151111234",
"number": "+1(604) 585 2331",
"templateName": "template",
"language": "en",
"parameters": []
}
Template languages
Your template can have different language translations which is why you need to provide the language in the API call.
To see a list of available languages go to Meta's official documentation.
Your template must have a language translation approved before you can use it for that specific language.
In most cases, the default template language is `en`.
Please see Meta Business Manager for the available templates and language translations.
Most common languages for templates
The language is specified in language
field. To see a list of available languages go to Meta's official documentation.
Brazilian Portuguese
{
"number": "16044441234",
"templateName": "my_brazilian_template",
"language": "pt_BR",
"parameters": []
}
Spanish
{
"number": "16044441234",
"templateName": "my_spanish_template",
"language": "es",
"parameters": []
}
How to use template parameters
The template parameters is a list of objects in the following format:
"parameters": [
{
"name": "header_document",
"value": "YOUR_VALUE",
"filename": "NAME_OF_DOCUMENT_FILE" // Only applicable to header_document
},
{
"name": "body_1",
"value": "YOUR_VALUE"
},
{
"name": "body_2",
"value": "YOUR_VALUE"
},
{
"name": "body_3",
"value": "YOUR_VALUE"
}
]
Available options for name
keys
name
keysHeader
header_text
- indicates text in the header. Works only if the header has any variables in it. Substitutes the variables with the specified text.header_document
- indicates document in the header. Thevalue
must be a valid URL with valid document. You can also specify how to name the file usingfilename
parameter. See examples below.
For supported media types please reference Meta's official documentation.
Body
body_1
- indicates text in the bodybody_2
- indicates text in the bodybody_3
- indicates text in the bodybody_4
- indicates text in the bodybody_5
- indicates text in the bodybody_6
- indicates text in the bodybody_7
- indicates text in the bodybody_8
- indicates text in the bodybody_9
- indicates text in the bodybody_10
- indicates text in the bodybody_11
- indicates text in the bodybody_12
- indicates text in the bodybody_13
- indicates text in the bodybody_14
- indicates text in the bodybody_15
- indicates text in the body
Buttons
button_1_url_suffix
- indicates URL link in the button. Thevalue
must be a valid URLbutton_2_url_suffix
- indicates URL link in the button. Thevalue
must be a valid URLbutton_3_url_suffix
- indicates URL link in the button. Thevalue
must be a valid URL
Examples
You have a template with one header variable and several body variables
{
"number": "16044441234",
"templateName": "my_template_name",
"language": "en",
"parameters": [
{
"name": "header_text",
"value": "Hello"
},
{
"name": "body_1",
"value": "John"
},
{
"name": "body_2",
"value": "red"
}
]
}
You have a template with a header image and multiple body variables
{
"number": "16044441234",
"templateName": "external_header_test2",
"language": "pt_BR",
"parameters": [
{
"name": "header_image",
"value": "https://i.picsum.photos/id/695/200/300"
},
{
"name": "body_1",
"value": "Connectly.ai"
},
{
"name": "body_2",
"value": "John"
}
{
"name": "body_3",
"value": "a new party"
},
{
"name": "body_4",
"value": "McDonald's"
},
{
"name": "body_5",
"value": "celebrate lol"
}
]
}
You have a template with a header document
{
"number": "16044441234",
"templateName": "external_header_document",
"language": "en",
"parameters": [
{
"name": "header_document",
"value": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
"filename": "feelssss"
}
]
}
You have a template with the link button and button has a suffix
{
"number": "16044441234",
"templateName": "external_link_button",
"language": "es",
"parameters": [
{
"name": "button_1_url_suffix",
"value": "connectlyai"
}
]
}
The above payload will send a template where "Our Facebook" button will take the customer to www.facebook.com/connectlyai
You have a template with two quick reply buttons
{
"number": "16044441234",
"templateName": "my_template_name",
"language": "en_US",
"parameters": []
}
Sending a Carousel template message
To send a Carousel message, first you need to create the template using Carousel template.
Assuming you want to send the same template created in Carousel template, you can use the below payload structure:
{
"number": "<TARGET PHONE NUMBER>",
"templateName": "carousel_demo_1",
"language": "en_US",
"parameters": [
{
"name": "card.0.header.image",
"value": "https://i.ibb.co/yB7pCHD/2025-02-20-16-38.png"
},
{
"name": "card.0.body.0",
"value": "Yuri"
},
{
"name": "card.0.button.0.urlSuffix",
"value": "fruits1234"
},
{
"name": "card.1.header.image",
"value": "https://i.ibb.co/nM0rYxB/2025-02-20-16-38-1.png"
},
{
"name": "card.1.body.0",
"value": "3-March 2025"
},
{
"name": "card.1.button.0.urlSuffix",
"value": "fruitcoupons"
}
]
}
Note that to detect carousel button clicks and replies, you need to subscribe to our Webhook API.
Rate Limiting
To ensure fair usage and maintain service stability, we have implemented rate limiting for above APIs. This endpoint is limited to 200 requests per second. If the limit is exceeded, the API will return a 429 Too Many Requests
response.
WhatsApp Message template
Last updated