External Broadcast API

18 min

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 \ 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\ to access this feature, ensure the required channel is enabled in your account supported channels whatsapp rcs for whatsapp, 360dialog must be configured as the provider this feature is exclusively available with higher engati plans the external broadcast api supports sending template based broadcast messages to existing users across supported channels \setting\ \up \ (whatsapp) 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 "phone no" 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 ai\ 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\\"}"' \setting up \ (rcs) the api supports rcs template based broadcasts using approved rcs templates for rcs broadcasts create and publish the broadcast from the platform navigate to the api logs section copy the generated template payload use the copied payload while triggering the external broadcast api sample curl request csv contact list curl location 'https //api engati ai/bot api/v2 0/customer/\<customer id>/bot/\<bot key>/external/broadcast' \\ \ header 'authorization basic \<api key>' \\ \ header 'accept application/hal+json' \\ \ form 'payload="{ "broadcasttitle" "test external broadcast rcs", "payload" { "content" \[ { "template" { "payload" { "contentmessage" { "templatemessage" { "templatecode" "test rcs template", "customparams" "{\n\t\\"postback data 1\\" \\"flow \<flow key>\\",\n\t\\"postback data 2\\" \\"flow \<flow key>\\",\n\t\\"postback data 3\\" \\"flow \<flow key>\\"\n}" } } }, "targetrcsnumber" "{{channel user id}}" }, "type" "template" } ], "type" "rcs template" }, "platform" "rcs", "countrycode" "in" }"' \\ \ form 'target audience=@"/users/tamilarasue/downloads/mobile numbers (1) csv"' sample curl request url contact list curl location 'https //api engati ai/bot api/v2 0/customer/\<customer id>/bot/\<bot key>/external/broadcast/by url' \\ \ header 'authorization basic \<api key>' \\ \ header 'accept application/hal+json' \\ \ form 'payload="{ "broadcasttitle" "test external broadcast rcs", "payload" { "content" \[ { "template" { "payload" { "contentmessage" { "templatemessage" { "templatecode" "test rcs template", "customparams" "{\n\t\\"postback data 1\\" \\"flow \<flow key>\\",\n\t\\"postback data 2\\" \\"flow \<flow key>\\",\n\t\\"postback data 3\\" \\"flow \<flow key>\\"\n}" } } }, "targetrcsnumber" "{{channel user id}}" }, "type" "template" } ], "type" "rcs template" }, "platform" "rcs", "countrycode" "in" }"' \\ \ form 'target audience url="https //mind sides regards connectors trycloudflare com/valid csv"' customparams formatting correct format customparams should be passed as a stringified json "customparams" "{\\"postback data 1\\" \\"value1\\",\\"postback data 2\\" \\"value2\\"}" incorrect format do not pass customparams as a raw json object "customparams" { "postback data 1" "value1" } \\ the external broadcast api supports contact lists in the following formats direct csv file upload contact list url when using a contact list url, the hosted file must follow the same structure and format as the supported csv contact list supported fields include user phone number (phone no) user attributes template variables 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 "phone no," 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 country code preceding the phone number itself this standardized formatting is crucial for the successful delivery of the broadcast messages contact list url support you can now provide a publicly accessible url containing the contact list instead of uploading the csv file directly requirements the url must be publicly accessible the hosted file must follow the supported csv structure column names and formatting should remain unchanged this enables dynamic hosting and external management of broadcast contact lists 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 support\@engati ai mailto\ support\@engati ai