Recipient List Import
Much like the person import, a recipient list is also a collection of persons. However, a recipient list is a collection of persons to target in a broadcast or file-triggered broadcast. The most common use case is when your CRM has created a list of contacts to target. The list can then be loaded into the Vibes platform and used for a broadcast.
Recipient lists can also include additional columns of data that can be used as message variables or the entire message itself. For example, if you had a column titled “first_name”, you could pull that personalization value into a broadcast or file-triggered message.
Which identifier should I use?
Recipient lists may be channel-specific depending on the fields you use to identify each person.
- If the file identifies person records by
person_id,person_key, orexternal_person_id, you can send SMS, MMS, or push messages - If the file identifies person records by
mdnonly, you can only send SMS or MMS messages - If the file identifies person record by
vibes_device_idonly, you can only send push messages
Using custom data
Using a recipient list will not update person records. If you include custom data for personalization in your recipient list, it will not be stored in your mobile database.
File Specifications
Encoding
UTF-8 or ASCII encoding for integration files is recommended. UTF-16LE encoding is not supported.
File Name
[file name].recipient_list
File Format
The contents of the file should be plain text separated by commas or another delimiter.
File Size
If you are uploading via the platform, we recommend files are less than 5MB, which is usually about 100,000 rows of data.
If you are uploading files via SFTP, there is no limit; however, larger files may take more time to upload.
Headers
You can include the following headers in your Recipient List Import. Using headers is 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. |
Body
The file body can contain the following fields as data. All field names must be lowercase.
In each row, at least one identifier needs to be specified. Available identifiers are person_id, external_person_id, person_key, vibes_device_id, or mdn. If more than one value is specified, we will use the value with the highest precedence.
| Field Name | Data Type | Description |
|---|---|---|
person_id | Integer | A Vibes-assigned number identifier, used to identify a person record that already exists in the Vibes system. First in precedence. |
person_key | String | The Vibes-assigned string identifying a person record that already exists in the Vibes system. The person_key must be lowercase. Second in precedence. |
external_person_id | String | If your external system uses its own system of id, use the external_person_id field to upload this data into the Vibes system. Third in precedence. |
vibes_device_id | String | A unique identifier for a device that can receive push notifications. The vibes_device_id must be lowercase. Fourth in precedence. |
mdn | String | An mdn is the mobile phone number to send the message to.- For non-US numbers, the mdn must be in E.164 format. Example: mdn +12295551234 - US numbers can use the 10-digit mdn format. |
| {custom} | String | Custom fields are fields that are specified by you. Any custom fields you’d like to use must be created in the platform before they are used in a person import. 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_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. |
Errors
The following tables show error codes that can occur for recipient list import files. Common errors for all file types can be found here.
Row-Level Errors
| Error Class | Error Message | Description |
|---|---|---|
| RecipientListEntryErrors::DuplicatePersonId | duplicate person_id | The recipient list already has a row with this person_id. |
| RecipientListEntryErrors::DuplicatePersonKey | duplicate person_key | The recipient list already has a row with this person_key. |
| RecipientListEntryErrors::DuplicateExternalPersonId | duplicate external_person_id | The recipient list already has a row with this external_person_id. |
| RecipientListEntryErrors::DuplicateMDN | duplicate mdn | The recipient list already has a row with this MDN. |
| RecipientListEntryErrors::DuplicateVibesDeviceId | duplicate vibes_device_id | The recipient list already has a row 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 record in our mobile database, 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 | The file does not include a field that can be used to identify the person or device you are sending to. One of the following fields must be present: - person_id- person_key- external_person_id- mdn- vibes_device_id |
| RecipientListErrors::InvalidImportFileFormat | specify an mdn, or a vibes_device_id, or neither | The file attempts to identify persons by both an MDN and vibes_device_id. Choose only one identifier, or remove both and add another identifier. |
| 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) |
Example Files
Below, you can download a .zip of example files of a recipient list. To view these files, follow the following steps.
- Download example files here.
- View the file in your downloads folder. Click to unzip.
- Rename each unzipped file by adding .csv to the end. This will change the file's extension, therefore making it viewable in Microsoft Excel.
- Open the file in Microsoft Excel or another spreadsheet app to view.
Note that when you upload a recipient list in platform, the .csv extension should be deleted.
Updated about 2 months ago