AUTOMATED MESSAGING SERVICE

CUSTOMER GUIDE
Version 2.2
 REVISION HISTORY

Version Date Author Description

2.0.0a 2022-09-14 Joseph D. Purcell First Draft

2.0.0b 2022-09-15 Zach Sherbondy Provider Specific Configuration

2.0.1 2022-09-26 Zach Sherbondy Expand on SMS Summary Section

2.2 2023-03-29 Joseph D. Purcell Add WhatsApp

Five9, Inc. Page 2 2023-03-29

Introduction ................................................................................................................................................................... 5

Providers .................................................................................................................................................................... 5

Using the Application ..................................................................................................................................................... 5

Launch the App via Portal .......................................................................................................................................... 5

Create a Broadcast ..................................................................................................................................................... 6

Common Fields ....................................................................................................................................................... 6

Five9 Fields ............................................................................................................................................................. 7

MMS Fields ............................................................................................................................................................. 7

Twilio Fields ............................................................................................................................................................ 7

WhatsApp Fields..................................................................................................................................................... 8

Upload a List ............................................................................................................................................................... 8

Schedule a Broadcast ................................................................................................................................................. 8

View Activity Details ................................................................................................................................................... 9

Download the SMS Summary .................................................................................................................................... 9

List Format...................................................................................................................................................................... 9

Common Fields ......................................................................................................................................................... 10

Five9 Fields ............................................................................................................................................................... 10

Engagement Workflow......................................................................................................................................... 11

MMS Fields ............................................................................................................................................................... 11

Twilio Fields .............................................................................................................................................................. 11

WhatsApp FIelds ...................................................................................................................................................... 11

Message Templating .................................................................................................................................................... 12

Generic Message Templating................................................................................................................................... 12

Five9 Message Templating ....................................................................................................................................... 13

WhatsApp Message Templating .............................................................................................................................. 14

Configuring Notifications ............................................................................................................................................. 14

Email Notification ..................................................................................................................................................... 15

Five9, Inc. Page 3 2023-03-29

 Webhook Notification .............................................................................................................................................. 15

Consent ........................................................................................................................................................................ 16

Five9 ......................................................................................................................................................................... 16

MMs ......................................................................................................................................................................... 16

Twilio ........................................................................................................................................................................ 16

WhatsApp ................................................................................................................................................................. 16

StoP Requests ........................................................................................................................................................... 17

SMS Summary .............................................................................................................................................................. 17

Ensuring the Message Was Received....................................................................................................................... 17

SMS Summary Fields ................................................................................................................................................ 17

Status Fields ......................................................................................................................................................... 18

SMS Status Updates ................................................................................................................................................. 19

SMS Status Updates Timing ................................................................................................................................. 19

API Guide ...................................................................................................................................................................... 19

Resources ..................................................................................................................................................................... 19

Five9, Inc. Page 4 2023-03-29

INTRODUCTION

The Five9 Automated Messaging Service enables sending SMS messages to a list of recipients when using one of
the supported messaging providers.

This document is a reference guide for using the Automated Messaging Service.

PROVIDERS

Providers that are currently supported and can be used with the Automated Messaging Service are:

- Five9 Product SMS

- MMS
- Twilio
- WhatsApp

USING THE APPLICATION

LAUNCH THE APP VIA PORTAL

To access the Automated Messaging Service User Interface (UI), login to the Five9 Custom Solutions Portal using
the username and password that was provisioned for use with Automated Messaging Service. Here is the URL to
the Portal:

https://app.ps.five9.com/portal/

Then, click the cog icon in the top left to see the menu and select “Automated Messaging”:

This will launch the Automated Messaging Service UI.

Click the “Broadcasts” link in the navigation menu to go to the Broadcast lists page:

Five9, Inc. Page 5 2023-03-29

CREATE A BROADCAST

On the Broadcast list page click the “New Broadcast” link on the top right. You will need to fill in some
configuration details and click “Save” to create the Broadcast. In this section we discuss each field.

COMMON FIELDS

There are several fields common to Providers.

Name and Provider

The “Name” is an administrative label you pick to help organize your Broadcasts. You can name it as you wish.

The provider can be selected from the “Provider” dropdown. You can only select from providers which have been
provisioned in your organization.

