Broadcast

Suggest Edits

A Broadcast campaign is a messaging service that allows sending messages to specific distribution groups delivered via SMS, Email, or Push.

Broadcasts serve as a way to accelerate the flow of data and information across a company or a large network of members. Organizations make use of broadcasts to communicate en-masse. This enables enterprise companies to relay important messages to their customers for informational or marketing purposes.

This API allows you to create and send bulk messages to subscribers who are included in a specific list previously created. These messages will be delivered through the desired delivery channel.

You can create and send five types of Broadcast:

  • SMS
  • Email
  • Push notification (Under Construction)
  • RCS (Under Construction)
  • WhatsApp

📘

NOTE

Before creating and sending multiple messages, you need to create a Subscriber List.

The Subscriber List will help you list the subscribers you want to send the messages to.

The Subscriber List must contain the column where it will include the necessary information to be able to send the broadcast according to the delivery channel. For example, if you want to send SMS messages, the column must contain the mobile numbers of each subscriber listed.

Creating and Sending SMS Broadcast

This endpoint allows you to create and send multiple SMS messages in a single API request.

Before creating and sending bulk SMS messages you need to:

  • Create a Subscriber List that contains a column where store the mobile numbers of the subscribers.
  • Once created the subscriber list, copy the unique identifier of the list ("listId"). This id will help you to send the messages to the subscribers that are added in that list.

In the following request body example, we are going to send this message "Hi [[name]]. This is a test" for each subscriber contained in the list. The message includes a placeholder value. This placeholder can be replaced with dynamic content inside double curly braces ([[...]]) when a message is sent.

Example of a sent SMS message using placeholders:

  • Hi! {{name}}, your purchase code is {{CODE}}
  • Hi! Katerina, your purchase code is 242527

📘

NOTE

The placeholder parameter is the name of the column defined when creating the subscriber list. Therefore, the information contained in that column will be sent to each subscriber.

When you create and sending multiple SMS messages (Broadcast), the request body contains the following data:

HTTP Request: POST /broadcasts

{
  "deliveryMethod": "SMS",
  "campaignName": "SMS Broadcast",
  "description": "Sending Broadcast now",
  "listId": 95650,
  "listField": "mobile",
  "message": "Hi [[name]]. This is a test",
  "origin": "14155824559",
  "scheduleWithoutDate": false
}

The parameters presented in the request body example when creating and sending the multiple SMS messages are the following:

Parameter Required Description
deliveryMethod Yes

Specifies the type of delivery channel which the message will be sent: "SMS" ,"EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "SMS" value to send the SMS message.
campaignName Yes

Name of the campaign, used as the main identifier for the broadcast.
description Yes

Description of the broadcast.
listId Yes

Enter the unique identifier of the list which contains the Recipients (subscribers) of the broadcast.
listField Yes

Name of the column defined when creating the subscriber list that contains the mobile numbers of the subscribers.

message Yes

Content of the SMS message that will be sent to the subscribers.

The maximum length of a short message text is 160 characters using the default GSM 03.38 alphabet. If you use any character that is not in the default alphabet, the message will be encoded in Unicode and will be divided in segments of a maximum of 70 characters each. For example, if you include an emoji in your message and the message is 150 characters long, it will be divided into three segments: the first one with 70 characters, the second one with 70 characters and the third one with just 10 characters.

You will be charged per segment, not per message.

Placeholder values must be replaced with dynamic content inside double curly braces ([[...]]). The placeholder parameter is the name of the column defined when creating the subscriber list. Therefore, the information contained in that column will be sent to each subscriber.
origin Yes

Source address of the broadcast.

Specifies the Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier.

If you don't have one assigned yet please contact our support team to request one.
scheduleWithoutDate Yes

Define the Date & Time of your broadcast

  • true: Define the date and time when sending the SMS messages.

  • false: Send the SMS messages once the API Call is executed.

By default is false
broadcastDate No

Applies only when the "scheduleWithoutDate" is true. That is, when you want to define the date and time when sending the SMS messages.

Set the date and time when the SMS messages will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

If you do not set the date, the sending of the broadcast will be pending.
segmentId No

Unique identifier of the segment.
filters No

Set the filter you want to apply on the message.
filterName No

Filter Name. The content is the name of the filter applied on the message.
throttle No

Message delivery speedometer.

By default, 250 messages are sent per second.

When you created and sent the multiple SMS messages, the response body contains the following data:


