How to prepare for phone number normalization in the Front API

On September 1st 2024, we will be introducing E.164 phone number normalization to the Front API to address issues caused by inconsistent phone number handles attached to contacts. Phone number handles for contacts in Front can be created via the API, the Front contacts manager, incoming messages in channels, CRM contact syncs, and CSV import of contacts. With so many different ways of creating contacts and storing phone numbers for those contacts, it’s important to normalize the data because the different input formats can lead to duplicate contacts and related search issues.

Benefits

• Easier Contact Management: By normalizing phone number handles, users will be able to search and merge contacts more effectively. Inconsistent normalization creates difficulties in contact management, such as not being able to effectively identify or merge contacts who have the same number stored in a slightly different way: 512-555-1337 versus +1 (512) 555 1337 versus 15125551337, etc. This leads to duplicate contacts in Front.
• Improved Search Functionality: Normalizing phone number handles will enable users to search for contacts using various phone number formats. For example, searching for 650 123 4567 or (650)123 - 4567 should return the same contact with the normalized handle +16501234567.
• Merge Functionality: The introduction of phone number normalization also includes the ability to merge existing duplicate contacts that currently would create a merge conflict. This allows users to consolidate multiple contacts with the same handle into a single contact, eliminating duplicates and improving contact management efficiency.

Potential impacts

Developers will have to prepare for the following potential impacts when phone number normalization is released:

• Missing country code (BREAKING CHANGE): Requests to the inbound and outbound Channel API message endpoints and to the custom channel incoming messages endpoint will default phone numbers to +1 (USA) if they are missing a country code. Front recommends always sending a country code. You must send country codes preceded with a plus (+) sign (e.g. +1 for USA, +33 for France, etc.).

  Example: +852 is the country code for Hong Kong. A correct way of sending a Hong Kong phone number to the Front API would be +85291234567. If you simply send 85291234567 instead, the phone number for the contact will be normalized as +185291234567.

• Make sure phone numbers are valid: If phone numbers for a contact are not valid for requests sent to the inbound and outbound Channel API message endpoints or to the custom channel incoming messages endpoints, those numbers will save as a null value instead of as an invalid phone number.

  Invalid phone number:
  If you send 000, the phone number for the contact will be null instead of 000.

  Invalid area code for a country:
  If you send +33 (415) 555-5555, the phone number for the contact will be null because 415 is not a valid area code for France.

  Missing digit or incorrect phone number length
  If you send (415)-123-456, the phone number for the contact will default to a US country code (because it is missing an explicit country code) and will be null because US phone numbers must contain seven digits after the country and area codes.

• Duplicate contacts might be created on a one-time basis: Normalizing phone numbers for API requests might cause duplicate contacts to be created for existing contacts in existing conversations, but these contacts can be manually merged by Front users if they occur. The duplicate contacts would only impact existing conversations. New conversations created after the normalization date would not be impacted.
• Custom channels might thread messages differently if thread_ref is not used: If you are receiving messages in a custom channel but not sending the thread_ref parameter, differences in contact handles before and after normalization might cause messages to thread into new conversations after the normalization date because Front threads by sender if the thread_ref is empty. The threading issues would only affect existing conversations. New conversations created after the normalization date would not be impacted.
• The contacts endpoints might reject certain requests: If you create or update a contact with a phone number that cannot be normalized to the E.164 standard, Front will reject your API request whereas before it would have accepted a value that didn’t make sense for a phone number.
• Ensure you are sending phone number handles for phone channels: If you are using the inbound and outbound Channel API message endpoints for channels configured with the phone type, make sure the handle you send in the sender object is a valid phone number. Incorrectly sending an email address for a phone channel, for example, can lead to issues when managing the contact.