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 use case use case 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 availability availability 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 setting up up 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 version 1 https //api engati ai/whatsapp api/v1 0/customer/\<customer id>/bot/\<bot key>/external/broadcast?broadcast id=\<broadcast name> version 2 (includes analytics contact support\@engati com support\@engati com for additional enablement) https //api engati ai/bot api/v2 0/customer/\<customer id>/bot/\<bot key>/external/broadcast 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 for version 1 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 in the body enter the below mentioned key and value for version 2 target audience provide the csv file containing the list of recipients that you created in step 5 payload we have added additional details like broadcasttitle, platform, countrycode and along with that, 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 sample curl request version 1 curl location request post 'https //api engati ai/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}}\\"}]}]}"' sample curl request version 2 curl location 'https //api engati ai/bot api/v2 0/customer/92064/bot/634dff0821d4424e/external/broadcast' \\ \ header 'accept application/hal+json' \\ \ header 'content type application/json' \\ \ header 'authorization basic 30ff7980 cfc5 4c70 8e23 41aa039a9695 hrppxef' \\ \ form 'target audience=@"/users/nitishkumar/downloads/sample contactlist file attributes csv"' \\ \ form 'payload="{\\"broadcasttitle\\" \\"test external attributes 02\\",\\"payload\\" {\\"content\\" \[{\\"template\\" {\\"payload\\" {\\"namespace\\" \\"bffff98d 69a9 4bb7 bb7d cfd0f81b1aa2\\",\\"name\\" \\"nitish attributes copy\\",\\"components\\" \[{\\"type\\" \\"body\\",\\"parameters\\" \[{\\"type\\" \\"text\\",\\"text\\" \\"{{power}}\\"}]}],\\"language\\" {\\"code\\" \\"en us\\",\\"policy\\" \\"deterministic\\"}}},\\"type\\" \\"template\\"}],\\"type\\" \\"whatsapp template\\"},\\"platform\\" \\"dialog360\\",\\"countrycode\\" \\"in\\"}"' csv file structure csv file structure 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 for version 2 , we support the same csv structure that we support for ' import contact list' on our platform column headers 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) phone number 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 response codes 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 mailto\ support\@engati com