Creating and Sending SMS Broadcast

Create and send an SMS broadcast to every contact in a Contact List with a single API request.

Before you begin

Create a Contact List with a column that stores each contact's mobile number.
Copy the list's unique identifier (listId). You use this ID to target the contacts in that list.

Send an SMS broadcast

The following request sends "Hi [[name]]. This is a test" to every contact in the list. Use placeholders inside double square brackets ([[...]]) to insert dynamic content for each message when it is sent.

For example:

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 contact list. Therefore, the information contained in that column will be sent to each contact.

Send the broadcast with the following request:

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
}

Request parameters

The following table describes the request body parameters:

Parameter	Required	Description
deliveryMethod	Yes	Specifies the type of delivery channel which the message will be sent: `"SMS"` ,`"EMAIL"`, `"RCS"`, `"WHATSAPP"`. In this case, we enter the `"SMS"` value to send the SMS message.
campaignName	Yes	Name of the broadcast used as the main identifier.
description	Yes	Description of the broadcast.
listId	Yes	Enter the unique identifier of the list which contains the Recipients (contacts) of the broadcast.
listField	Yes	Name of the column defined when creating the contact list that contains the mobile numbers of the contacts.
message	Yes	Content of the SMS message that will be sent to the contacts. 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. For details about character encoding and how special characters affect SMS segmentation, see the Encoding & Optimization for Multilingual SMS Encoding & Optimization for Multilingual SMS section. 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 contact list. Therefore, the information contained in that column will be sent to each contact.
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.

Response

After you create and send the SMS broadcast, 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
  }
}

Response parameters

The following table describes the response body parameters:

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"`, `"RCS"`, `"WHATSAPP"`. In this case, we enter the `"SMS"` value to send the SMS message.
data. campaignName	Name of the broadcast used as the main identifier.
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 (contacts) of the broadcast.
data. listSize	Total number of lines read in the list.
data. listField	Name of the column defined when creating the contact list that contains the mobile numbers of the contacts.
data. message	Content of the SMS message that will be sent to the contacts. 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. For details about character encoding and how special characters affect SMS segmentation, see the Encoding & Optimization for Multilingual SMS Encoding & Optimization for Multilingual SMS section. 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 contact list. Therefore, the information contained in that column will be sent to each contact.
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.