Max Messages Per Minute

The “Max Messages Per Minute” is an optional setting that provides a requested speed for outbound texting for
the Broadcast. Use “0” to use the system’s default speed. Note that the speed is subject to vary based on load of
the system and the carrier.

Enable Notifications

Five9, Inc. Page 6 2023-03-29

The “Enable Notifications” checkbox allows you to enable and configure notifications that trigger on broadcast
completion.

Force Opt-In

The “Force Opt-In" checkbox should only be checked if you know that the recipients in the list have given consent
to receive SMS messages. If it is unknown whether the recipients have given consent, leave the box unchecked.

This field is not available for all providers. See the Consent section for more details.

FIVE9 FIELDS

Campaign Name

The “Campaign Name” must exactly match the Campaign Name that is enabled for Outbound SMS with Five9
Native SMS. If you are not using Five9 as a provider, this field will not exist.

Message Template

The “Message Template” is required. It is used as a default message for any recipients that do not have a message
defined on the recipient CSV. If a recipient was uploaded with a “message” value, the value in the list will take
precedence over this template value.

MMS FIELDS

Message Template

The Message Template field displays the same as Five9.

TWILIO FIELDS

Message Template

The Message Template field displays the same as Five9.

Five9, Inc. Page 7 2023-03-29

WHATSAPP FIELDS

Source Number

Choose a phone number provisioned on your account to send messages from.

Message Template and Language

Choose a Message Template and Language. The template and language combination must already have been
approved by WhatsApp.

UPLOAD A LIST

On the Broadcast list page, click the “Upload List to Broadcast” icon ( ) to get to the list upload page.

Select a file to upload to the Broadcast. The file must comply with the List Format for the provider, see the List
Format section for details.

Then, click “Upload File”.

The status of the list upload can be seen on the Broadcast list page.5

SCHEDULE A BROADCAST

On the Broadcast list page, click the “Schedule Broadcast” icon ( ) to get to the Broadcast schedule page.

If you wish to run the Broadcast immediately simply click “Schedule” without specifying a Date and Time.

Click the “Schedule Date & Time” field to open a date picker to select when you wish the Broadcast to run.

The time chosen is displayed in the time zone of your computer’s settings. The time zone is clarified by displaying
the time zone offset, for example GMT-5 would suggest you are in the Central Daylight Time (CDT) time zone.

The status of the Broadcast job can be seen on the Broadcast list page.

Five9, Inc. Page 8 2023-03-29

VIEW ACTIVITY DETAILS

On the Broadcast list page, click the “View Broadcast Logs” icon ( ) to get to the Broadcast activity page.

Here you can view the most recent 20 activity messages for the Broadcast. This may include validation errors on a
list upload or the results of a scheduled Broadcast.

DOWNLOAD THE SMS SUMMARY

The SMS Send Summary is not a delivery report, and this application does not guarantee the delivery of the SMS
message. The summary only shows the status of whether the SMS API provider has received the request to send
the SMS.

The SMS Send Summary shows a list of messages that have been requested to be sent through the Provider
configured on the Broadcast. The messages can be filtered by Broadcast and date range.

Click the “SMS Summary” tab on the navigation panel to reach the SMS Summary page.

Choose the Broadcast, number of results, and date rate, then click “Download”.

Upon clicking “Download” the file will be generated, please wait until the file has downloaded before navigating
away from the page.

LIST FORMAT

Lists of recipients must be uploaded in CSV format:

• delimiter: ","
• quoteChar: '"'
• escapeChar: '"'
• newline: "\n"
• skipEmptyLines: true
• header: 1 line
• encoding: UTF-8

Five9, Inc. Page 9 2023-03-29

The header row must be 1 row and contain field names specified for the Provider the list is going to be used with.

COMMON FIELDS

These fields are common to all providers:

• recipient (required): A US number in E.164 format (e.g. +15555555555), or a number that can be
converted to E.164 format using these rules:
o Delimiters like “-“ will be removed.
o If the plus sign prefix is missing it will be added.
o If the country code is missing the US country code will be added.
• message (optional): If the provider supports it, this field can specify a per-recipient Message Template
which will be used instead of the default on the Broadcast. If this field is not specified, or the value is an
empty string, the Message Template on the Broadcast will be used. The same templating rules that apply
to the Broadcast Message Template apply here as well, e.g. detagging.
• attr.* (optional): Any field prefixed with "attr." will be used to set per-recipient provider
configuration. See provider specific List Format for configuration details.
• vars.* (optional): Any field prefixed with “vars.” can be used to replace placeholder variables in the
Message Template, see Generic Message Templating for details.
• * (optional): All other fields will be ignored.

