External Broadcast API
The External Broadcast API feature allows you to programmatically trigger broadcast messages to your users from your own systems, rather than solely relying on the Engati platform. This powerful capability provides flexibility and integration options for developers and technical teams.
One of the primary use-cases for the External Broadcast API is sending notices or announcements to your user base. By leveraging this API, you can seamlessly initiate broadcast campaigns from within your existing workflows and systems.
It's important to note that broadcasts initiated through the External Broadcast API may take some time (typically 5-15 minutes) to be delivered to all recipients. Additionally, the API does not provide granular tracking for delivery, send, or failure statuses of individual messages.
To access this feature, ensure WhatsApp is enabled in your account with 360Dialog as your provider. Additionally, this feature is exclusively available with higher Engati plans.
The API is specifically designed for sending broadcast messages with WhatsApp template messages and is limited to existing users.
Setting up the External Broadcast API involves a few key aspects:
- You'll need to obtain the cURL command of the specific message template you want to use for the broadcast. This cURL represents the approved template content that will be sent.
- You must prepare a CSV file containing the list of recipients you want to target with the broadcast.
Proceed by following the steps provided below to initiate a external broadcast using APIs.
Step 1 : Navigate to Broadcast > Message Templates > More Actions > Generate cURL Note: This is available only for the approved templates.
Step 2 : After clicking the ‘Generate cURL’ option an API request box will be displayed.
Step 4 : Click the 'Copy' button to save the API request curl to your clipboard. From this generated API cURL, take note of the payload section. The payload should contain the following key values:
- namespace
- name
- language
- components
The payload is the section where you'll need to provide specifics about the message template, such as the namespace it belongs to, the template name, language, and components like header, body, and buttons. Ensure these values are present and correctly formatted in the payload when using the API cURL.
Step 5 : Create a CSV file with one column containing the phone numbers of the users you want to target for the broadcast. The header of this column must be labeled as "user.phone_number".
If your message template includes any variables or placeholders for additional user attributes, you'll need extra columns in the CSV.
The headers for these extra columns should follow the format "user.attribute_N" where N starts from 0 and increments for each attribute (e.g. user.attribute_0, user.attribute_1, user.attribute_2, and so on).
Step 6 : Open you Postman and enter the values as mentioned below: Method : POST Request URL : https://api.engati.com/whatsapp-api/v1.0/customer/<customer id>/bot/<bot key>/external/broadcast?broadcast_id=<broadcast name>
Note : To get your Customer id, Bot key and API key, navigate to Integrations > Engati API. To generate an API Key : Click on "+Create App"
Step 7 : In the headers field enter the below mentioned key and value :
- Authorization : Basic <API key>
- Content-Type : application/json
Step 8 : In the Body enter the below mentioned key and value :
- target_audience: Provide the CSV file containing the list of recipients that you created in step 5.
- template_payload: Include the structure of the message template you want to send, along with any necessary parameters. This template payload should be the same payload section obtained from the generated API cURL in step 4.
After completing all the previous steps mentioned above, including providing the target audience CSV file and template payload details, you can initiate the external broadcast by clicking the "Send" button.
This will trigger the API call and kick off the process of sending the broadcast message to the specified list of recipients using the provided template.
The CSV file structure is a crucial component of the external broadcast API, as it allows you to provide the specific data and recipient information to be used in conjunction with the message template payload.
The first column header in the CSV file must be "user.phone_number," as a phone number is mandatory for WhatsApp as the broadcast channel.
Beyond the phone number column, there will be additional column headers for any attributes or placeholders used in the template message. These columns will follow the format "user.attribute_N," where N starts from 0 and increments for each subsequent attribute (e.g., user.attribute_0, user.attribute_1, and so on).
To ensure that the phone number is in the correct format, it is necessary to include the "+" symbol followed by the country code preceding the phone number itself.
This standardized formatting is crucial for the successful delivery of the broadcast messages.
When using the external broadcast API, it's important to be aware of the various response codes that may be returned. Some common response codes include:
- 1000, "SUCCESS": Indicates that the API call was successful.
- 2000, "FAILURE": An unhandled error occurred during the process.
- 2003, "BOT_NOT_FOUND": The provided botkey does not match any Engati bot.
- 2004, "API_KEY_NOT_FOUND": The 360dialog configuration is not set up correctly.
- 2005, "INVALID_FILE_FORMAT": The uploaded file is not in the expected CSV format.
- 2006, "FILE_UPLOAD_FAILED": There was an error during the CSV file upload, or the file size exceeds the allowed limit.
By adhering to the CSV file structure guidelines, including the correct column headers, phone number formatting, and attribute columns, you can effectively leverage the external broadcast API to send personalized messages to your target audience.
Understanding the potential response codes can also aid in troubleshooting and ensuring a smooth broadcast experience.
If you face any issues or queries please reach out to us at [email protected]