{
  "meta": {
    "timestamp": 1689873202279,
    "transactionId": "92aef322-3efd-49bf-9b1d"
  },
  "data": {
    "id": 84274,
    "beginDate": "2023-07-20T17:13:22.251099990Z",
    "deliveryMethod": "SMS",
    "campaignName": "SMS Broadcast",
    "createdBy": "[email protected]",
    "operator": "[email protected]",
    "description": "Sending Broadcast now",
    "listId": 95650,
    "listSize": 1,
    "listField": "mobile",
    "message": "Hi [[name]]. This is a test",
    "origin": "14155824559",
    "broadcastDate": "2023-07-20T17:13:22.251099727Z",
    "broadcastStatus": "SENDING",
    "createdAt": "2023-07-20T17:13:22.246499085Z",
    "scheduleWithoutDate": false,
    "throttle": 250,
    "notSentCounter": 1,
    "messagesSentCounter": 0
  }
}

Parameters presented in the response body example when creating and sending the multiple SMS messages are the following:

Parameter Description
data Data contained once the broadcast was created and sent.
data.id Unique identifier of the broadcast.
data.beginDate Date on which the creation and sending of the Broadcast begins.
data.deliveryMethod

Specifies the type of delivery channel which the message will be sent: "SMS" ,"EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "SMS" value to send the SMS message.
data.campaignName

Name of the campaign, used as the main identifier for the broadcast.
data.createdBy

User who created and sent the broadcast.
data.operator

User who is a member of the owner or creator of the broadcast.
data.description

Description of the broadcast.
data.listId

Unique identifier of the list which contains the Recipients (subscribers) of the broadcast.
data.listSize

Total number of lines read in the list.
data.listField

Name of the column defined when creating the subscriber list that contains the mobile numbers of the subscribers.
data.message

Content of the SMS message that will be sent to the subscribers.

The maximum length of a short message text is 160 characters using the default GSM 03.38 alphabet. If you use any character that is not in the default alphabet, the message will be encoded in Unicode and will be divided in segments of a maximum of 70 characters each. For example, if you include an emoji in your message and the message is 150 characters long, it will be divided into three segments: the first one with 70 characters, the second one with 70 characters and the third one with just 10 characters.

You will be charged per segment, not per message.

Placeholder values must be replaced with dynamic content inside double curly braces ([[...]]). The placeholder parameter is the name of the column defined when creating the subscriber list. Therefore, the information contained in that column will be sent to each subscriber.
data.origin

Source address of the broadcast.
data.broadcastDate

Optional. Applies only when the "scheduleWithoutDate" is true. That is, when you want to define the date and time when sending the SMS messages.

Set the date and time when the SMS messages will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

If you do not set the date, the sending of the broadcast will be pending.
data.broadcastStatus

When the broadcast is created and sent, the system assigns one of the following possible statuses to a Broadcast:

  • "DONE": Broadcast sent.

  • "PENDING": The broadcast was created without a sending date → scheduleWithoutDate in true.

  • "SCHEDULE": scheduled delivery.

  • "SENDING": sending in progress.

  • "SUSPENDED": sending suspended (the broadcast was scheduled and was suspended)

  • "PAUSE": sending paused/stopped (the broadcast was in progress and was paused). Everything that was in transit will be processed.

  • "DONE_WITH_FLAWS": eady sent. Some recipients did not have the sending field (email or phone number).

  • "FATAL_ERROR": execution error. Contact support.
data.createdAt

Date when the broadcast was created and sent .
data.scheduleWithoutDate

Date & Time of your broadcast

  • true: Define the date and time when sending the SMS messages.

  • false: Send the SMS messages once the API Call is executed.

By default is false
data.throttle

Optional. Message delivery speedometer.

By default, 250 messages are sent per second.
data.notSentCounter

Total unsent messages.
data.messagesSentCounter

Total sent messages.

Creating and Sending Email Broadcast

This endpoint allows you to create and send multiple Email messages in a single API request.

Before creating and sending bulk Email messages you need to:

  • Create a Subscriber List that contains a column which stores the emails of the subscribers.
  • Once created the subscriber list, copy the unique identifier of the list (“listId”). This id will help you to send the messages to the subscribers that are added in that list.

In the following request body example, we are going to send this message "Welcome to EliPackage! This is a test" for each subscriber contained in the list.

When you create and sending multiple Email messages (Broadcast), the request body contains the following data:

HTTP Request: POST /broadcasts