The columns can be arranged in any order.

IMPORTANT! All fields are case sensitive.

FIVE9 FIELDS

When using a Five9 provider, you have the option to use several “attr” In your list. This section will explain these
fields and how they affect the behavior of the sent message.

The “attr” fields described below must exactly match (case sensitive) when included as headers in your recipient
CSV file. Each of these fields is its own header. The “.*” means that you are free to choose the name of the
variable, and replace the “*” with that variable name.

The Five9 provider supports the following “attr” fields:

• attr.campaignName: Can be used to assign the Five9 Campaign Name to use when sending an SMS to the
recipient. The Five9 Campaign Name determines the outbound phone number used when sending the
message. If this field is empty the campaign name specified on the Broadcast will be used.
• attr.attributes.Custom.*: These are called Task Attributes. These serve a dual purpose of being able to be
with Engagement Workflow and with Five9’s Message Templating, see their related sections for details.
You can define any number of fields that start with “attr.attributes.Custom.” as long as they have
different names. For example, you could have a field of “attr.attributes.Custom.firstName” and
“attr.attributes.Custom.lastName”.
• attr.recipients.attributes.Custom.*: These are called Recipient Attributes and work similarly to Task
Attributes.

Five9, Inc. Page 10 2023-03-29

 • attr.dispositionName: Can be used to specify the disposition name used after sending the message. If this
field is empty the default disposition will be used.
• attr.scheduledTime: Can be used to define the approximate time that Five9 Product SMS will attempt to
send the message. Provide as an ISO 8601 date time UTC (e.g. 2023-03-27T01:00:00Z is 1 am UTC). If this
field is empty the message will be sent immediately.
• attr.taskName: Can be used to define the task name to use when sending the SMS.

For more information on the behavior of these fields refer to the Five9 Product SMS documentation.

ENGAGEMENT WORKFLOW

You can access the values of Task Attributes and Recipient Attributes as call variables in Engagement Workflow
when the recipient responds. The list must include values for these Attributes and there must be a Call Variable
configured in the Domain corresponding to the attribute’s name.

For example, if you have a Call Variable Group named “Custom” with a field “leadSource” you would have a CSV
file that looks like this:

recipient attr.attributes.Custom.leadSource

+15555555555 Salesforce

+15555555556 HubSpot

MMS FIELDS

When using MMS as the provider, you can specify these “attr” fields:

• attr.appId: The appId to use when sending the message. This changes the source number used when the
message is sent. If this field is empty the appId that was used when the account was provisioned will be
used.

TWILIO FIELDS

When using Twilio as the provider, you can specify these “attr” fields:

• attr.sendAt: The approximate time to schedule the message to be sent. Provide as an ISO 8601 UTC date
time. If this field is empty the message will be sent immediately.
• attr.messagingServiceSid: The messagingServiceSid to use when sending the message. This changes the
source number used when the message is sent. If this field is empty the messagingServiceSid that was
used when the account was provisionsed will be used.

WHATSAPP FIELDS

The “message” field is not supported by WhatsApp.

Five9, Inc. Page 11 2023-03-29

When using a WhatsApp provider, you can specify these “attr” fields:

• attr.message.template.components.0.parameters.0.text: The variable replacement value for template

parameter 1. See WhatsApp Message Templating for details. If not specified but the template requires
this parameter the message will not be sent.
• attr.message.template.components.0.parameters.1.text: The variable replacement value for template
parameter 2.
• attr.message.template.components.0.parameters.2.text: The pattern repeats for 3, 4, etc. parameters.

MESSAGE TEMPLATING

The message you send can be templated. This section explains the generic Message Templating feature provided
by the Automated Messaging Service as well as Provider-specific templating.

CAUTION! It is not recommended to use Generic Message Templating syntax and provider specific message
templating syntax in the same Message Template. A Message Template should be written in the syntax style of
one or the other, not both.

