Phone Number Normalization for WhatsApp (Country Code Addition) facebook for Woocmmerce 3.5.9

[jsballarini]

Facebook for WooCommerce - (Version 3.5.9)

Phone Number Normalization for WhatsApp

Overview

The plugin now automatically adds country calling codes to phone numbers when sending WhatsApp messages, based on the customer's billing or shipping country.

How It Works

Automatic Detection

When a customer places an order without including the country code in their phone number, the plugin:

1. Detects the country from billing or shipping address
2. Looks up the calling code for that country
3. Adds the code automatically to the phone number
4. Sends to WhatsApp API in the correct international format

Examples

Customer Country	Phone Entered	Normalized Phone
Brazil (BR)	11987654321	+5511987654321
USA (US)	2025551234	+12025551234
UK (GB)	7911123456	+447911123456
Germany (DE)	15112345678	+4915112345678
Mexico (MX)	5512345678	+525512345678

Phone Number Formats Supported

The helper handles various input formats:

• Plain numbers: 11987654321 → +5511987654321
• With formatting: (11) 98765-4321 → +5511987654321
• With spaces: 11 98765 4321 → +5511987654321
• Already normalized: +5511987654321 → +5511987654321 (no change)

Implementation

PhoneNumberHelper Class

Location: includes/Utilities/PhoneNumberHelper.php

use WooCommerce\Facebook\Utilities\PhoneNumberHelper;

$normalized = PhoneNumberHelper::normalize_phone_number($phone, $country_code);

Integration Points

1. Order Status Changed Event (facebook-commerce-whatsapp-utility-event.php)

   • Normalizes phone before sending ORDER_PLACED, ORDER_FULFILLED, ORDER_REFUNDED messages

2. WhatsApp Extension (includes/Handlers/WhatsAppExtension.php)

   • Normalizes phone in customer events API calls

Supported Countries

The helper includes calling codes for 180+ countries including:

• Americas: US, CA, BR, MX, AR, CL, CO, PE, etc.
• Europe: GB, DE, FR, IT, ES, PT, NL, BE, CH, etc.
• Asia: CN, JP, IN, KR, ID, TH, MY, PH, VN, SG, etc.
• Africa: ZA, EG, NG, KE, GH, TZ, MA, etc.
• Oceania: AU, NZ, FJ, PG, etc.
• Middle East: SA, AE, IL, TR, IQ, IR, etc.

Error Handling

• If country code is unknown, the phone number is returned unchanged
• A warning is logged for debugging purposes
• The message sending continues with the original phone number

Benefits

✅ No customer friction - Customers don't need to know international format
✅ Higher delivery rates - Correctly formatted numbers reach WhatsApp
✅ Global support - Works for customers worldwide
✅ Automatic - No configuration needed
✅ Safe - Doesn't modify already-formatted numbers

---

What was changed?

---

Changelog - Phone Number Normalization

Created Files

includes/Utilities/PhoneNumberHelper.php

• Class header and namespace
• PhoneNumberHelper class documentation
• Country codes array declaration
• Complete mapping of 180+ countries to calling codes (ISO 3166-1 alpha-2 → calling code)
• normalize_phone_number() method documentation
• Normalization implementation: sanitizes, checks for existing code, fetches country code and adds it
• sanitize_phone_number() method documentation
• Sanitization implementation: removes non-numeric characters, preserves leading +
• has_country_code() method documentation
• Checks if number starts with +
• get_calling_code() method documentation
• Fetches calling code from array, returns with + prefix

<?php
/**
 * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
 *
 * This source code is licensed under the license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @package FacebookCommerce
 */

namespace WooCommerce\Facebook\Utilities;

defined( 'ABSPATH' ) || exit;

/**
 * Helper class for phone number normalization and country code handling.
 *
 * @since 3.5.10
 */
class PhoneNumberHelper {

