Creating and Sending WhatsApp Broadcast

This endpoint allows you to create and send a WhatsApp message template to multiple contacts 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 Contact List that contains a column that stores the messages of the contacts.
Once the contact list is created, copy the unique identifier of the list ("listId"). This ID will help you to send the message to the contacts who are added to that list.

In the following request body example, we are going to send a WhatsApp message template previously approved by META for each contact contained in the list.

When you create and send a WhatsApp message template to multiple contacts (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 message template are the following:

Parameter	Required	Description
deliveryMethod	Yes	Specifies the type of delivery channel which the message will be sent: `"SMS"` ,`"EMAIL"`, `"RCS"`, `"WHATSAPP"`. In this case, we enter the `"WHATSAPP"` value to send the WhatsApp message template.
campaignName	Yes	Name of the broadcast, used as the main identifier.
description	Yes	Description of the broadcast.
listId	Yes	Enter the unique identifier of the list which contains the Recipients (contacts) of the broadcast.
listField	Yes	Name of the column defined when creating the contact list that contains the mobile numbers of the contacts.
message	Yes	Applies only when sending a Regular Message. Content of the regular message that will be sent to the contacts. 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 message 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 `true`: Define the date and time when sending the WhatsApp message template. `false`: Send the WhatsApp message template once the API Call is executed. By default is `false`
whatsappTemplateName	Yes	Applies only when sending a WhatsApp Message Template. Name of the message template created in your WhatsApp Business Account.
whatsappTemplateLanguage	Yes	Applies only when sending a WhatsApp Message Template. Language of the WhatsApp message template. `English`: `"en"`, `"en_GB"`, `"en_US"` `Spanish`: `"es"`, `"es_AR"`, `"es_ES"`, `"es_MX"` `Portuguese`: `"pt_BR"`, `"pt_PT"`
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 message template.
whatsappTemplateHeader. type	No	Applies only when sending a WhatsApp Message Template. Enter the header type chosen when creating the message 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 message 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 `"http://…"` or `"https://…"` and provides a direct download. Redirects are not supported.
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 message template.
whatsappTemplateButtons. type	No	Applies only when sending a WhatsApp Message Template. Enter the button type chosen when creating the message template: `"cta"`: call to action button. `"quick-reply"`: quick reply button.
whatsappTemplateButtons. values	No	Applies only when sending a WhatsApp Message Template. Array that contains the Message 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 message template. For Call to Action and Quick Reply buttons, indicates the position index of the button of how it was defined when creating the message 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 message template has been defined with a dynamic URL, enter the URL suffix value defined when creating the message 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 message template regarding its index position.
broadcastDate	No	Applies only when the `"scheduleWithoutDate"` is true. That is, when you want to define the date and time when sending the WhatsApp message template. 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: `"SMS"` ,`"EMAIL"`, `"RCS"`, `"WHATSAPP"`. In this case, we enter the `"WHATSAPP"` value to send the WhatsApp message template.
data. campaignName	Name of the broadcast, used as the main identifier.
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 (contacts) of the broadcast.
data. listSize	Total number of lines read in the list.
data. listField	Name of the column defined when creating the contact list that contains the mobile numbers of the contacts. 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 contacts. 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 message 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 `"scheduleWithoutDate"` is true. That is, when you want to define the date and time when sending the WhatsApp message template. 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: `"CODE_NOT_ALLOWED"`: Messangi suggests that the WhatsApp Business Account (WABA) used is either not activated on the platform or lacks the capability to message the recipient. Additionally, it could be because the owner does not have a WABA assigned , which is required to send the message. Contact our support team to verify the WABA. `"INCOMPLETE"`: Messangi indicates that a personalized WhatsApp message was sent without the necessary placeholder data filled in. Please note, personalized messages are those that feature dynamic fields—like "Name", "Phone Number", "Last Name", and similar—which need to be populated before sending. `"BLACKLISTED"`: Messangi indicates that the intended recipient's phone number is on a blacklist, preventing any messages from being sent to that number. When a number is blacklisted, it is essentially blocked from receiving any further communications from the sender's number or broadcast, ensuring that no messages are delivered to that recipient. `"QUOTA_EXCEEDED"`: The WhatsApp Business Account (WABA) has surpassed the allowed limit for sending messages within a specified period, as defined by WhatsApp's messaging policies or limits. `"SENT"`: Indicates that the message has been successfully dispatched from our system and is en route to META. This status means that the message is on its way to the recipient but does not confirm that the message has been delivered to the end user. It signifies a successful handoff to the next stage in the message delivery process. `"DELIVERED"`: Messangi has received confirmation of message delivery from META. The message has successfully reached the recipient's device. This status confirms that the message not only was sent and processed by META but also was received by the intended recipient's WhatsApp application, ensuring that the communication was successfully completed. `"READ"`: Indicates that the recipient has opened and seen the message. `"FAILED"`: Indicates that META could not deliver the message to the recipient's device.
data. createdAt	Date when the broadcast was created and sent .
data. scheduleWithoutDate	Date & Time of your broadcast `true`: Define the date and time when sending the WhatsApp message template. `false`: Send the WhatsApp message template once the API Call is executed. By default is `false`
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 message template created in your WhatsApp Business Account.
data. whatsappConfig. whatsappTemplateLanguage	Applies only when sending a WhatsApp Message Template. Language of the WhatsApp message template. `English`: `"en"`, `"en_GB"`, `"en_US"` `Spanish`: `"es"`, `"es_AR"`, `"es_ES"`, `"es_MX"` `Portuguese`: `"pt_BR"`, `"pt_PT"`
data. whatsappConfig. whatsappTemplateId	Applies only when sending a WhatsApp Message Template. Unique identifier of the whatsApp message template.