GENERIC MESSAGE TEMPLATING

Automated Messaging Service provides generic message templating for Providers that support a Message
Template. This templating is processed prior to any provider-specific templating.

Let’s start with an example Message Template configured on a Broadcast like so:

Hello {{firstName}}, this is a reminder that you have {{count}} prescription(s) available for pickup.

Your CSV would include fields prefixed with “vars” for use in variable replacement like so:

recipient vars.firstName vars.count

+15555555555 Lisa 1

+15555555556 Tony 3

Lisa’s message would be received like this:

Hello Lisa, this is a reminder that you have 1 prescription(s) available for pickup.

And Tony’s message would be received like this:

Hello Tony, this is a reminder that you have 3 prescription(s) available for pickup.

The way this works is the Message Template is processed by looking for any variables that require replacement.
Variable placeholders are indicated by double curly brackets like this {{variablePlaceholder}}. The replacement
value is indicated by a CSV field named the same with the prefix “vars.”, e.g. “vars.variablePlaceholder”. If no value
is found an empty string is used in the replacement.

Five9, Inc. Page 12 2023-03-29

The following characters are reserved with special use:

• Characters “{” and “}” are used to encapsulate variable placeholders.

• Slash symbol “\” is used as an escape character. Supported escape sequences are:
o “\\” single slash
o “\{“ opening bracket
o “\}” closing bracket

Be aware that some providers may implement restriction on the length of the message sent, which will be
calculated based on the de-tagged message.

FIVE9 MESSAGE TEMPLATING

When using a Five9 provider you can specify variable placeholders in your Message Template using single curly
bracket syntax. Then, in your CSV you can specify Task Attributes and Recipient Attributes for variable
replacement.

Let’s start with an example:

Hi {Custom.firstName} {Custom.lastName}, your trial ends in 30 days.

Your CSV would include Recipient for variable replacement like so:

recipient attr.recipients.attributes.Custom.firstName attr.recipients.attributes.Custom.lastName

+15555555555 Hal Jordan

+15555555556 Carol Ferris

Hal’s message would be received like this:

Hi Hal Jordan, your trial ends in 30 days.

And Carol’s message would be received like this:

Hi Carol Ferris, your trial ends in 30 days.

The way this works is the Message Template is processed by looking for any variables that require replacement.
Variable placeholders are indicated by single curly brackets like this {variablePlaceholder}. The replacement value
is indicated by either a Task Attribute or a Recipient Attribute by that name in the list, see the List Format for
details. If there is a Recipient Attribute and a Task Attribute with the same name, the Recipient Attribute will be
used. If no value is found an empty string is used in the replacement.

The following characters are reserved with special use:

• Characters “{” and “}” are used to encapsulate variable placeholders.

• Slash symbol “\” is used as an escape character. Supported escape sequences are:

Five9, Inc. Page 13 2023-03-29

 o “\\” single slash
o “\{“ opening bracket
o “\}” closing bracket

IMPORTANT! Make sure there are no spaces between the curly brace and the first or last character of your
variable inside the message template.

WHATSAPP MESSAGE TEMPLATING

When using a WhatsApp provider, you will specify a Message Template to use on the Broadcast. In the list you can
specify the variable replacement.

Let’s start with an example, let’s say you chose the message template “order_shipped” with “en” language which
has two parameters specified like so:

Hey {{1}}, your order is ready. Your confirmation code is {{2}}.

Your CSV would include two parameters like so:

recipient attr.message.template.components.0.param attr.message.template.components.0.param

eters.0.text eters.1.text

+15555555555 Jerry 100001

+15555555556 Lorraine 100002

Jerry’s message would be received like this:

Hey Jerry, your order is ready. Your confirmation code is 100001.

And Carol’s message would be received like this:

Hey Lorraine, your order is ready. Your confirmation code is 100002.

See the WhatsApp List Format section for more details.

CONFIGURING NOTIFICATIONS

When you create a Broadcast, you can check the “Enable Notifications” checkbox to configure notifications. A
notification will be sent each time a Broadcast has completed at its scheduled time. You can configure an email, a
webhook URL, or both.

Five9, Inc. Page 14 2023-03-29

EMAIL NOTIFICATION

