Формат номера E.164: как преобразовать и проверить номер

Почему API для SMS и WhatsApp требуют E.164?

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

Что Meta говорит о номерах WhatsApp?

В документации Meta о форматах номеров телефонов пользователей WhatsApp сказано, что в запросах на отправку сообщений поддерживаются знаки «+», дефисы, скобки и пробелы, и настоятельно рекомендуется указывать знак «+» и код страны. Если знака «+» нет, к номеру добавляется код страны отправителя, и сообщение может уйти на неверный номер. Пример Meta: для отправителя из Индии (код 91) (631) 555-1234 доставляется на +916315551234, а +1 (631) 555-1234 доставляется правильно. Meta также отмечает, что для Бразилии и Мексики Cloud API может изменять лишний префикс, который встречается в некоторых номерах, и называет такое поведение стандартным.

Надёжный подход: храните чистый E.164 и отправляйте именно его.

А что с SMS?

API для SMS тоже ожидают полный международный номер. Некоторым нужны цифры без знака «+»; формат различается между API и протоколами, поэтому изучите документацию используемого вами API и проверьте на своём номере. Рабочие примеры см. в материалах отправка SMS через API и отправка сообщения WhatsApp через API.

Как проверять и нормализовать номера в коде?

Используйте регулярное выражение для быстрой проверки формы и библиотеку для настоящей проверки.

Распространённая проверка формы E.164:

// Plus, a non-zero first digit, then 1 to 14 more digits: 15 digits at most
const E164 = /^\+[1-9]\d{1,14}$/;

function looksLikeE164(value) {
  return E164.test(value);
}

looksLikeE164("+971501234567"); // true
looksLikeE164("0501234567");    // false: no plus or country code
looksLikeE164("+0501234567");   // false: country codes do not start with 0

Регулярное выражение проверяет только длину и символы. Оно пропустит +99999999999, хотя такого номера не существует. Для настоящей проверки используйте библиотеку Google с открытым исходным кодом libphonenumber, предназначенную для разбора, форматирования и проверки международных телефонных номеров, доступную для Java, C++ и JavaScript, с портами сообщества для других языков. В её README isValidNumber описана как полная проверка для региона по данным о длине и префиксах, а также показано форматирование разобранного номера в E.164.

# pip install phonenumbers  (a Python port of libphonenumber)
import phonenumbers

def to_e164(raw, default_region):
    try:
        number = phonenumbers.parse(raw, default_region)  # e.g. "AE", "SA", "GB"
    except phonenumbers.NumberParseException:
        return None
    if not phonenumbers.is_valid_number(number):
        return None
    return phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)

print(to_e164("050 123 4567", "AE"))   # +971501234567 if the number is valid for the UAE
print(to_e164("+44 7700 900123", "GB"))

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

Нормализуйте при вводе: в форме регистрации, при импорте в CRM или в API, а не при отправке. Номер, записанный двумя способами, становится двумя контактами, и каждый получит одну и ту же кампанию.

Как исправить номера телефонов в таблице?

Задайте столбцу с телефонами текстовый формат до того, как вводить или вставлять номера. Типичные проблемы:

Microsoft сообщает, что Excel удаляет ведущие нули и преобразует большие числа в экспоненциальную запись, а номера, введённые до применения текстового формата, нужно вводить заново. При прямом открытии файла CSV Excel применяет к каждому столбцу форматы по умолчанию, поэтому используйте мастер импорта текста или «Из текста/CSV», чтобы пометить столбец телефонов как текст.

Для списка мобильных номеров ОАЭ, хранящихся в виде 050 123 4567 в столбце A, эта формула собирает E.164 как текст:

="+971"&RIGHT(SUBSTITUTE(A2," ",""),9)

Она берёт последние девять цифр после удаления пробелов, поэтому подходит только для номеров такого вида. Перед сохранением в CSV скопируйте результат и вставьте как значения. Форматтер номеров преобразует номер без формулы, а наше руководство по массовой SMS-рассылке из Excel или CSV показывает весь процесс загрузки.

Пример: очистка списка клиентов

«Souq Rafiq» (вымышленный пример), розничная компания из Дубая, выгружает 8000 контактов из трёх систем с номерами вида 0501234567, 971 50 123 4567, +971-50-123-4567 и 00971501234567.

1. Аналитик добавляет столбец страны по стране выставления счёта каждого клиента.
2. Скрипт разбирает каждую строку с этой страной в качестве региона по умолчанию, так что все четыре формата превращаются в +971501234567.
3. Строки, не прошедшие проверку, попадают на лист для проверки, а не отправляются.
4. Дубликаты удаляются после нормализации, которая сводит четыре формата к одному контакту.
5. HLR-проверка перед кампанией отмечает неактивные номера. См. HLR-проверка: объяснение.
6. Чистый столбец сохраняется как текст и загружается.

Именно нормализация в начале делает проверку на дубликаты рабочей; до неё один и тот же клиент выглядел как четыре человека.

Какие бывают типичные ошибки?

• Всегда отбрасывать ведущий нуль. В некоторых странах, например в Италии, нет префикса междугородной связи.
• Сохранять нуль и добавлять код страны, получая +9710501234567.
• Отправлять в WhatsApp без знака «+», из-за чего добавляется код страны отправителя.
• Использовать регулярное выражение как проверку. Оно проверяет форму, а не допустимость.
• Позволять Excel воспринимать телефоны как числа, теряя нули или переходя на экспоненциальную запись.
• Нормализовать при отправке вместо ввода.
• Считать, что допустимый формат означает досягаемый номер. Перенесённые или отключённые номера всё равно дают сбой.
• Доверять статичной таблице. Планы нумерации меняются; используйте поддерживаемую библиотеку.

Чем помогает OmniChannels.ai

OmniChannels.ai принимает международные номера для SMS и WhatsApp через один REST API, а его кампании принимают загрузку Excel и CSV с предпросмотром и фильтрацией дубликатов. BroadNet предлагает HLR-проверку и проверку номера, так что вы можете убедиться, что правильно оформленный номер активен. Точные поля запросов смотрите в документации SMS API и документации WhatsApp API, а по вопросам подключения поговорите с нашей командой.