	/**
	 * Country calling codes mapping (ISO 3166-1 alpha-2 to calling code).
	 *
	 * @var array
	 */
	private static $country_calling_codes = array(
		'US' => '1', 'CA' => '1', 'BR' => '55', 'MX' => '52', 'AR' => '54', 'CL' => '56', 'CO' => '57',
		'PE' => '51', 'VE' => '58', 'EC' => '593', 'GT' => '502', 'CU' => '53', 'BO' => '591', 'HT' => '509',
		'DO' => '1', 'HN' => '504', 'PY' => '595', 'SV' => '503', 'NI' => '505', 'CR' => '506', 'PA' => '507',
		'UY' => '598', 'GY' => '592', 'SR' => '597', 'BZ' => '501', 'GF' => '594', 'FK' => '500',
		'GB' => '44', 'DE' => '49', 'FR' => '33', 'IT' => '39', 'ES' => '34', 'NL' => '31', 'BE' => '32',
		'CH' => '41', 'AT' => '43', 'PT' => '351', 'SE' => '46', 'NO' => '47', 'DK' => '45', 'FI' => '358',
		'PL' => '48', 'CZ' => '420', 'HU' => '36', 'RO' => '40', 'GR' => '30', 'IE' => '353', 'SK' => '421',
		'BG' => '359', 'HR' => '385', 'SI' => '386', 'LT' => '370', 'LV' => '371', 'EE' => '372', 'IS' => '354',
		'AL' => '355', 'MT' => '356', 'CY' => '357', 'LU' => '352', 'MC' => '377', 'SM' => '378', 'VA' => '379',
		'RU' => '7', 'UA' => '380', 'BY' => '375', 'MD' => '373', 'AM' => '374', 'GE' => '995', 'AZ' => '994',
		'CN' => '86', 'JP' => '81', 'IN' => '91', 'KR' => '82', 'ID' => '62', 'TH' => '66', 'MY' => '60',
		'PH' => '63', 'VN' => '84', 'SG' => '65', 'HK' => '852', 'TW' => '886', 'BD' => '880', 'PK' => '92',
		'LK' => '94', 'NP' => '977', 'MM' => '95', 'KH' => '855', 'LA' => '856', 'MO' => '853', 'BN' => '673',
		'AU' => '61', 'NZ' => '64', 'FJ' => '679', 'PG' => '675', 'NC' => '687', 'PF' => '689',
		'ZA' => '27', 'EG' => '20', 'NG' => '234', 'KE' => '254', 'ET' => '251', 'GH' => '233', 'TZ' => '255',
		'UG' => '256', 'DZ' => '213', 'SD' => '249', 'MA' => '212', 'AO' => '244', 'MZ' => '258', 'MG' => '261',
		'CM' => '237', 'CI' => '225', 'NE' => '227', 'BF' => '226', 'ML' => '223', 'MW' => '265', 'ZM' => '260',
		'SN' => '221', 'SO' => '252', 'TD' => '235', 'ZW' => '263', 'GN' => '224', 'RW' => '250', 'BJ' => '229',
		'TN' => '216', 'BI' => '257', 'SS' => '211', 'TG' => '228', 'SL' => '232', 'LY' => '218', 'LR' => '231',
		'MR' => '222', 'CF' => '236', 'ER' => '291', 'GM' => '220', 'BW' => '267', 'GA' => '241', 'GW' => '245',
		'MU' => '230', 'SZ' => '268', 'DJ' => '253', 'RE' => '262', 'KM' => '269', 'CV' => '238', 'ST' => '239',
		'SC' => '248', 'SA' => '966', 'AE' => '971', 'IL' => '972', 'TR' => '90', 'IQ' => '964', 'IR' => '98',
		'SY' => '963', 'JO' => '962', 'LB' => '961', 'YE' => '967', 'KW' => '965', 'OM' => '968', 'QA' => '974',
		'BH' => '973', 'PS' => '970', 'AF' => '93', 'KZ' => '7', 'UZ' => '998', 'TM' => '993', 'TJ' => '992',
		'KG' => '996', 'MN' => '976',
	);

	/**
	 * Normalizes a phone number by adding country calling code if missing.
	 *
	 * @param string $phone_number The phone number to normalize.
	 * @param string $country_code ISO 3166-1 alpha-2 country code.
	 * @return string Normalized phone number with country code.
	 */
	public static function normalize_phone_number( $phone_number, $country_code ) {
		if ( empty( $phone_number ) || empty( $country_code ) ) {
			return $phone_number;
		}

		$phone_number = self::sanitize_phone_number( $phone_number );
		
		if ( self::has_country_code( $phone_number ) ) {
			return $phone_number;
		}

		$calling_code = self::get_calling_code( $country_code );
		if ( empty( $calling_code ) ) {
			wc_get_logger()->warning(
				sprintf(
					__( 'Unknown country code: %s. Phone number not normalized.', 'facebook-for-woocommerce' ),
					$country_code
				)
			);
			return $phone_number;
		}

		return $calling_code . $phone_number;
	}

	/**
	 * Sanitizes phone number by removing non-numeric characters except leading +.
	 *
	 * @param string $phone_number The phone number to sanitize.
	 * @return string Sanitized phone number.
	 */
	private static function sanitize_phone_number( $phone_number ) {
		$phone_number = trim( $phone_number );
		$has_plus     = strpos( $phone_number, '+' ) === 0;
		$phone_number = preg_replace( '/[^0-9]/', '', $phone_number );
		return $has_plus ? '+' . $phone_number : $phone_number;
	}

	/**
	 * Checks if phone number already has a country code.
	 *
	 * @param string $phone_number The phone number to check.
	 * @return bool True if has country code, false otherwise.
	 */
	private static function has_country_code( $phone_number ) {
		return strpos( $phone_number, '+' ) === 0;
	}