When the “Notification Email Addresses” field is specified, an email will be sent to all recipients. You can add one
or more email addresses in a comma separated list. The email will come from the address “Five9 PS <no-
reply@ps.five9.com>”

The email subject will be “Five9 Automated Messaging Job Notification”.

WEBHOOK NOTIFICATION

When a Webhook URL is configured, an HTTP POST request will be sent to the webhook URL specified with a JSON
body containing these properties:

• description: The Broadcast’s status description

• broadcastName: Name of the broadcast that ran
• status: Stats on the broadcast job, which includes the items below:
o total: Total number of recipients where SMS delivery was attempted for the job
o queued: Total number of messages that have been queued for sending
o unqueued: The number of messages not yet queued for sending (total – queued)
o succeeded: Number of successful SMS messages sent within the job
o failed: Number of failed SMS messages within the job

Five9, Inc. Page 15 2023-03-29

 o startedAt: The start date time UTC of the job in ISO 8601 format.
o finishedAt: The finish date time UTC of the job in ISO 8601 format.

When a Broadcast is complete, succeeded + failed = total.

Example request body:

{
"description": "Idle: list is ready",
"broadcastName": "My Broadcast",
"status": {
"total": 50,
"queued": 50,
"unqueued": 0,
"succeeded": 50,
"failed": 0,
"unacked": 0,
"startedAt": "2021-12-14T17:42:11.414Z",
"finishedAt": "2021-12-14T17:43:06.222Z"
}
}

CONSENT

The Automated Messaging Service provides a consent database. Before each message is sent the consent status is
checked first according to the provider details explained below.

FIVE9

If the “Force Opt-In” field is checked, the recipient will be opted into the Five9 consent database as well as the
Automated Messaging Service consent database, regardless of their opt-in status.

If the “Force Opt-In” field is unchecked, the recipient’s consent status will be checked against the Five9 consent
database. If they are opted in to Five9, they will be allowed to receive the message, otherwise they are not.

MMS

If the “Force Opt-In” field is checked, the recipient will be opted into the Automated Messaging Service consent
database, regardless of their opt-in status.

If the “Force Opt-In” field is unchecked, the recipient’s consent status will be checked against the Automated
Messaging Service database. If they are opted in, they will be allowed to receive the message, otherwise they are
not.

TWILIO

This behaves the same as MMS.

WHATSAPP

Five9, Inc. Page 16 2023-03-29

WhatsApp bypasses the Automated Messaging Service consent checks. Messages are always allowed to be
delivered to WhatsApp.

WhatsApp applies its own consent policies when processing the messages for sending. See WhatsApp’s
documentation for details.

STOP REQUESTS

STOP requests are not handled by the Automated Messaging Service. If a recipient of a message replies with
“STOP” it will be handled by the carrier or the SMS Provider.

SMS SUMMARY

This section helps explain in further detail the Broadcast SMS Summary.

ENSURING THE MESSAGE WAS RECEIVED

The Automated Messaging Service provides status information on whether the message was sent to the provider
for processing, not delivery of SMS messages. It is possible that an error occurs at the provider during message
processing. Errors may also occur during carrier delivery to the recipient.

Some providers offer support for status updates which will be displayed in the SMS Summary.

For detailed delivery reporting consult the provider’s or carrier’s documentation.

SMS SUMMARY FIELDS

An SMS Summary CSV lists each message requested to be sent by the Automated Messaging service. The fields
available common to providers are:

• recipient: Who the message was sent to, e.g. +15555555555

• recipientType: The type of recipient, e.g. E164
• isAccepted: Whether the message attempt was accepted by the provider.
• reason: Reason for failure or success.
• externalId: A provider specific unique identifier that can be used in some cases to track the original
message in the provider’s system.
o For Five9, this value maps to the “sendSmsTaskId”
o For MMS, this value does not have a mapping
o For Twilio, this value maps to the “messageSid”
o For WhatsApp, this value maps to the notification “_id”
• isMessageTransactionAllowed: Whether the message send attempt was allowed to be sent based on the
consent state.
• consentAction: Represents how the consent request to send the message was processed. Possible Values:
o FORCE_ALL – If “Force Opt In” is checked in Broadcast
o PERMIT_OPTED_IN – If “Force Opt In” is not checked in Broadcast
o PERMIT_BYPASS – If the provider bypasses the Automated Messaging consent database, e.g.
WhatsApp

