Troubleshoot the Contact API
Whispir works with you to customise the Contact API module to meet your company's data requirements. The following conditions are important for ensuring a successful contact file import.
CSV file format is comma delimited
Whispir only supports the import of comma delimited .CSV files. Tab or pipe delimited files are not supported. Text fields with commas as part of the data should use quotation marks (" ") around the data.
CSV file name format must follow the agreed format
Once Whispir and your company have agreed on a .CSV file name format, that file name must always follow the format for every import. The preferred file name format is <YourCompanyName>_<Time>_<Date>_<Count>records<Import Option>.CSV.
CSV file header row must remain the same
Once Whispir has worked with you to determine the correct .CSV data file format for your data, the format of the .CSV file header row must be exactly the same for every import with the same number of columns, column names and order.
Contacts are imported into a single Whispir workspace called ‘Masterlist’
A single administration workspace is created specifically to hold the contacts imported via the Contact API. This is called the Masterlist workspace. From here contact mapping rules are used to map imported contacts to the workspaces they need to be in for receiving messages.
The Masterlist workspace is the only workspace configured to allow a Contact API import. All other workspaces can only use Whispir’s standard contact import functionality and this will only work if your company has not implemented custom contact profile fields. For more information contact the Whispir Support Team (support@whispir.com).
It’s possible to perform a manual Contact API import into the Masterlist workspace using the Import Contact command on the Masterlist’s Workspace menu. The process is similar but not identical – it lets you add, update and ignore contacts but it doesn’t delete contacts.
Each contact must have a unique identifier
For all imports a unique identifier must exist for each individual contact and it must not change. In the initial .CSV file setup work you specify the identifier to use for your contacts. Typically this is Work Email Address Primary. But Whispir can set up a custom field if your company wants to assign its own unique ID to each contact.
The identifier is used to compare a contact record imported from the previous import and determine if the record is new and has to be added, is existing and has to be updated, or is existing but has to be ignored as no change is identified. Any contacts in the Masterlist workspace that are not in the import file are deleted.
A full and complete listing of the contacts to be maintained in Whispir must be in the .CSV file for each import
The Contact API processing deletes all contacts in the Masterlist workspace that aren’t in the .CSV file being imported up to a default threshold of 5% of the Masterlist contacts. This is a safety mechanism that stops the import process at that threshold to ensure contact details aren’t being deleted due to a file import error.
The threshold can be configured by the Whispir Support Team (support@whispir.com). For example, a company might request a temporary increase in the threshold to 100% to process a high number of deletions in a one-off import.
Note: Whispir's 'classic' Import Contacts feature does not delete contacts.
Contact mapping rules must be in place
In order to make the imported contacts available in other workspaces, contact mapping rules must be in place to map from the Masterlist workspace. Whispir will work with you to ensure these rules are set up before the initial import. See About Contact Mapping Rules.
Mandatory fields must have data
The mandatory data fields will depend on the custom configuration for your company. Once agreed, these fields must always have data in the imported .CSV file. At a minimum, Last Name and the unique identifier are mandatory.
Data must be message-ready
The Contact API doesn’t perform data validation, data integrity or data quality checks. All contact information should be complete and ready for the type of messaging the contacts require. In particular phone numbers should be valid and meet specified formats with no invalid characters. Phone country codes should exist for each phone number being imported.
Data used in any dynamic distribution lists must be included. See Create a dynamic distribution list.
Contacts imported via the Contact API should not be edited or deleted via the Whispir platform
Once the Contact API has been implemented for your company, the ‘source of truth’ for contact data is assumed to be external to the Whispir platform. As a result any contact record updates (add/edit/delete) must be made in your third-party system(s) and then the updated data is imported.
For this reason Whispir recommends that Whispir users do not create, update or delete contact records from within Whispir. It can cause confusion when users believe they’ve updated a contact, only to find it has reverted or changed following a later import. If new contacts need to be created or any existing contacts need updating or deleting always use the Contact API to upload a new file for processing. This will ensure that the contact data in Whispir is kept in sync with your third-party system.
Whispir can advise you on how to adjust workspace permissions to disable the add, edit and delete functions in workspaces that have contacts mapped to them from the Masterlist workspace. For information about permissions see About roles and permissions.
New workspaces or new contact mapping rules created after Contact API implementation
New mapping rules and a manual contact mapping are required when workspaces are added or new or changed rules need to be applied. See Create a workspace mapping rule.
View the Activity Log to check import status
Company administrators can open the Activity Log from the Administration sidebar. See Use the Activity Log.
On the Activity Log page you can use filters to search for an entry that shows that a file has been accepted for processing. A corresponding entry will show the number of records added, updated, deleted and ignored during processing. The activity log also shows the status of each record processed.