Using File Triggered Broadcasts

The Vibes Mobile Engagement Platform can be configured to automatically send messages to subscribers using a flat-file (CSV) batch process. Incoming files will be handled and routed based upon a designated set of characters, words or phrases in the file name. The result of processing these files is sending a SMS message or Push notification through the Platform.

Within the file, an identifier (such as person_key, external_person_id, vibes_device_id or mdn) is required to ensure a subscriber is valid and to properly route the message. The Platform can also accept file specific data that can be used to personalize the triggered messages to subscribers such as customer’s first and last name, order numbers, and even URLs.

File Layout

The file format will be a recipient list integration file.  For details on file format and error messaging see recipient list section here.

File Naming

<filename>.recipient_list

File name trigger logic is created at the campaign level in the Vibes Platform UI.

The beginning of the file name is customizable by campaign, but every file MUST end in .recipient_list.

The file name is critical for managing incoming files to the Vibes Platform and message delivery. Every file triggered campaign is associated with a specific file naming format to ensure the subscribers are routed to the appropriate campaign. The naming convention of the file must match the respective campaign name in the Platform to trigger a message.

NOTES

• Once the campaign specific file name trigger structure is set, it cannot be changed for the campaign
• All file names must contain file name trigger logic in the exact same order and format set at the campaign otherwise, the file will not be recognized by the Vibes platform.
• One file can be utilized for multiple triggered campaigns in the Platform. You can use different filters per campaign to target different subsets of subscribers in the file. If filters are not used, two messages will be sent to everyone in the file.

File Body

The file body can contain the following fields as data, separated by the delimiter.

Note: The field names must be lowercase.

Identifying Persons

For a particular row, only one of external_person_id, person_key, mdn, or vibes_device_id need to be specified, as these are alternate means of referencing a Person. If more than one value is specified, we will use the value with the highest precedence.

Precedence order:

1. Person_key
2. External_person_id
3. mdn
4. vibes_device_id

Message Delivery

Message distribution is set and managed within the Vibes platform UI when creating the file triggered campaign.

Messages can be scheduled to trigger at a set time and time zone after file upload completion to the Vibes platform or as soon as the file finishes uploading to the platform.

If the campaign is set to trigger at a set time, the time of deployment is set within the Vibes Platform rather than in the parameters of the dropped file.  Once the campaign file is accepted by the Vibes portal, the message will remain in a masked queue within the Vibes Platform until campaign deployment. 

The only means of deleting a campaign that has been processed through the Vibes Platform is by performing an API call to delete the campaign. Once the campaign has been deleted, an updated file can be dropped to initiate the new SMS. You will need the campaign id and company key to perform this action. 

Example:

DELETE /companies/:company_key/mobiledb/broadcasts/:broadcast_id

Link to Broadcast API Documentation: https://developer.vibes.com/display/APIs/Broadcast+API+Methods

NOTE:

• The recipient list file only determines who will receive the message, and assignment of personalized message content. Delivery time cannot be determined within the recipient list file.
• The file must finish uploading prior to the send time configured at the campaign level. If the file upload finishes after the schedule time, the messages will trigger the following day.

File Triggered Message Scenario

Imagine you would like to send your customers an SMS notification a few days before their rewards balance expires, and the SMS will contain information specific to the customer’s loyalty balance with a personalized coupon offer. You would like the message personalized to include the customer's first name, reward balance and expiration date, and a custom coupon offer.

To achieve this, you need to create a File Triggered campaign in the Vibes Platform UI to be used when a expiring rewards message needs to be sent, and the file trigger campaign needs to be configured to respond to files containing the following phrase in the file name:'rewards_expiration_reminder'.

The Message Content in the file triggered campaign would be defined as follows:

Hi, {{rl.first_name}}! Your ${{rl.reward_value}} reward is expiring in {{rl.expiration_days}} days! Use code {{rl.reward_code}} before {{rl.expiration_date}}! Reply HELP for help, Reply STOP to cancel. Msg&data rates may apply

When the following recipient list file example is uploaded to the SFTP or platform UI:

File Name: rewards_expiration_reminder_03302020.recipient_list

Recipient list format:

external_person_id,first_name,reward_code,reward_value,expiration_days,expiration_date
53438280,Josh,11P8R8QWXP8H,10,23,3/31/2020
69448680,David,T12DRNB9DZNR,5,23,3/31/2020
90343160,Laura,H812VM46RT7M,15,23,3/31/2020
2123680,Brent,LF82612JP2BR,10,23,3/31/2020
86604800,Aaron,H3J12GNTVD4P,10,23,3/31/2020
6600840,April,JNWHCN412YX4,10,23,3/31/2020
25262680,Molly,H4B1269W3GTR,10,23,3/31/2020

The values in the additional columns after external_person_id are substituted for the placeholders defined in the File Trigger Message Content, resulting in delivery of the following message to the recipient with external_person_id=53438280 in MobileDB:

 Hi, Josh! Your $10 reward is expiring in 23 days! Use code 11P8R8QWXP8H before 3/31/2020! Reply HELP for help, Reply STOP to cancel. Msg&data rates may apply

Process Notes:·      

• File name logic is created when configuring a File Triggered Campaign in the Vibes Platform UI.
• Output markup for dynamic data in Message Content must be prefaced with "rl.", denoting elements of the custom_data column header in the file.
• Example: If "first_name" is supplied in the custom data column header name object, the Message Content markup would refer to that value as "rl.first_name".
• File Trigger Message Content supports Liquid Markup Language syntax.
• File trigger messaging can be scheduled at a set time and by time zone or once the file has processed. Configuration can be setup in the Vibes Platform UI.
• If the File Trigger campaign is set to distribute messages by a set time and time zone, the file must finish uploading prior to the send time configured at the campaign level. If the file upload finishes after the schedule time, the messages will trigger the following day.
• If a person_key/mdn/external_person_id is on the file more than once, they will only get the first message.  The Vibes platform de-dupes.