External Broadcast API

1. Introduction

This feature allows you to trigger a broadcast from outside the engati platform for a list of users in one go. This avoids using the API to send a template message one user at a time.

2. Availability

This feature is available only if WhatsApp is enabled in your account with 360Dialog as your provider. This feature is available with the higher engati plans.

The API can be used to send broadcast with WhatsApp template messages only.

3. Basic Usage

HTTP Method: Post

Request URL: https://api.engati.com/whatsapp-api/v1.0/customer/<customer id>/bot/<bot key>/external/broadcast?broadcast_id=<broadcast name>

Headers:

Authorization: Basic <Auth Token>

Body:

target_audience: CSV file with list of receipients

template_payload: Structure of message to be sent along with parameters

Sample Curl:

curl --location --request POST 'https://api.engati.com/whatsapp-api/v1.0/customer/54314/bot/6872b6150b184ac6/external/broadcast?broadcast_id=PROD_1' \
--header 'Authorization: Basic 8f62e974-c9c8-41f4-9345-035e14b1e692-GmWANEq' \
--form 'target_audience=@"/Users/vrajdesai/Downloads/single_user_for_external_broadcast.csv"' \
--form 'template_payload="{\"namespace\":\"d44848c7_08b0_4a15_9c53_fbe0bc353185\",\"name\":\"table_reservation\",\"language\":{\"code\":\"en\",\"policy\":\"deterministic\"},\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"document\",\"document\":{\"link\":\"https://webstor.srmist.edu.in/web_assets/srm_mainsite/files/2017/Enagati-Poster_SRM.pdf\",\"filename\":\"asdasd.pdf\"}}]},{\"type\":\"button\",\"sub_type\":\"quick_reply\",\"index\":\"0\",\"parameters\":[{\"type\":\"payload\",\"payload\":\"flow_9ACECB154D304276A827352F5FD5DE3A||data_booleanliked=BBB\"}]},{\"type\":\"button\",\"sub_type\":\"quick_reply\",\"index\":\"1\",\"parameters\":[{\"type\":\"payload\",\"payload\":\"flow_4D336055233C4DA1BA782ED1B072BB2E\"}]},{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"{{0}}\"}]}]}"'

4. CSV File structure



While the template_payload is the signature of the template message to be sent, the CSV file contains the values of the parameters included in the template message for all the users in the target_audience

4.1 Column Headers

Since a phone number is mandatory with WhatsApp as the channel, the first column header will always be user.phone_number.

Besides user.phone_number, there will be as many column headers as there are attributes. These will have the format:

user.attribute_N where N starts with 0, so user.attribute_0, user.attribute_1 and so on

4.2 Phone Number

To ensure that the phone number is in the right format, a "+ " should be added in front of the phone number with the country code.

4.3 Response Codes

Some of the common response codes from the API include:

1000, "SUCCESS": Success

2000, "FAILURE" : Unhandled Error

2003, "BOT_NOT_FOUND" : botkey does not match any engati bot

2004, "API_KEY_NOT_FOUND" : 360dialog not properly configured

2005, "INVALID_FILE_FORMAT" : customer does not upload a CSV file

2006, "FILE_UPLOAD_FAILED" : error in uploading CSV file or file is too large

5. Broadcast Status

Once an external broadcast has been triggered, it shows up in Broadcast > Basic Broadcast > Published with the tag (Ext.) highlighting that this broadcast is an external broadcast triggered using our API.



The status of the broadcast will either be In-progress or Completed. The status will however not be auto-refresh. The status can be manuall refreshed by clicking on the "..." options to the right of status and clicking "Update Status"