{
  "deliveryMethod": "EMAIL",
  "campaignName": "Email Broadcast",
  "description": "Sending Broadcast now",
  "listId": 95830,
  "listField": "email",
  "message": "<p>Welcome to EliPackage!</p> <p>This is a test</p>",
  "origin": "[email protected]",
  "scheduleWithoutDate": false,
  "subject": "Email Test"
}

The parameters presented in the request body example when creating and sending the multiple Email messages are the following:

Parameter Required Description
deliveryMethod Yes

Specifies the type of delivery channel which the message will be sent: "SMS" ,"EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "EMAIL" value to send the Email message.
campaignName Yes

Name of the campaign, used as the main identifier for the broadcast.
description Yes

Description of the broadcast.
listId Yes

Enter the unique identifier of the list which contains the Recipients (subscribers) of the broadcast.
listField Yes

Name of the column defined when creating the subscriber list that contains the emails of the subscribers.

message Yes

Content of the Email message that will be sent to the subscribers. This can be a simple text or HTML format.
origin Yes

Source address of the broadcast.
scheduleWithoutDate Yes

Define the Date & Time of your broadcast

  • true: Define the date and time when sending the Email messages.

  • false: Send the Email messages once the API Call is executed.

By default is false
subject Yes

Headline of the email.
broadcastDate No

Applies only when the "scheduleWithoutDate" is true. That is, when you want to define the date and time when sending the SMS messages.

Set the date and time when the SMS messages will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

If you do not set the date, the sending of the broadcast will be pending.
filters No

Set the filter you want to apply on the message.
filterName No

Filter Name. The content is the name of the filter applied on the message.
throttle No

Message delivery speedometer.

By default, 160 messages are sent per second.
clientId No

Unique user identifier that can be used for reporting purposes.

When you created and sent the multiple Email messages, the response body contains the following data:

{
  "meta": {
    "timestamp": 1689879000421,
    "transactionId": "98835d43-46a0-474b-a768"
  },
  "data": {
    "id": 84288,
    "beginDate": "2023-07-20T18:50:00.383688185Z",
    "deliveryMethod": "EMAIL",
    "campaignName": "Email Broadcast",
    "createdBy": "[email protected]",
    "operator": "[email protected]",
    "description": "Sending Broadcast now",
    "listId": 95830,
    "listSize": 1,
    "listField": "email",
    "message": "<p>Welcome to EliPackage!</p> <p>This is a test</p>",
    "origin": "[email protected]",
    "broadcastDate": "2023-07-20T18:50:00.383677863Z",
    "broadcastStatus": "SENDING",
    "createdAt": "2023-07-20T18:50:00.378087288Z",
    "scheduleWithoutDate": false,
    "throttle": 160,
    "notSentCounter": 1,
    "messagesSentCounter": 0,
    "subject": "Email Test"
  }
}

Parameters presented in the response body example when creating and sending the multiple Email messages are the following:

Parameter Description
data Data contained once the broadcast was created and sent.
data.id Unique identifier of the broadcast.
data.beginDate Date on which the creation and sending of the Broadcast begins.
data.deliveryMethod

Delivery channel which the message will be sent: "SMS" ,"EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "EMAIL" value to send the EMAIL message.
data.campaignName

Name of the campaign, used as the main identifier for the broadcast.
data.createdBy

User who created and sent the broadcast.
data.operator

User who is a member of the owner or creator of the broadcast.
data.description

Description of the broadcast.
data.listId

Unique identifier of the list which contains the Recipients (subscribers) of the broadcast.
data.listSize

Total number of lines read in the list.
data.listField

Name of the column defined when creating the subscriber list that contains the emails of the subscribers.
data.message

Content of the Email message that will be sent to the subscribers. This can be a simple text or HTML format.
data.origin

Source address of the broadcast.
data.broadcastDate

Optional. Applies only when the "scheduleWithoutDate" is true. That is, when you want to define the date and time when sending the Email messages.

Set the date and time when the Email messages will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

If you do not set the date, the sending of the broadcast will be pending.
data.broadcastStatus

When the broadcast is created and sent, the system assigns one of the following possible statuses to a Broadcast:

  • "DONE": Broadcast sent.

  • "PENDING": The broadcast was created without a sending date → scheduleWithoutDate in true.

  • "SCHEDULE": scheduled delivery.

  • "SENDING": sending in progress.

  • "SUSPENDED": sending suspended (the broadcast was scheduled and was suspended)

  • "PAUSE": sending paused/stopped (the broadcast was in progress and was paused). Everything that was in transit will be processed.

  • "DONE_WITH_FLAWS": eady sent. Some recipients did not have the sending field (email or phone number).

  • "FATAL_ERROR": execution error. Contact support.