Five9, Inc. Page 17 2023-03-29

 • consentState: The opt-in status of the recipient after the consent action was applied. For example, if the
“Force Opt-In” checkbox was checked and the value is “OPTED_IN”
• consentPolicyReason: An explanation of what consent processing was done:
o PERMIT_BYPASS – The message was allowed because the consent action was bypassed.
o PERMIT_OPTED_IN – The message was allowed because the recipient is opted in already.
o PERMIT_FORCED_IN – The message was allowed because the recipient was force opted in.
o PERMIT_FORCED_OVERRIDE – The message was allowed because the recipient was force opted
in.
o DENY_UNSPECIFIED – The message was not allowed because they are not opted in.
o DENY_OPTED_OUT – The message was not allowed because they are opted out.
o DENY_ERROR – The message was not allowed because of an error. This could be an error within
Automated Messaging or in the case of Five9 it could be an issue during Five9’s processing of
consent.
• messageSendHttpCode: The HTTP code from the message send request. If 0, there was a client side error,
else the error was on the provider’s server.
• consentHttpCode: The HTTP code from the attempt to opt the recipient in. If 0, there was a client side
error, else the error was on the provider’s server.
• messageServiceSuid: The identifier for the Message Service used to send the message.
• messageTransactionUuid: The unique identifier for the message transaction.
• broadcastJobUuid: The unique identifier for the Broadcast Job.
• broadcastUuid: The unique identifier for the Broadcast.
• consentUuid: The unique identifier for the consent processing request.
• messageSendTaskUuid: The unique identifier for the message send attempt to the provider.
• uuid: The unique identifier for the SMS Summary record.
• createdAt: The timestamp of the SMS Summary record’s creation.
• receivedAtTimestampMs: The millisecond timestamp when the message was processed.

Any message template variables (starting with “attr.” or “vars.”) that are included in the initial recipient CSV will be
included as additional columns in the SMS Summary.

Certain providers allow for status updates which will provide the following additional fields:

• status: The provider’s status value.

• statusReason: The provider’s status reason.
• hasStatusUpdate: If true, there was an update to the message status after it was sent to the provider.
• statusAt: The ISO 8601 date time UTC the status was received.

STATUS FIELDS

From the SMS Summary, you can see whether any messages failed to be sent to the provider. Any of these field
values indicate that a message failed to be sent to the SMS Provider:

Field Sent Not Sent

Five9, Inc. Page 18 2023-03-29

 isAccepted true false

consentHttpCode 200-299 (Usually 200, 201, 202, or 204) 0 or any non-success HTTP code

messageSendHttpCode 200-299 (Usually 200, 201, 202, or 204) 0 or any non-success HTTP code

You can determine the approximate failure reason by looking at the “reason” field. Note that a sent value does not
indicate that the message was delivered to the recipient successfully, just that the provider has indicated it will
process the message for sending. You must rely on the provider’s reporting for detailed send status.

SMS STATUS UPDATES

Certain providers allow for status updates after the message has been initially processed. These statuses are
available in the SMS Summary.

Twilio and WhatsApp support status updates.

The statuses and status reasons are completely up to the provider. As an example, some providers may be able to
send a status update that a message failed due to the destination not being a valid number.

SMS STATUS UPDATES TIMING

If an SMS attempt was just made by the Automated Messaging Service, and an SMS Summary is pulled, it is
possible that the status update has not made it back to the Automated Messaging Service application, so it is
possible that the status fields will be empty for a period of time after the message send attempt occurs.

Please allow enough time for the message provider to return the status update for the fields to populate on the
SMS Summary.

API GUIDE

To access the Automated Messaging Service API, use the API Key provided to you. The API documentation is
available at the following URL:

https://pam.ps.five9.com/app/api/v1/docs/customer/

The API can be used to programmatically integrate with the Automated Messaging Service. It requires a bearer
token for authentication which will be provided during the provisioning process.

RESOURCES

During implementation work with your assigned Five9 deployment resource for any support or information you
need. After the implementation is complete submit a request to cases@five9.com.

Five9, Inc. Page 19 2023-03-29