	/**
	 * Gets the calling code for a country.
	 *
	 * @param string $country_code ISO 3166-1 alpha-2 country code.
	 * @return string|null Calling code with + prefix, or null if not found.
	 */
	private static function get_calling_code( $country_code ) {
		$country_code = strtoupper( $country_code );
		if ( isset( self::$country_calling_codes[ $country_code ] ) ) {
			return '+' . self::$country_calling_codes[ $country_code ];
		}
		return null;
	}
}

---

Modified Files

facebook-commerce-whatsapp-utility-event.php

Line 12: Added use WooCommerce\Facebook\Utilities\PhoneNumberHelper;

Lines 94-99 (BEFORE):

$has_whatsapp_consent    = $wa_billing_consent_enabled || $wa_shipping_consent_enabled;
$should_use_billing_info = isset( $billing_phone_number ) && $wa_billing_consent_enabled;
$billing_phone_number  = $order->get_billing_phone();
$shipping_phone_number = $order->get_shipping_phone();
$phone_number          = $should_use_billing_info ? $billing_phone_number : $shipping_phone_number;
$country_code = $should_use_billing_info ? $order->get_billing_country() : $order->get_shipping_country();

Lines 94-103 (AFTER):

$has_whatsapp_consent    = $wa_billing_consent_enabled || $wa_shipping_consent_enabled;
$should_use_billing_info = $wa_billing_consent_enabled;
$billing_phone_number  = $order->get_billing_phone();
$shipping_phone_number = $order->get_shipping_phone();
$raw_phone_number      = $should_use_billing_info ? $billing_phone_number : $shipping_phone_number;
$country_code          = $should_use_billing_info ? $order->get_billing_country() : $order->get_shipping_country();
// Normalize phone number with country code
$phone_number          = PhoneNumberHelper::normalize_phone_number( $raw_phone_number, $country_code );

Changes:

• Line 95 Removed isset( $billing_phone_number ) check (variable didn't exist yet)
• Line 98: Renamed $phone_number to $raw_phone_number
• Lines 100: Added comment and helper call to normalize phone

---

includes/Handlers/WhatsAppExtension.php

Line 16: Added use WooCommerce\Facebook\Utilities\PhoneNumberHelper;

Lines 162-174 (BEFORE):

$whatsapp_connection = $plugin->get_whatsapp_connection_handler();
$is_connected        = $whatsapp_connection->is_connected();
if ( ! $is_connected ) {
    wc_get_logger()->info(
        sprintf(
            __( 'Customer Events Post API call for Order id %1$s Failed due to failed connection ', 'facebook-for-woocommerce' ),
            $order_id,
        )
    );
    return;
}
$wa_installation_id = $whatsapp_connection->get_wa_installation_id();

Lines 162-176 (AFTER):

$whatsapp_connection = $plugin->get_whatsapp_connection_handler();
$is_connected        = $whatsapp_connection->is_connected();
if ( ! $is_connected ) {
    wc_get_logger()->info(
        sprintf(
            __( 'Customer Events Post API call for Order id %1$s Failed due to failed connection ', 'facebook-for-woocommerce' ),
            $order_id,
        )
    );
    return;
}
// Normalize phone number with country code
$phone_number        = PhoneNumberHelper::normalize_phone_number( $phone_number, $country_code );
$wa_installation_id = $whatsapp_connection->get_wa_installation_id();

Changes:

• Line 174: Added comment and phone normalization before fetching installation_id

---

Summary of Changes

Total Lines Added: 130 lines

• PhoneNumberHelper.php: 128 lines (new file)
• facebook-commerce-whatsapp-utility-event.php: +3 lines
• WhatsAppExtension.php: +2 lines

Total Lines Modified: 3 lines

• facebook-commerce-whatsapp-utility-event.php: 1 line modified
• WhatsAppExtension.php: 0 lines modified (additions only)

Impact

• ✅ Automatic phone normalization at 2 critical points
• ✅ Support for 180+ countries
• ✅ Zero breaking changes
• ✅ Backward compatible (already formatted numbers remain unchanged)

[sharunaanandraj]

jsballarini Thank you for your suggestion and for taking the time to contribute to the project!
We appreciate your idea on normalizing WhatsApp phone numbers. Currently, we handle all phone number normalization logic on the Meta side, which helps us streamline debugging and maintain consistency across platforms. To keep the WooCommerce integration as lightweight as possible, we prefer not to add additional normalization logic here for now.

We’ll keep your suggestion in mind if our approach changes in the future. Thanks again for your contribution and understanding!

[jsballarini]

Hi @sharunaanandraj
I'm participating in the WhatsApp testing phase of the plugin, and I even shared a feedback document with you, along with fabi, ardsou, and gilma (I've hidden some letters to maintain privacy).
Since it is only a domestic market, my ecommerce does not request a country code and the messages were not being sent, so I made this change and it is sending normally.