Формат E.164 для проверок через WhatsApp API: почему локальные форматы приводят к ошибкам

В статье дается определение формата E.164, описываются ошибки при использовании локальных форматов, которые приводят к неверным результатам проверок в WhatsApp, и приводится процедура нормализации для API и пакетных задач.

E.164 — это международный стандарт нумерации ITU: код страны, за которым следует национальный номер (максимум 15 цифр), записанный в каноническом виде с ведущим знаком «плюс» без пробелов, тире или префиксов выхода на междугородную связь. Проверки через WhatsApp API требуют, чтобы номера были представлены в этом международном формате, так как локальный формат, например 07700 900123, не указывает, к какой стране он относится. Нормализация каждого номера до E.164 перед проверкой гарантирует, что результат будет соответствовать именно тому номеру, который вы имели в виду.

Что такое формат E.164

ITU-T Recommendation E.164 определяет план международной нумерации для сетей электросвязи общего пользования. Для практической работы с данными номер в формате E.164 обладает тремя характеристиками:

• Он начинается с кода страны, состоящего из одной–трех цифр, например 1, 44, 55 или 971.
• Далее следует национальный значимый номер без префикса выхода на междугородную связь (часто это ведущий 0).
• Общая длина номера не превышает 15 цифр, а каноническая форма записи представляет собой знак «плюс», за которым следуют только цифры, например +447700900123.

Важно понимать, что формат E.164 исключает: международные префиксы набора (например, 00 или 011), скобки, пробелы и добавочные номера.

Как локальные форматы нарушают работу проверок WhatsApp API

Большинство ресурсов по этой теме ограничиваются лишь определением. Практическая проблема заключается в том, как обычные данные из CRM превращаются в ошибочные результаты поиска. Вот основные сценарии, которые к этому приводят:

Руководство Meta по формату телефонных номеров пользователей WhatsApp наглядно показывает риски при отправке сообщений: без знака «плюс» и кода страны может быть автоматически подставлен код страны отправителя. Например, номер «(631) 555-1234», отправленный с индийского бизнес-аккаунта, может быть интерпретирован как +916315551234 вместо нужного номера в США. Та же неоднозначность касается и любой проверки. Если проверка выполняется для неверного номера, результат будет относиться к другому абоненту.

Процедура нормализации перед проверкой номеров

Выполняйте эти шаги перед любой проверкой в WhatsApp, независимо от того, передаются ли номера через API или в файле.

1. Храните номера как текст. Ячейки с числовым форматом в таблицах удаляют знак «плюс» и ведущие нули, а длинные значения могут преобразовываться в экспоненциальную форму.
2. Сохраняйте код страны вместе с записью. Для нормализации номеров, введенных в локальном формате, требуется регион по умолчанию; берите его из поля страны в контакте, а не из местоположения отдела продаж.
3. Используйте проверенную библиотеку для парсинга. Библиотека Google libphonenumber анализирует исходную строку и регион, преобразуя их в код страны и национальный номер в формате E.164. Функция isPossibleNumber проверяет только длину, тогда как isValidNumber также использует информацию о префиксах региона.
4. Изолируйте ошибки. Значения, которые не удалось распознать или которые не прошли валидацию, должны отправляться в очередь на проверку, а не в систему поиска.
5. Удаляйте дубликаты после нормализации. «07700 900123» и «+44 7700 900123» становятся одним и тем же номером только после этого шага.

Эти шаги отвечают на узкий вопрос: является ли строка правдоподобным международным номером для своего региона? Наличие аккаунта WhatsApp — это отдельный вопрос, на который отвечает только проверка регистрации.

Использование E.164 с API и файлами WA Lookup

API WA Lookup в режиме реального времени принимает один номер телефона в формате E.164 для POST /api/v1/check вместе с заголовком X-API-Key и параметром service_type, который выбирает Проверка регистрации в WhatsApp, Проверка аватара WhatsApp или Проверка аккаунта WhatsApp Business. Метод POST /api/v1/batch-check принимает до 100 номеров за запрос, и к каждому из них применяется та же процедура нормализации. Обращайтесь к актуальной документации API для уточнения структуры тела запроса.

Для пакетных задач с файлами действуют свои требования к формату:

• Только TXT или CSV, один номер с кодом страны на строку.
• Файл должен содержать номера преимущественно одной страны. Если 10% или более номеров относятся к другим странам, предварительная проверка отклонит файл, поэтому разделяйте данные по коду страны после нормализации.
• Номера материкового Китая (+86), Гонконга (+852) и Макао (+853) не принимаются в пакетных файлах; для этих регионов доступны только одиночные проверки в реальном времени.

Распространенные ошибки E.164, требующие контроля

• Предположение, что все номера являются внутренними. Регион по умолчанию — это лишь запасной вариант для локального ввода, а не правило для каждой строки.
• Удаление знака «плюс» при хранении. Сохраняйте каноническую форму в CRM; конвертируйте ее только в том случае, если конкретная система требует иного представления.
• Сохранение добавочных номеров. Удаляйте текст добавочных номеров, например «ext. 204», перед проверкой; в E.164 для них нет места.
• Приравнивание нормализации к получению согласия. Правильно отформатированный зарегистрированный номер все равно требует получения согласия (opt-in) перед рассылкой в соответствии с WhatsApp Business Messaging Policy.
• Смешивание форматов в одном столбце. Использование одного нормализованного столбца для проверок и рассылок позволяет избежать расхождения данных.

Часто задаваемые вопросы

Как командам определить, находится ли сохраненный номер уже в формате E.164?

Значение начинается со знака «плюс», после него содержатся только цифры, после кода страны нет префикса выхода на связь, а общая длина составляет 15 цифр или меньше. Парсинг с помощью библиотеки, такой как libphonenumber, и обратное форматирование в E.164 должны возвращать ту же самую строку.

Имеет ли значение ведущий знак «плюс» для проверок и сообщений в WhatsApp?

Он обозначает номер как международный. Руководство Meta рекомендует включать как знак «плюс», так и код страны, поскольку номер без них может быть интерпретирован с кодом страны отправителя. Для WA Lookup следуйте актуальной документации API относительно ожидаемой строки в запросе.

Что делать с номерами, которые не прошли нормализацию?

Отправляйте их в очередь на ручную проверку, сохраняя исходное значение и страну записи. Проверка неоднозначной или некорректно сформированной строки расходует баланс и может привязать результат к неверному номеру.

Почему пакетный файл должен содержать номера одной страны?

Пакетные задачи подаются для выбранной страны, и предварительная проверка отклоняет файлы, в которых 10% или более номеров относятся к другим странам. Нормализация до E.164 упрощает разделение смешанного экспорта по кодам стран.

Узнать больше

Выберите информацию о продукте, соответствующую следующему шагу в вашем рабочем процессе.

• Перейти к документации продукта →
• Связаться с командой →