Import contacts

Register contacts for email, SMS, WhatsApp, and Viber from one CSV file. One phone number column can register a contact for both SMS and WhatsApp, so you don’t need a separate file per channel.

Prepare your CSV file

File format

• The first row must contain column headers describing the data in each column.
• Each subsequent row represents a single contact, with values corresponding to the headers.
• Values must be separated by commas.
• Save the file in UTF-8 encoding to ensure proper character display.
• The maximum file size is 100 MB.

Contact columns

Include at least one of these columns, depending on the channels you want to register contacts for:

• Email: the recipient’s email address.
• Phone number (for SMS, WhatsApp, and Viber): in international format, starting with + and the country code, for example +120XXXXX234. Enter the plain number without a whatsapp: or viber: prefix. Pushwoosh adds the prefix when you map the column to that channel.

If a phone number isn’t in a valid international format, it’s skipped for that channel. The rest of the row still imports.

Note

The column names in your CSV file don’t need to match these labels. During import, you map your existing column names to a channel in the wizard. For example, a column named Mobile can be mapped to the SMS or WhatsApp channel.

Optional columns

• User ID: a unique identifier for the user (e.g. name or email). Not required, but recommended so the contact’s channels share one user profile instead of several.
• Any other column can be mapped to a system tag for segmentation and personalization, for example Location, Birthday, Language, or Customer type.

Example CSV file

Email,Mobile,User ID,Name,Location
john.smith@email.com,+120XXXXX234,john.smith@email.com,John Smith,New York
jane.smith@email.com,+131XXXXX890,jane.smith@email.com,Jane Smith,Los Angeles

Upload and map the CSV file

1. Go to Audience → Import CSV → Import Contacts.

   

2. Click Upload CSV and select your file. To replace it, click Upload Another CSV.

   Caution

   Pushwoosh checks the whole file when you upload it. A row that can’t be parsed (its column count doesn’t match the header, or a quoted value isn’t closed) gets the file rejected right away. A toast names the row and the reason, for example “Row 42: the number of values does not match the header.” Nothing is imported in this case. Fix that row and upload the file again.

3. Enter a Segment name for the imported contacts.

4. Under Contact column in CSV, select a column and, next to it, choose the Channel it registers (Email, SMS, WhatsApp, or Viber). Click + Add channel to map another column, or to map the same column to an additional channel.

5. Under UserId column in CSV, select the column with unique user identifiers, if your file has one.

6. To include extra data for segmentation, select a Column Name from your CSV and assign it a Tag. Click + Add Column to map more attributes.

   

7. Click Start Import.

After the import, the contacts are available for campaigns on the channels you mapped. They appear as a new segment in the Segments list and can also be accessed via User explorer.

The completion screen shows two counts:

• Created: channel registrations that are new to the app.
• Updated: channel registrations that already existed, including when the same address or number re-registers under a different User ID or on a different device platform.

Both count channel registrations, not contacts or CSV rows. A contact mapped to two channels, for example SMS and WhatsApp, adds 2.

For an updated contact, only the tags mapped in step 6 change. Their values are overwritten with the CSV values. Other tags already set on the contact stay as they are.

Note

Older imports in the recent imports list show a single Imported count instead of Created and Updated.

Rows skipped during import

The completion screen groups skipped rows by reason:

• Email address is not valid
• Phone number is not valid
• No contact address in the row: every mapped column was empty

A row can be partially imported and still show up in this breakdown. For example, the email column succeeds, but the phone column fails validation.

Click Download skipped rows to get a CSV of those rows only. The file adds the skip reason as an extra column so you can fix the rows and re-upload them.

Note

Download the file before you leave the completion screen. If you open the same import later from the recent imports list on the Import CSV hub, you see the reason counts but no download link.

Rows the import failed to register

Some rows look fine in the file but still don’t go through. For example, an email address can be spelled correctly and still get rejected because it belongs to a disposable or bounced domain. Pushwoosh counts rows like this as Failed, separately from Created, Updated, or Skipped.

Failed rows aren’t broken down by reason and aren’t included in the skipped-rows download. To find them, compare your source CSV with the imported segment. Fix the missing addresses (for example, remove a disposable or bounced domain), then re-upload only those rows in a new import.