data.createdAt

Date when the broadcast was created and sent .
data.scheduleWithoutDate

Date & Time of your broadcast

  • true: Define the date and time when sending the Email messages.

  • false: Send the Email messages once the API Call is executed.

By default is false
data.throttle

Optional. Message delivery speedometer.

By default, 160 messages are sent per second.
data.notSentCounter

Total unsent messages.
data.messagesSentCounter

Total sent messages.
data.subject

Headline of the email.

Creating and Sending WhatsApp Broadcast

This endpoint allows you to create and send a WhatsApp message template to multiple subscribers in a single API request.

Before creating and sending bulk WhatsApp messages you need to:

  • Created a WhatsApp Message Template (Text, Media or Regular) that was approved by META previously.
  • Create a Subscriber List that contains a column which stores the messages of the subscribers.
  • Once created the subscriber list, copy the unique identifier of the list ("listId"). This id will help you to send the message to the subscribers that are added in that list.

In the following request body example, we are going to send a WhatsApp message templated previously approved by META for each subscriber contained in the list.

When you create and sending a WhatsApp message template to multiple subscribers (Broadcast), the request body contains the following data:

HTTP Request: POST /broadcasts

{
  "deliveryMethod": "WHATSAPP",
  "campaignName": "WhatsApp Broadcast",
  "description": "Sending Broadcast now",
  "listId": 95650,
  "listField": "mobile",
  "origin": "17542163412",
  "scheduleWithoutDate": false,
  "whatsappTemplateName": "whatsapp_new_chetna",
  "whatsappTemplateNameSpace": "233c8cc8",
  "whatsappTemplateLanguage": "en",
  "whatsappTemplateId": "5624"
}

The parameters presented in the request body example when creating and sending the WhatsApp message template are the following:

Parameter Required Description
deliveryMethod Yes

Specifies the type of delivery channel which the message will be sent: "SMS" ,"EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "WHATSAPP" value to send the SMS message.
campaignName Yes

Name of the campaign, used as the main identifier for the broadcast.
description Yes

Description of the broadcast.
listId Yes

Enter the unique identifier of the list which contains the Recipients (subscribers) of the broadcast.
listField Yes

Name of the column defined when creating the subscriber list that contains the mobile numbers of the subscribers.

Mobile numbers are specified in E.164 format → (‘+’ and a country code).
message Yes

Applies only when sending a Regular Message.

Content of the regular message that will be sent to the subscribers.

If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window to send the regular message, without using a template.
origin Yes

Source address of the broadcast.

Phone number provided during the WABA account setup will be used as the sender of the broadcast.

Only accepts numeric characters. Do not include the "+" sign.
scheduleWithoutDate Yes

Define the Date & Time of your broadcast

  • true: Define the date and time when sending the WhatsApp template.

  • false: Send the WhatsApp template once the API Call is executed.

By default is false
whatsappTemplateName Yes

Applies only when sending a WhatsApp Message Template.

Name of the template created in your WhatsApp Business Account.
whatsappTemplateNameSpace Yes

Applies only when sending a WhatsApp Message Template.

Template Namespace value. Identifies message templates belonging to the account.
whatsappTemplateLanguage Yes

Applies only when sending a WhatsApp Message Template.

Language of the WhatsApp message template.

  • English: "en", "en_GB", "en_US"

  • Spanish: "es", "es_AR", "es_ES", "es_MX"

  • Portuguese: "pt_BR", "pt_PT"
whatsappTemplateId Yes

Applies only when sending a WhatsApp Message Template.

Unique identifier of the whatsApp message template.
broadcastDate No

Applies only when the "scheduleWithoutDate" is true. That is, when you want to define the date and time when sending the WhatsApp message template.

Set the date and time when the WhatsApp message template will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

If you do not set the date, the sending of the broadcast will be pending.
segmentId No

Unique identifier of the segment.
filters No

Set the filter you want to apply on the message.
filterName No

Filter Name. The content is the name of the filter applied on the message.
throttle No

Message delivery speedometer.

By default, 250 messages are sent per second.
clientId No

Unique user identifier that can be used for reporting purposes.

When you created and sent the WhatsApp message template, the response body contains the following data:

{
  "meta": {
    "timestamp": 1689906776296,
    "transactionId": "98bc7263-47cf-4217-9d22"
  },
  "data": {
    "id": 84382,
    "beginDate": "2023-07-21T02:32:56.244598259Z",
    "deliveryMethod": "WHATSAPP",
    "campaignName": "WhatsApp Broadcast",
    "createdBy": "[email protected]",
    "operator": "[email protected]",
    "description": "Sending Broadcast now",
    "listId": 95650,
    "listSize": 1,
    "listField": "mobile",
    "origin": "17542163412",
    "broadcastDate": "2023-07-21T02:32:56.244597906Z",
    "broadcastStatus": "SENDING",
    "createdAt": "2023-07-21T02:32:56.176551918Z",
    "scheduleWithoutDate": false,
    "throttle": 250,
    "notSentCounter": 1,
    "messagesSentCounter": 0,
    "whatsappConfig": {
      "whatsappTemplateName": "whatsapp_new_chetna",
      "whatsappTemplateNameSpace": "233c8cc8_145a_48de_83fa_f4c78d01465a",
      "whatsappTemplateLanguage": "en",
      "whatsappTemplateId": "562464325983702"
    }
  }
}

Parameters presented in the response body example when creating and sending the WhatsApp message template are the following:

Parameter Description
data Data contained once the broadcast was created and sent.
data.id Unique identifier of the broadcast.
data.beginDate Date on which the creation and sending of the Broadcast begins.
data.deliveryMethod

Delivery channel in which the message will be sent: "SMS" ,"EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "WHATSAPP" value to send the WhatsApp message template.
data.campaignName

Name of the campaign, used as the main identifier for the broadcast.
data.createdBy

User who created and sent the broadcast.
data.operator

User who is a member of the owner or creator of the broadcast.
data.description

Description of the broadcast.
data.listId

Unique identifier of the list which contains the Recipients (subscribers) of the broadcast.
data.listSize

Total number of lines read in the list.
data.listField

Name of the column defined when creating the subscriber list that contains the mobile numbers of the subscribers.

Mobile numbers are specified in E.164 format → (‘+’ and a country code).
data.message

Applies only when sending a Regular Message.

Content of the regular message that will be sent to the subscribers.

If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window to send the regular message, without using a template.
data.origin

Source address of the broadcast.

Phone number provided during the WABA account setup will be used as the sender of the broadcast.

Only accepts numeric characters. Do not include the "+" sign.
data.broadcastDate

Optional. Applies only when the "scheduleWithoutDate" is true. That is, when you want to define the date and time when sending the WhatsApp message template.

Set the date and time when the WhatsApp message template will be sent in UTC format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

If you do not set the date, the sending of the broadcast will be pending.
data.broadcastStatus

When the broadcast is created and sent, the system assigns one of the following possible statuses to a Broadcast:

  • "DONE": Broadcast sent.

  • "PENDING": The broadcast was created without a sending date → scheduleWithoutDate in true.

  • "SCHEDULE": scheduled delivery.

  • "SENDING": sending in progress.

  • "SUSPENDED": sending suspended (the broadcast was scheduled and was suspended)

  • "PAUSE": sending paused/stopped (the broadcast was in progress and was paused). Everything that was in transit will be processed.

  • "DONE_WITH_FLAWS": eady sent. Some recipients did not have the sending field (email or phone number).

  • "FATAL_ERROR": execution error. Contact support.
data.createdAt

Date when the broadcast was created and sent .
data.scheduleWithoutDate

Date & Time of your broadcast

  • true: Define the date and time when sending the WhatsApp message template.

  • false: Send the WhatsApp message template once the API Call is executed.

By default is false
data.throttle

Optional. Message delivery speedometer.

By default, 15 messages are sent per second.
data.notSentCounter

Total unsent messages.
data.messagesSentCounter

Total sent messages.
data.whatsappConfig

Data contained when sending a Whatsapp message template.
data.whatsappConfig.whatsappTemplateName

Applies only when sending a WhatsApp Message Template.

Name of the template created in your WhatsApp Business Account.
data.whatsappConfig.whatsappTemplateNameSpace

Applies only when sending a WhatsApp Message Template.

Template Namespace value. Identifies message templates belonging to the account.
data.whatsappConfig.whatsappTemplateLanguage

Applies only when sending a WhatsApp Message Template.

Language of the WhatsApp message template.

  • English: "en", "en_GB", "en_US"

  • Spanish: "es", "es_AR", "es_ES", "es_MX"

  • Portuguese: "pt_BR", "pt_PT"
data.whatsappConfig.whatsappTemplateId

Applies only when sending a WhatsApp Message Template.

Unique identifier of the whatsApp message template.

Updated 9 months ago