The last step in the Main Broadcast Screen before creating your broadcast is the ‘Use File’ control that will upload your broadcast file. Your broadcast file contains the phone numbers and and other optional parameters for your broadcast.

General Guidelines

  • Standard CSV format rules must be followed. It is recommended to review all files with a basic text editor (e.g. n++).
  • All columns must be separated by delimiters. Accepted delimiters are semicolon, comma, and pipe sign. Do not mix delimiters.
  • For all CSV filenames, follow these guidelines:
    • No special characters or spaces
    • Use capitals and underscores instead of periods, spaces, slashes, etc.
    • Use date format: ISO 8601: YYYYMMDD
  • Information that is entered in the UI will overwrite the information in the uploaded broadcast file (e.g. if a message is entered in the UI, it will overwrite any message(s) contained in the uploaded file).

Saving a CSV File

Save as a standard CSV file.

Maximum File Size

The maximum standard file size for the production SMS Broadcast system is 500,000 records (rows in the CSV file).

Broadcast File Formatting

File Header

The first row of the CSV file that contains the column titles is called the file header. An example of a basic file header with two messages to be sent:

Phone_number Message Date_time <- file header
16175551212 Happy New Year! 01-01-2020: 00:00
17812221212 Happy New Year! 01-01-2020: 00:00

Parameters

The SMS Broadcast Service supports a number of parameters. ‘Phone_number’ is the only required parameter in the Broadcast file. ‘Message’ may uploaded in the Broadcast file for entered in the UI. Optional parameters allow for configuration of future send times, personalized messages (using templates and variables), and meta-data (used for message/contact tracking).

No. Column Required Format Description
01 Phone_number Yes 10 – 15-digit number Destination phone number with country code (e.g. 16175551212 for a USA number)
02 Message No string Message to be sent to the mobile phone. Messages can be added to the Broadcast file or entered in the UI. To accommodate special characters, double (non-shaped) quotes are highly recommended.
03 Date_time Optional MM-DD-YYYY: HH:mm
M-D-YY: HH:mm HH:MM
Message send time.
If blank, broadcast will start immediately.
If MM-DD-YYYY is missing, current date will be used.
Time is in 24-hour format.
Individual Date_time line items must be in chronological order.
04 Source_number Optional 5 – 15 digit number The transport code that ‘sends’ the message
05 Throughput Optional 1, 10, 100, 1000 The speed (in messages per minute) at which the entire file is sent. May only be used as a default parameter (the throughput number applies to the entire file)
06 Param1
Param2
Optional string Parameters are values inserted in template messages.
The default parameter message is used as the template, the strings specified as parameters are then inserted. See Template Messages section for more info.
06 Agent_id Optional number or string (e.g. ABC123) Optional parameter for integration with call center platforms.
If present, the value will be associated with inbound traffic for this mobile number.
07 User_id Optional number or string (e.g. ABC123) Optional parameter for integration with call center platforms.
If present, the value will be associated with inbound traffic for this mobile number.
08 Template Optional string Optional parameter for using pre-defines templates instead of a message copy. Is used INSTEAD of Message
09 Meta_data1 Optional number or string (e.g. ABC123) Optional non-messaging related parameter for linking external data to a specific message, especially useful for reporting purposes

Phone_number (required): The destination phone number with country code (e.g. 16175551212).

