Creating and Sending WhatsApp Broadcast
This endpoint allows you to create and send a WhatsApp message template to multiple subscribers in a single API request.
Before creating and sending bulk WhatsApp messages you need to:
- Created a WhatsApp Message Template (Text, Media or Regular) that was approved by META previously.
- Create a Subscriber List that contains a column which stores the messages of the subscribers.
- Once created the subscriber list, copy the unique identifier of the list ("listId"). This id will help you to send the message to the subscribers that are added in that list.
In the following request body example, we are going to send a WhatsApp message templated previously approved by META for each subscriber contained in the list.
When you create and sending a WhatsApp message template to multiple subscribers (Broadcast), the request body contains the following data:
HTTP Request: POST /broadcasts
{
"deliveryMethod": "WHATSAPP",
"campaignName": "SendingWhatsAppTemplate",
"description": "TestWhatsAppTemplate",
"listId": 85,
"listField": "mobile",
"message": "Unlock exclusive deals with us! Shop now and enjoy up to 50% off.",
"origin": "+123456789",
"scheduleWithoutDate": false,
"whatsappTemplateName": "code_shipping",
"whatsappTemplateLanguage": "en",
"whatsappTemplateId": "5fa14d7689ad77431",
"whatsappTemplateHeader": {
"type": "image",
"url": "https://example.com?media=image.png"
},
"whatsappTemplateButtons": [
{
"type": "cta",
"values": [
{
"index": 0,
"value": "ertyhgf456"
}
]
},
{
"type": "quick-reply",
"values": [
{
"index": 1,
"value": "Unsubscribe"
}
]
}
]
}
The parameters presented in the request body example when creating and sending the WhatsApp message template are the following:
Parameter | Required | Description |
---|---|---|
deliveryMethod | Yes | Specifies the type of delivery channel which the message will be sent: In this case, we enter the |
campaignName | Yes | Name of the campaign, used as the main identifier for the broadcast. |
description | Yes | Description of the broadcast. |
listId | Yes | Enter the unique identifier of the list which contains the Recipients (subscribers) of the broadcast. |
listField | Yes |
Name of the column defined when creating the subscriber list that contains the mobile numbers of the subscribers. Mobile numbers are specified in E.164 format → (‘+’ and a country code). |
message | Yes | Applies only when sending a Regular Message. Content of the regular message that will be sent to the subscribers. If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window to send the regular message, without using a template. |
origin | Yes |
Source address of the broadcast. Phone number provided during the WABA account setup will be used as the sender of the broadcast. Only accepts numeric characters. Do not include the "+" sign. |
scheduleWithoutDate | Yes |
Define the Date & Time of your broadcast
By default is |
whatsappTemplateName | Yes |
Applies only when sending a WhatsApp Message Template. Name of the template created in your WhatsApp Business Account. |
whatsappTemplateLanguage | Yes |
Applies only when sending a WhatsApp Message Template. Language of the WhatsApp message template.
|
whatsappTemplateId | Yes |
Applies only when sending a WhatsApp Message Template. Unique identifier of the whatsApp message template. |
whatsappTemplateHeader | No |
Applies only when sending a WhatsApp Message Template. Object of personalized fields (placeholders) or URL containing the header type chosen when creating the template. |
whatsappTemplateHeader.type | No |
Applies only when sending a WhatsApp Message Template. Enter the header type chosen when creating the template in lower case: "image", "video", "document". |
whatsappTemplateHeader.url | No |
Applies only when sending a WhatsApp Message Template. if you set the Video, Image or Document as Header option when creating the template, enter the URL of the chosen media. The URL of the header (image, video and document) must be a valid URL that starts with |
whatsappTemplateButtons | No |
Applies only when sending a WhatsApp Message Template. If you set the Call To Action as Button type, it is required when the button contains a Dynamic URL. If you set the Quick Reply as Button type, it is required when the button contains a payload or keywords. Array that contains the URL Suffix value (placeholder) of Dynamic URL for a Call To Action Button, and payloads or keywords from Quick Reply Buttons containing the button type chosen when creating the template. |
whatsappTemplateButtons.type | No |
Applies only when sending a WhatsApp Message Template. Enter the button type chosen when creating the template:
|
whatsappTemplateButtons.values | No |
Applies only when sending a WhatsApp Message Template. Array that contains the Template button values. |
whatsappTemplateButtons.values.index | No |
Applies only when sending a WhatsApp Message Template. Position index of the button of how it was defined when creating the template. For Call to Action and Quick Reply buttons, indicates the position index of the button of how it was defined when creating the template (0, 1, 2, 3, ...). |
whatsappTemplateButtons.values.value | No |
Applies only when sending a WhatsApp Message Template. For Call To Action buttons, if the created template has been defined with a dynamic URL, enter the URL suffix value defined when creating the template regarding its index position. The URL suffix is then propagated as an extension of the registered URL address. For Quick Reply buttons, enter the payload or keyword defined when creating the template regarding its index position. |
broadcastDate | No |
Applies only when the Set the date and time when the WhatsApp message template will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ). If you do not set the date, the sending of the broadcast will be pending. |
segmentId | No |
Unique identifier of the segment. |
filters | No |
Set the filter you want to apply on the message. |
filterName | No |
Filter Name. The content is the name of the filter applied on the message. |
throttle | No |
Message delivery speedometer. By default, 250 messages are sent per second. |
clientId | No |
Unique user identifier that can be used for reporting purposes. |
When you created and sent the WhatsApp message template, the response body contains the following data:
{
"meta": {
"timestamp": 1689906776296,
"transactionId": "98bc7263-47cf-4217-9d22"
},
"data": {
"id": 84382,
"beginDate": "2023-07-21T02:32:56.244598259Z",
"deliveryMethod": "WHATSAPP",
"campaignName": "WhatsApp Broadcast",
"createdBy": "[email protected]",
"operator": "[email protected]",
"description": "Sending Broadcast now",
"listId": 95650,
"listSize": 1,
"listField": "mobile",
"origin": "17542163412",
"broadcastDate": "2023-07-21T02:32:56.244597906Z",
"broadcastStatus": "SENDING",
"createdAt": "2023-07-21T02:32:56.176551918Z",
"scheduleWithoutDate": false,
"throttle": 250,
"notSentCounter": 1,
"messagesSentCounter": 0,
"whatsappConfig": {
"whatsappTemplateName": "whatsapp_new_chetna",
"whatsappTemplateLanguage": "en",
"whatsappTemplateId": "562464325983702"
}
}
}
Parameters presented in the response body example when creating and sending the WhatsApp message template are the following:
Parameter | Description |
---|---|
data | Data contained once the broadcast was created and sent. |
data.id | Unique identifier of the broadcast. |
data.beginDate | Date on which the creation and sending of the Broadcast begins. |
data.deliveryMethod | Delivery channel in which the message will be sent: In this case, we enter the |
data.campaignName | Name of the campaign, used as the main identifier for the broadcast. |
data.createdBy | User who created and sent the broadcast. |
data.operator | User who is a member of the owner or creator of the broadcast. |
data.description | Description of the broadcast. |
data.listId | Unique identifier of the list which contains the Recipients (subscribers) of the broadcast. |
data.listSize | Total number of lines read in the list. |
data.listField | Name of the column defined when creating the subscriber list that contains the mobile numbers of the subscribers. Mobile numbers are specified in E.164 format → (‘+’ and a country code). |
data.message | Applies only when sending a Regular Message. Content of the regular message that will be sent to the subscribers. If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window to send the regular message, without using a template. |
data.origin |
Source address of the broadcast. Phone number provided during the WABA account setup will be used as the sender of the broadcast. Only accepts numeric characters. Do not include the "+" sign. |
data.broadcastDate |
Optional. Applies only when the Set the date and time when the WhatsApp message template will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ). If you do not set the date, the sending of the broadcast will be pending. |
data.broadcastStatus |
When the broadcast is created and sent, the system assigns one of the following possible statuses to a Broadcast:
|
data.createdAt | Date when the broadcast was created and sent . |
data.scheduleWithoutDate |
Date & Time of your broadcast
By default is |
data.throttle | Optional. Message delivery speedometer. By default, 15 messages are sent per second. |
data.notSentCounter | Total unsent messages. |
data.messagesSentCounter | Total sent messages. |
data.whatsappConfig | Data contained when sending a Whatsapp message template. |
data.whatsappConfig.whatsappTemplateName |
Applies only when sending a WhatsApp Message Template. Name of the template created in your WhatsApp Business Account. |
data.whatsappConfig.whatsappTemplateLanguage |
Applies only when sending a WhatsApp Message Template. Language of the WhatsApp message template.
|
data.whatsappConfig.whatsappTemplateId |
Applies only when sending a WhatsApp Message Template. Unique identifier of the whatsApp message template. |
Updated 5 days ago