External Broadcast API

7min

﻿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
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}}\"}]}]}"'
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"
﻿