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: In this case, we enter the |
| 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 ( |
| 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
By default is |
| broadcastDate | No |
Applies only when the 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: In this case, we enter the |
| 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 ( |
| data. origin |
Source address of the broadcast. |
| data. broadcastDate |
Optional. Applies only when the 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:
|
| data. createdAt |
Date when the broadcast was created and sent . |
| data. scheduleWithoutDate |
Date & Time of your broadcast
By default is |
| data. throttle |
Optional. Message delivery speedometer. By default, 250 messages are sent per second. |
| data. notSentCounter |
Total unsent messages. |
| data. messagesSentCounter |
Total sent messages. |
Updated 1 day ago