Send template message

API to send a WhatsApp templated message to recipient

WhatsApp template messages can be sent only to personal WhatsApp accounts not WhatsApp API accounts. If you are testing WhatsApp templated message API please use your personal WhatsApp phone number instead of your business phone number on Connectly.

Make sure your personal WhatsApp account you are using for testing has accepted all of WhatsApp app and privacy updates

API to send a WhatsApp templated message to recipient

POST/v1/businesses/{businessId}/send/whatsapp_templated_messages

Path parameters

businessId*string

Body

senderstring

Optional. Sender WhatsApp number, not required when only 1 WA number is present.

Example: "+16501113333"

numberstring

WhatsApp number for recipient.

Example: "+16502223333"

templateNamestring

WhatsApp template name, managed through WhatsApp Cloud API.

Example: "bogo_marketing_campaign"

languagestring

Optional. WhatsApp template language, managed through WhatsApp Cloud API.

Example: "en"

parametersarray of messageTemplatedMessageParameter (object)

Parameters used for templated message variable substitution.

campaignNamestring

Optional. Campaign name.

Example: "test_campaign_2022-03-12"

ordermessageEventProcessingOrderMetadata (object)

Response

A successful response.

Body

idstring

ID of created message.

Example: "01ARZ3NDEKTSV4RRFFQ69G5FAV"

Request

Response

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

Header

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. The value must be a valid URL with valid document. You can also specify how to name the file using filename parameter. See examples below.

For supported media types please reference Meta's official documentation.

Body

body_1 - indicates text in the body
body_2 - indicates text in the body
body_3 - indicates text in the body
body_4 - indicates text in the body
body_5 - indicates text in the body
body_6 - indicates text in the body
body_7 - indicates text in the body
body_8 - indicates text in the body
body_9 - indicates text in the body
body_10 - indicates text in the body
body_11 - indicates text in the body
body_12 - indicates text in the body
body_13 - indicates text in the body
body_14 - indicates text in the body
body_15 - indicates text in the body

Buttons

button_1_url_suffix - indicates URL link in the button. The value must be a valid URL
button_2_url_suffix - indicates URL link in the button. The value must be a valid URL
button_3_url_suffix - indicates URL link in the button. The value 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

If you have subscribed to Connectly Messaging Webhooks, whenever the customer presses a button the value (payload) that you specify will be sent through the webhook to indicate which button was pressed.

{
    "number": "16044441234",
    "templateName": "my_template_name",
    "language": "en_US",
    "parameters": []
}

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.