Last Updated: Wednesday, April 15, 2020
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_id | String | The external system's Person ID to include in the Recipient List. |
| vibes_device_id | String | The 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.
Example: mdn +12295551234. link to E.164 format: E.164 Support for Platform APIs
|
custom | String | A custom field that can be used for Broadcast personalization. Notes:
|
| segment_code | String | 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_id | String | A 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 Class | Error Message | Description |
|---|---|---|
| RecipientListEntryErrors::DuplicatePersonId | duplicate person_id | The Recipient List already has a record with this person_id. |
| RecipientListEntryErrors::DuplicatePersonKey | duplicate person_key | The Recipient List already has a record with this person_key. |
| RecipientListEntryErrors::DuplicateExternalPersonId | duplicate external_person_id | The Recipient List already has a record with this external_person_id. |
| RecipientListEntryErrors::DuplicateMDN | duplicate mdn | The Recipient List already has a record with this mdn. |
| RecipientListEntryErrors::DuplicateVibesDeviceId | duplicate vibes_device_id | The Recipient List already has a record with this vibes_device_id. |
| RecipientListEntryErrors::InvalidPersonId | invalid person_id | The person_id or person_key in this record doesn't point to a valid Person, or the person_id is formatted incorrectly. |
| RecipientListEntryErrors::InvalidMDN | invalid mdn | The mdn isn't a valid E.164 phone number. |
| PG::NumericValueOutOfRange | integer out of range | The error message means the import has a number that’s too big for our database to handle. |
File Level Errors
| Error Class | Error Message | Description |
|---|---|---|
| RecipientListErrors::RecipientListAlreadyExists | A Recipient List with that name already exists. | |
| RecipientListErrors::InvalidImportFileFormat | Couldn't find a person_id, external_person_id, mdn, or vibes_device_id field | You must specify at least one field to identify the Person or device you wish to send to. |
| RecipientListErrors::InvalidImportFileFormat | specify an mdn, or a vibes_device_id, or neither | You 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.
Overview
Content Tools