Creating a Broadcast

Introduction

Engati makes it super easy for you to create a Broadcast. Simply go to the Broadcast workflow which is accessible from the left Navigation as Broadcast.

If in case you don’t have an active WhatsApp business number readily available, you can use the "WhatsApp Sandbox" feature to test your bot flow on the WhatsApp channel. Click here to know more.

Note: It would be available only if your bot is not deployed on the WhatsApp channel

To provide you the ease of testing your broadcasts, we’ve made the ‘WhatsApp Sandbox’ and ‘Create New Broadcast’ options available in all three sections i.e. Broadcast History, Scheduled Broadcast, and Draft Broadcasts.



Create New Broadcast

Once you click on the ‘Create new broadcast’ button, it would open a section as below -



While creating a new Broadcast, you must provide the following details -

• Broadcast Name - Provide a name related to the context of your broadcast, it would be useful for your future reference.
• Target Channels - Select the deployed channel that you want to use to send the broadcast.



• Broadcast Type - You get the following options to personalize your broadcast message:

1. Send a Message: This type of broadcast is non-interactive. The receiver will see a Message
2. Send Message with options: This type of broadcast allows the sender to receive input from the receiver
3. Trigger a path: This option takes the receiver through all the flows defined in a path. While creating a new Broadcast, think of it as a way of re-engaging your users and getting them to start interacting with your chatbot again. This means that avoid triggering paths to just deliver a lot of content to users.
4. Send template message (Only for WhatsApp channel - Click here)



• Broadcast Message - For the Send Message and Send Message with options broadcast type, you can add a text message.



• Target segment - There are two options available for selecting your target user group:

1. Contact list (Only for WhatsApp channel) - Select the contact list that you’ve already uploaded or you can upload a new contact list by clicking on the ‘Import Contact List’ option.
2. Segment - Using ‘all users’ option you can include all the users that have previously interacted with your bot or you can select the custom segment created.

• Schedule - As the title suggests, this option allows you to define a set schedule for when you want the broadcast to be initiated/published. You could publish a broadcast as a one-time or recurring occurrence. If recurring you can opt to select the frequency and the time period during which the broadcast will continue to be active.



This feature is available if you have an active WhatsApp setup with – 360Dialog, Kaleyra. Navigate to ‘Configure’ and ‘WhatsApp’ to set up your WhatsApp account. Visit the detailed documentation here, to know how to send whatsapp template messages to the new and existing users

Note: Template messages are charged on per message basis. Please contact your WhatsApp provider or Engati support team (support@engati.com) for more information on the same.

4. Broadcast APIs

4.1 Segment Basic Usage

Navigate to Users page and create a segment.

Click here to learn more about segments

HTTP Method :  Post Request URL   :  https://api.engati.com/bot-api/v1.0/customer/<customerId>/bot/<botkey>/broadcast

(Customer ID, Bot key and Authorization token are available in the Integrations -> Engati API) Headers:

Content-Type : Application/json Authorization : Basic <Auth token>

Body : 

Dynamic parameters

“broadcastTitle”    : Identifier name for the broadcast “channels”              : Channels such as Web users, whatsapp users, mobile app. “segmentName”    : Broadcast will published to users satisfying the attribute condition under this segment. “payload”                : The message type to be sent,  ‘Send message’, ‘Send message with options’ …

Sample Curl Request 

curl --location --request POST 'https://api.engati.com/bot-api/v1.0/customer/51638/bot/3a0cfe2f06cd4bac/broadcast' \
--header 'Authorization: Basic 96abab63-9213-4784-a824-05d834f8c90b-F2vplSP' \
--header 'Content-Type: application/json' \
--data-raw '{
"publishedOn": "2019-06-03T06:48:27.170Z",
"status": "SCHEDULED",
"broadcastId": null,
"broadcastTitle": "testing broadcast",
"audience": {
"rule": {
"channels": [
"web"
],
"segmentName":"name"
}
},
"payload": {
"type": "DIRECT",
"content": [
{
"type": "TEXT",
"data": {
"message": "Welcome Hello World"
}
}
]
},
"scheduledBroadcastModel": null
}'

4.2 Usage Rules

While defining the Broadcast Segment using an API, the below rules have to be kept in mind – Specifying Channels is mandatory If we are sending a DIRECT message on whatsApp , LastActiveAfter is 24hrs. For web LastActiveAfter is 48hrs.

4.3 Direct Message

See an example below of a Broadcast API request for a Direct Message to be sent to users