Message: The message to send. If only the first message is specified, it will be the default for all other messages. If there are special characters in the message (#,@,$,%, etc.), the message must be formatted within double quotes (non-shaped). See Appendix A for details on message lengths, encoding, and concatenation.

Date_time: If the date_time parameter is missing, the message will be sent immediately. Format for date_time is MM-DD-YYYY: hh:mm. If specifying individual Date_time send times for each message, the entries must be in chronological order in the broadcast file.

Source_number: For accounts the multiple source numbers (the ‘From’ number when sending a message), a specific source number may be designated with this parameter. Only numbers that have been assigned to an account may be used.

Throughput: Messages per minute that the broadcast file will be sent. When messages include a call-to-action (e.g._ “call or text now…”_), customer service managers often prefer to send messages at a slower rate to spread out call center traffic. Throughput may be set either in the UI or in the broadcast file.

Param1, Param2,…: User-defined parameters inserted in message templates for personalized SMS messages. Up to ten (10) different user-defined parameters can be used. Refer to Message Template section for more information.

Agent_id and User_id: Tracking information that is logged with individual outbound messages. This information is used by call center and CRM systems for routing and tracking purposes.

Template: Template is an optional parameter that replaces Message. Templates can be generated and modified in the UI and used instead of the message copy. By using templates, the message will be the same for all subscribers in your broadcast (with the exception of the dynamic parameters you specify as placeholders). If you’re using a broadcast file and want to use templates, the template must already exist in the UI.

Meta_data1: Similar to Agent_id, Meta_data1 is a more generic optional parameter to link external information to specific messages. The most common use case is adding subscriber specific information to outbound messages to link messages back to reporting data. Meta_data1 information is also useful for integrations with external systems (CRM systems, contact center platforms, etc.).

Default Parameters

An easy shortcut for sending the same message to all numbers is to use default parameters. The first record (the line immediately following the header line) contains the default parameters for all broadcast messages. Default parameters can also be used for creating templates with variables (see section on user-defined parameters).

Example of a basic CSV file using default parameters:

Phone_number Message Date_time
16175551212 Happy New Year! 01-01-2020: 00:00 <- default parameters go in this line
17812221212
18083219876

Because subsequent lines are blank, all numbers will be sent the same “Happy New Year!” message when the clock strikes midnight.

Using dynamic parameters

Dynamic messages can be created by using parameters. The parameters get inserted as specified by the param1, param2,… placeholders.
You can use up to 10 parameters. User-defined parameters are preceded by a dollar sign and enclosed in curly braces. Example: ${param1}.

Phone_number Message Param1 Param2
16175551212 Hello ${param1}, your balance is ${param2}. John $1,500
17812221212 Peter $950

The two resulting messages sent would be
“Hello John, your balance is $1,500.” and
“Hello Peter, your balance is $950.”

Using pre-defined templates

Templates can be uploaded and modified in the UI to provide an easy way of re-using static message content. If you use the optional Template header in your broadcast file, you can specify a specific template by its template name and the broadcast will use the template as the message body. You can even combine this with optional parameters for dynamic text parts.

Phone_number Template
16175551212 Maintemplate1
17812221212
Phone_number Template Param1 Param2
16175551212 Maintemplate1 John $1,500
17812221212 Peter $950

Linking meta data to your outbound messages

In this simple example, a subscriber ID is linked to each message and can then be retrieved together with the send status within the reporting options.

Phone_number Message Meta_data1
16175551212 Hello, this is an info message A123127021
17812221212 Hello, this is an info message B234233023

Additional CSV File Examples

It is always highly recommended to test your files before you schedule large broadcasts, especially if you are using complex file structures and advanced features.

1. Basic CSV File

Phone_number Message
16175551212 Hello!
17812221212 Hello!

These two messages will be sent immediately as no date_time is designated.

2. Basic CSV File with Date-time

Phone_number Message Date_time
16175551212 Merry Christmas 12-25-2022: 12:00
17812221212 Happy New Year 01-01-2023: 00:00

These two messages will be sent at different times.

3. CSV File with Message Template, Throughput, Parameters, and Agent_id

Phone_number Message Date_time Source_number Throughput Param1 Param2 Agent_id
16175551212 Hello ${param1}, your balance is ${param2}. 01-12-2022: 12:00 18002311234 1 John $1,500 agent5
17812221212 01-25-2022: 17:00 18889877896 Peter $950 agent27

The two resulting messages sent 1 minute apart would be:
“Hello John, your balance is $1,500.” sent from (800) 231-1234 to (617) 555-1212 on January 12, 2022 at noon.
“Hello Peter, your balance is $950.” sent from (888) 987-7896 to (781) 222-1212 on January 25, 2022 at 5pm.
Any reply messages from John or Peter will be tagged with their respective agent IDs for routing to a specific agent for SMS chat.

Revision: 32
Last modified: 10 January 2024