How to Validate and Normalize Phone Numbers Using Google’s libphonenumber

Overview

Incorrect or incomplete phone numbers are one of the most common causes of message delivery failures across channels such as WhatsApp, SMS, and RCS.
When users enter invalid numbers (for example, missing country codes, landlines instead of mobile numbers, or typos), messages cannot be delivered.

Implementing phone number validation and normalization ensures that all phone numbers are stored and processed in a consistent format. This reduces message failures, improves deliverability, and enhances the accuracy of customer data across all communication channels.

Why Phone Number Validation Is Important

Before sending any message, the number must meet three key conditions:

1. It must be valid for a specific country.
   Example: 0412 123 4567 may be valid in Venezuela, but invalid in Colombia.

2. It must be formatted consistently.
   A standardized format ensures all systems — your application, Messangi’s APIs, and WhatsApp — interpret numbers correctly.

3. It must be reachable on the intended channel.
   Not all valid mobile numbers are registered on WhatsApp or capable of receiving SMS messages.

Recommendations and Best Practices

1. Validate Early at the Point of Entry

The most effective way to prevent invalid numbers is to validate them as users type or submit them.

• Use a country selector to automatically apply the correct country code.

• Provide real-time validation feedback such as “Valid number” or “Invalid format.”

• Restrict the input field to numeric values and automatically remove spaces or special characters.

• Display an example format for clarity, such as “Example for the U.S.: (305) 555-1234.”

2. Store Numbers in E.164 Format

The E.164 format is the international standard used by most messaging APIs.
Format:

+<CountryCode><SubscriberNumber>

Examples:

• United States: +12015550123

• Mexico: +525512345678

• Jamaica: +18765551234

Storing numbers in E.164 ensures consistency across systems and simplifies integration with APIs and databases.

3. Validate on Both Client and Server Side

Client-side validation improves user experience, but server-side validation guarantees data integrity.

• Client-side validation prevents obvious errors before submission.

• Server-side validation ensures all stored numbers meet your business rules and formatting standards.

4. Filter Mobile Numbers Only

If you are using WhatsApp or SMS as a delivery channel, automatically exclude landlines.
The libphonenumber library can identify the type of number (mobile, landline, toll-free, etc.) for most countries.

5. Confirm or Verify User Numbers

If users frequently mistype their phone numbers:

• Implement OTP verification via WhatsApp or SMS before allowing access or sending notifications.

• Use Click-to-WhatsApp buttons or QR codes so users can initiate a WhatsApp chat directly, capturing a verified number automatically.

6. Track and Analyze Validation Results

Monitor:

• The percentage of invalid numbers entered.

• The most common validation errors (missing country code, wrong length, etc.).

• Message failure rates per channel.

This data helps refine validation rules and improve the user experience over time.

Implementing Validation and Normalization with libphonenumber

About libphonenumber

libphonenumber is an open-source library developed by Google that can parse, validate, and format international phone numbers.
Its main capabilities include:

• Validating numbers based on each country’s rules.

• Converting numbers to standardized formats (E.164, national, international).

• Identifying number types such as mobile, landline, or toll-free.

It is widely used by communication platforms and applications that handle international numbers.

Installation

JavaScript / Node.js

npm install libphonenumber-js

Python

pip install phonenumbers

Java

<dependency>
  <groupId>com.googlecode.libphonenumber</groupId>
  <artifactId>libphonenumber</artifactId>
  <version>8.13.31</version>
</dependency>

Example in JavaScript

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const input = '3055551234'
const country = 'US'

const phoneNumber = parsePhoneNumberFromString(input, country)

if (phoneNumber && phoneNumber.isValid()) {
  console.log('E.164 format:', phoneNumber.number)
} else {
  console.log('Invalid number')
}

Example in Python

import phonenumbers

number = phonenumbers.parse("3055551234", "US")

if phonenumbers.is_valid_number(number):
    print(phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164))
else:
    print("Invalid number")

Summary of Best Practices

Additional Resources

• Google libphonenumber GitHub Repository

• libphonenumber-js Documentation

• phonenumbers Library for Python