{
"broadcastId": null,
"broadcastTitle": "testing broadcast",
"publishedOn": "2019-06-03T06:48:27.170Z",
"audience": {
"rule": {
"channels":["whatsapp"],
"channelUserIds":["918951139300"]
}
},
"payload": {
"type": "DIRECT",
"content": [
{
"type": "TEXT",
"data": {
"message": "This is a test message"
}
},
{
"type": "TEXT",
"data": {
"message": "This is another message"
}
}
]
},
"status": null
}

Direct Message with Options See an example below of a Broadcast API request for a Message with options sent to users

{
"broadcastId": null,
"broadcastTitle": "testing broadcast",
"publishedOn": "2019-06-03T06:48:27.170Z",
"audience": {
"rule": {
"userIds": [],
"channelUserIds":["7e84cfe1-5b64-45f8-9d3d-bc158e5d8d31"],
"channels":["web"]
}
},
"payload": {
"type": "FLOW",
"content": [{
"type": "OPTIONS",
"data": {
"message": "Please select a option",
"options": [{
"text": "Option 1",
"postback": "flow_ECD6F99C0FF4427C812543994BDFC213"
},
{
"text": "Option 2",
"postback": "flow_livechat_trigger_5029"
}
]
}
}]
},
"status": null
}

4.4 Set an attribute and send a message (optional) See an example below of a Broadcast API request to set an attribute and send a message

{
"broadcastId": null,
"broadcastTitle": "testing broadcast",
"publishedOn": "2019-06-03T06:48:27.170Z",
"audience": {
"rule": {
"channels":["whatsapp"],
"channelUserIds":["918951139300"]
}
},
"payload": {
"type": "FLOW",
"content": [{
"type": "TEXT",
"data": {
"message": "score:100"
},
"attributes": [{
"name": "attribute name 1",
"value": "attribute Value 1"
},
{
"name": "attribute name 2",
"value": "attribute Value 2"
}
]
}
]
},
"status": null
}

4.5 Trigger a Path and send a message (optional) See an example below of a Broadcast API request to trigger a path and send a message

{
"broadcastId": null,
"broadcastTitle": "testing broadcast",
"publishedOn": "2019-06-03T06:48:27.170Z",
"audience": {
"rule": {
"userIds": [],
"channelUserIds":["7e84cfe1-5b64-45f8-9d3d-bc158e5d8d31"],
"channels":["web"]
}
},
"payload": {
"type": "FLOW",
"content": [{
"type": "TEXT",
"flowKey": "C5019AA6D10D433DA0EE50EF61E69F02",
"data": {
"message": "score:100"
}
}]
},
"status": null
}

4.6 Template Message on Whatsapp Whatsapp typically supports in session messages that are messages, sent to a user who was active with the chatbot in the last 24 hours. For initiating a conversation or notification beyond that time window, you need to send what’s called a message with a defined template. Engati supports sending template messages for Whatsapp using the below API structure. The below API is for Nexmo.

{
"broadcastId": null,
"broadcastTitle": "test_broadcast1312",
"publishedOn": "2019-06-03T06:48:27.170Z",
"audience": {
"rule": {
"userIds": [],
"channelUserIds":["918951139300","919150238942"],
"channels":["whatsapp"]
}
},
"payload": {
"type": "WHATSAPP_TEMPLATE",
"content": [
{
"type": "TEMPLATE",
"template":{
"name":"whatsapp:hsm:technology:nexmo:verify",
"parameters":[
{
"default":"Nexmo Verification"
},
{
"default":"64873"
},
{
"default":"10"
}
]
}
}
]
},
"status": null
}

4.7 Template Message on 360dialog

URL: https://api.engati.com/bot-api/v2.0/customer/<customerId>/bot/<botkey>/broadcast HTTP Method: POST

Header – Authorization: Basic <API Key>

Note: Navigate to Engati APIs to find customer id, bot key and generate API Key

{
"broadcastId": null,
"broadcastTitle": "<name of the broadcast>",
"publishedOn": "2021-10-06T06:48:27.170Z",
"platform" : "whatsapp",
"users" : [{
"phoneNumber" : "+<country code><phone number>",
"email" : "<email of the user",
"organization" : "<organization of the user>",
"title" : "<title of the user",
"lastName" : "<last name of the user>",
"firstName" : "<first name of the user",
"userName" : "<name of the user>"
}],
"payload": {
"type": "DIRECT",
"content": [
{
"type": "TEXT",
"data": {
"message": "Text for Parameter 1"
}
},
{
"type": "TEXT",
"data": {
"message": "Text for Parameter 2"
}
}
]
},
"status": null
}

