Last Updated:





A Recipient List is a collection of Person references that can be loaded into the Mobile Database and used as a target filter for Broadcast messages. The most common use case is when there is a Customer-defined CRM/targeting system that creates a targeted list of Broadcast recipients that needs to be loaded and used within Vibes Mobile Engagement Platform targeting.

Recipient Lists may be channel specific depending on the fields you upload. For example, if you upload a Recipient List with just person_id, person_key or external_person_id, it can be used on any channel. But, if you upload just an mdn, then it only works for an SMS/MMS channel; or, if you upload a vibes_device_id field, then it is for push only.

Recipient Lists can also include additional columns of data that can be used as message variables. For example, if you had a column titled “first_name”, you could pull that personalization value into a Broadcast or file triggered message.

Note: UTF-8 or ASCII encoding for integration files is recommended (UTF-16LE encoding is not supported).

File Name

<filename>.recipient_list

File Format

The file format is a Comma-Separated Values (CSV) file. This stores tabular data (numbers and text) in plain text, where the line of the file is a data record. Each record consists of one or more fields, separated by commas.

Headers

You can include the following headers in your Recipient List.

Note: Using headers is entirely optional.


Header Name

Description

Content-Type

Value should always be TEXT.

List-Name

This is the list name that will be displayed in the User Interface. If omitted, a default value based on the filename will be used.

Fields

This is a comma separated list of the fields that will be in the body of the text file. If omitted, then the first row of the body must contain the field names, with the same delimiter as the body.

File Body

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


Note: The field names must be lowercase.


Field Name

Data Type

Description

person_id

Integer

The Mobile Database Person ID to include in the Recipient List. The person_id must be lowercase.

person_key

String

The Person Key is a UUID to include in the Recipient List. The person_key must be lowercase.

external_person_idStringThe external system's Person ID to include in the Recipient List.
vibes_device_idStringThe Vibes Device ID to include in the Recipient List. The vibes_device_id must be lowercase.

mdn

String

A Mobile Directory Number (mdn) is the mobile_phone number to include in the Recipient List.

  • For non-US numbers, the Mobile Directory Number (mdn) must be in E.164 format.

Example:

mdn

+12295551234.

link to E.164 format: E.164 Support for Platform APIs

  • US numbers can use the 10-digit mdn format.

custom

String

A custom field that can be used for Broadcast personalization.

Notes

  • "Custom" is not a specific string. It means that any custom field name may be used in the data file.
  • The header row must match the name of the custom field EXACTLY.


segment_codeString

A custom string that can be used for targeting.

Note: You can only use the segment_code option in Broadcasts − it is not supported in File Triggered messages.


client_message_idStringA custom string that can be later tracked through exports from our data warehouse.

Identifying Persons
For a particular row, only one of person_id, external_person_id, person_key, or mdn 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. The precedence order is shown in the table above.

Error Messages

The following tables show the error codes that can occur when importing a file.

Row Level Errors

Error ClassError MessageDescription
RecipientListEntryErrors::DuplicatePersonIdduplicate person_idThe Recipient List already has a record with this person_id.
RecipientListEntryErrors::DuplicatePersonKeyduplicate person_keyThe Recipient List already has a record with this person_key.
RecipientListEntryErrors::DuplicateExternalPersonIdduplicate external_person_idThe Recipient List already has a record with this external_person_id.
RecipientListEntryErrors::DuplicateMDNduplicate mdnThe Recipient List already has a record with this mdn.
RecipientListEntryErrors::DuplicateVibesDeviceIdduplicate vibes_device_idThe Recipient List already has a record with this vibes_device_id.
RecipientListEntryErrors::InvalidPersonIdinvalid person_idThe person_id or person_key in this record doesn't point to a valid Person, or the person_id is formatted incorrectly.
RecipientListEntryErrors::InvalidMDNinvalid mdnThe mdn isn't a valid E.164 phone number.
PG::NumericValueOutOfRangeinteger out of rangeThe error message means the import has a number that’s too big for our database to handle.

File Level Errors

Error ClassError MessageDescription
RecipientListErrors::RecipientListAlreadyExists
A Recipient List with that name already exists.
RecipientListErrors::InvalidImportFileFormatCouldn't find a person_id, external_person_id, mdn, or vibes_device_id fieldYou must specify at least one field to identify the Person or device you wish to send to.
RecipientListErrors::InvalidImportFileFormatspecify an mdn, or a vibes_device_id, or neitherYou cannot specify both and mdn and vibes_device_id in the same file.
RecipientListErrors::InvalidImportNoValidEntries
There are no valid entries in the file, so the Recipient List was not created.
RecipientListErrors::SegmentCodeLimitExceeded
You have too many unique values for the segment code. (max 100)

Common Errors

The following errors can occur in imports of all file types.

File Level Errors

Error Class

Error Message

Description

TenantEngine::SchemaErrors::InvalidSchemaNameError

Schema name for company <company_id> (is nil|was not found)The company that the file is target for is not set up in MobileDB, or there was some other system level error.

Example Files

See the attached files for some examples.