Below is the explanation of the attributes used above,

For broadcast creation

• broadcastTitle – Broadcast will be created using this name
• publishedOn – Time stamp when broadcast is to be scheduled. Provided time here in UTC, this will be taken as a scheduling time.

For a new user creation

• phoneNumber – Whatsapp number with + and country code – ‘+91979093071’. This is a mandatory field
• email – Email of the user will be set. This is an optional field
• organization – Organization of the user will be set. This is an optional field
• title – Title of the user will be set. This is an optional field
• lastName – Last name of the user will be set. This is an optional field
• firstName – First name of the user will be set. This is an optional field
• userName – Username of the user will be set. This is an optional field

Parameters used will also have to be provided under TEXT.

For media templates you can provide URLs for images, documents and flow keys (5.5 Trigger a path) for buttons, if applicable, like the below script,

{
"broadcastId": null,
"broadcastTitle": "testing broadcast",
"publishedOn": "2021-10-08T03:29:27.170Z",
"platform" : "whatsapp",
"users" : [{
"phoneNumber" : "+91979093071",
"email" : "vaibhav.k@engati.com",
"organization" : "ABC",
"title" : "123",
"lastName" : "Kalra",
"firstName" : "Vaibhav",
"userName" : "Vaibhav K"
}],
"payload": {
"type": "WHATSAPP_TEMPLATE",
"content": [
{
"type": "TEMPLATE",
"template" : {
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "https://s3.ap-south-1.amazonaws.com/file-upload-public/dev/6712/BROADCAST_TEMPLATE_ATTACHMENT/30234-Pagebook.png"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Text for Parameter 1"
}
]
},
{
"type": "button",
"index": 0,
"sub_type": "quick_reply",
"parameters": [
{
"type": "payload",
"payload": "flow_<flow_key>"
}
]
}
],
"namespace": "d44848c7_08b0_4a15_9c53",
"name": "food_delivery_username",
"language": {
"code": "en",
"policy": "deterministic"
}
}
}
]
},
"status": null
}

5. Tracking broadcast status



As a part of the Broadcasts, users will be able to download the target user and failed users list by clicking on their respective statistics number as highlighted in the image. The downloaded file will be available as a CSV and will have the following information,

• User id
• User name
• Email
• Contact number
• Platform/channel (on which the broadcast was sent)
• Timestamp
• Status
• Reason for failure (available only for WhatsApp – 360dialog)

For the sent broadcasts, you get the following options such as:

a. View Broadcast

b. Copy Broadcast

c. Export Broadcast

d. Retry Broadcast



a. View Broadcast -

Once you click on the ‘View Broadcast’ option, it will open a window as shown below



1. Channel - a specific icon for the chosen channel will be displayed.
2. Completion time - It displays the date and time when the broadcast was sent.
3. Target Users - It indicates the count of valid phone numbers or users included in your broadcast's target segment or contact group.
4. Failed Users - It indicates the count of invalid phone numbers or users that are excluded from the target segment or contact group for your broadcast.
5. CTA (URL Clicks) - It shows the count of clicks made by your targeted user group on the CTA (Call-to-Action) button.
6. Sent - The message acknowledged as sent by the channel to the number of users.
7. Delivered - The message acknowledged as delivered by the channel to the number of users.
8. Read - Messages read by the number of users and acknowledged by the channel.
9. Click rate - Messages on which buttons were clicked by your target audience (only button clicks with type as quick reply are captured by WhatsApp)

You also get an option to Retarget the broadcast, Click here to learn more…

b. Copy Broadcast -

You can choose this option if you want to edit and reuse the same broadcast for a different group of users.



Once you click on the ‘Copy Broadcast’ option, it would open a window as shown below - 



c. Export Broadcast -

If you require a detailed report for the sent broadcast, you can generate it by clicking on the 'Export Broadcast' option. This action will trigger the download of a zip file that contains an Excel sheet of your broadcast report. The Excel sheet will provide you with comprehensive information on the broadcast, allowing you to analyze the data and gain insights into the performance of your message.



A downloaded report would look like this -



d. Retry Broadcast - 

In the event that there are any failed users in your sent broadcast, you will have the option to retry the broadcast for those users. To retry the broadcast, simply click on the 'Retry Broadcast' option. This action will allow you to re-initiate the broadcast for the failed users, ensuring that they receive the message as intended.



Click on the ‘confirm’ button to retry the broadcast -