После регистрации аккаунта разработчика Meta и получения ключа API, для вызова официальной конечной точки (например, https://graph.facebook.com/v19.0/<PHONE_NUMBER_ID>/messages) с использованием POST-запроса, необходимо передать заголовки Authorization: Bearer <ACCESS_TOKEN> и Content-Type: application/json, а также JSON-сообщение (пример: {"messaging_product":"whatsapp","to":"886912345678","text":{"body":"Тестовое сообщение"}}), обратите внимание, что ограничение частоты составляет 200 сообщений в секунду.

Регистрация аккаунта и получение учетных данных

Согласно официальным данным Meta, в настоящее время более 5 миллионов компаний используют WhatsApp Business API для общения с клиентами, при этом средняя скорость ответа увеличилась до​​3 минут​​, а открываемость сообщений достигает​​98%​​. Процесс регистрации обычно занимает​​1-3 рабочих дня​​, но при выборе канала через реселлера может быть сокращен до​​2 часов​​. Ниже приведены конкретные детали операции:

Сначала перейдите на официальную платформу разработчиков Meta (developers.facebook.com), нажмите «Создать приложение» и выберите тип «Бизнес». Система попросит вас заполнить название приложения (рекомендуется использовать английское название компании), контактный адрес электронной почты (должен соответствовать корпоративному домену) и выбрать «WhatsApp» в качестве основного продукта. Здесь следует отметить: название приложения после отправки​​не может быть изменено​​, и каждая учетная запись компании может создать максимум​​5 приложений​​. После завершения базовой регистрации платформа сгенерирует​​64-значный идентификатор приложения​​ (App ID) и​​32-значный секретный ключ​​ (App Secret), эти два кода необходимо немедленно загрузить и сохранить, так как секретный ключ отображается только один раз.

Далее необходимо пройти бизнес-верификацию. Компания должна загрузить официальные коммерческие документы (свидетельство о регистрации бизнеса, налоговое свидетельство или свидетельство о регистрации компании), формат файла ограничен PDF/JPG/PNG, а размер не должен превышать​​5 МБ​​. Время проверки обычно составляет​​24-72 часа​​, но если вы решите сотрудничать с сертифицированным BSP (Business Solution Provider), вы можете пропустить этот шаг и напрямую использовать их ускоренный канал. После прохождения проверки система откроет доступ к API и предоставит​​постоянный базовый токен доступа​​ (Access Token), срок действия этого токена по умолчанию составляет​​90 дней​​, но может быть продлен с помощью механизма регулярного обновления.

После получения базового токена также необходимо привязать номер телефона. Каждое приложение может привязать максимум​​25 номеров​​, номер должен быть физическим номером, который ранее не был зарегистрирован в WhatsApp Business (рекомендуется приобрести новую SIM-карту). Во время привязки необходимо оплатить​​фиксированную ежемесячную плату​​ (около​​0,5-5 долларов США​​ в зависимости от страны) и получить​​6-значный код подтверждения​​ по SMS или голосовому сообщению. После завершения привязки платформа сгенерирует эксклюзивный​​URL конечной точки API​​ (включающий 128-битный зашифрованный параметр), этот URL является основным учетным данным для всех последующих вызовов API.

Наконец, необходимо настроить Webhook для приема сообщений. Сервер должен поддерживать​​протокол HTTPS​​ и быть настроен на шифрование​​TLS 1.2 или выше​​, минимальный интервал между отправкой сообщений может быть установлен на​​100 миллисекунд​​. Рекомендуется предварительно настроить балансировщик нагрузки, Meta официально требует, чтобы время ответа сервера было менее​​300 миллисекунд​​, в противном случае будет запущен механизм повторной попытки (максимум 3 повтора, каждый с интервалом 5 минут). После завершения всех настроек не забудьте включить «Режим отладки API» в бэкэнде, который будет записывать все​​исходные данные запроса в формате JSON​​, что удобно для последующего устранения неполадок. Общая стоимость всего процесса составляет около​​15-50 долларов США​​ (без учета ежемесячной платы за номер), если оформлять через реселлера, обычно взимается​​единовременная плата за техническое обслуживание в размере 50-100 долларов США​​.

Настройка прав доступа к API

Согласно официальной статистике Meta, более 30% сбоев вызовов API вызваны ошибками в настройке разрешений. Правильная настройка разрешений может увеличить процент доставки сообщений в среднем с 75% до 99,8% и сократить время ответа до 500 миллисекунд. Настройка разрешений включает 4 основных уровня: Бизнес-уровень (Business Level), Уровень приложения (App Level), Уровень номера (Phone Level) и Уровень функций (Feature Level), каждое разрешение должно быть проверено отдельно, общее время проверки занимает около 2-6 часов. Ниже приведены конкретные детали операции:

Сначала войдите в бэкэнд Meta for Developers, найдите вкладку «Разрешения» в «Настройках приложения». Здесь будут отображаться 13 основных переключателей разрешений, основные разрешения, которые необходимо включить, включают:​​messages​​ (отправка и получение сообщений),​​contacts​​ (чтение контактов),​​webhooks​​ (веб-перехватчики) и​​message_templates​​ (шаблонные сообщения). Каждое разрешение требует отдельной подачи на проверку после включения, проверка разрешения для шаблонных сообщений является самой строгой, обычно требуется предоставить как минимум 3 предустановленных содержимых сообщения (каждое не более 1024 символов) и указать частоту отправки (например, максимум 200 сообщений в час).

Особое внимание следует уделить процессу привязки​​разрешений телефонного номера​​. Каждый номер должен быть привязан к соответствующим правам на операции API, включая: возможность отправлять мультимедийные файлы (изображения/видео/документы), возможность совершать голосовые вызовы, возможность отправлять информацию о местоположении. Разрешение на мультимедиа по умолчанию отключено, для его включения требуется загрузить описание типа файла (например, ограничение формата jpg/png, один файл не более 16 МБ). Разрешение на голосовую связь доступно только для аккаунтов, прошедших бизнес-верификацию, и минимальная плата за каждый звонок составляет 0,015 доллара США.

Настройка Webhook является ключевым узлом в конфигурации разрешений. Необходимо заполнить предварительно подготовленный URL обратного вызова HTTPS в поле «Веб-перехватчики» (рекомендуется использовать обратный прокси-сервер Nginx) и настроить 6 типов событий для получения:​​message​​ (получение сообщения),​​status​​ (обновление статуса),​​template​​ (статус шаблона),​​contact​​ (изменение контакта),​​location​​ (обновление местоположения),​​error​​ (журнал ошибок). Сервер должен ответить кодом состояния 200 OK в течение 3 секунд, в противном случае сервер Meta запустит механизм повторной попытки (максимум 5 повторов, каждый с интервалом 15 минут).

Ниже приведены стандарты настройки параметров для основных категорий разрешений:

В «Расширенных настройках» можно настроить лимит вызовов API в минуту/час/день, значение по умолчанию составляет 1000 запросов в минуту (может быть увеличено до 10000 запросов в минуту в зависимости от бизнес-потребностей). Рекомендуется включить​​режим автоматического масштабирования​​, когда объем запросов непрерывно превышает 80% от установленного значения в течение 5 минут, система автоматически увеличит квоту на 20%. Все изменения разрешений немедленно записываются в журнал аудита, где можно отследить все операции за последние 180 дней. После завершения настройки обязательно нажмите кнопку «Тестирование симуляции разрешений», система автоматически запустит 25 пунктов проверки, время проверки занимает около 8 минут, для официального включения службы API необходимо достичь 100% прохождения.

Написание кода для отправки сообщений

Согласно фактической статистике WhatsApp Business API, правильно оптимизированный код отправки может увеличить процент доставки сообщений с 92% до 99,7% и сократить среднее время ответа до 800 миллисекунд. Стандартный модуль отправки обычно включает 5 основных модулей: Модуль аутентификации (Authentication), Модуль построения полезной нагрузки (Payload Building), Модуль шифрования (Encryption), Модуль отправки (Dispatching) и Модуль повторной попытки (Retry Mechanism), время выполнения каждого модуля должно контролироваться в пределах 200 миллисекунд.

В модуле аутентификации необходимо включить 3 ключевых параметра в заголовок каждого HTTP-запроса: заголовок Authorization должен использовать формат Bearer Token (длина 64 символа), Content-Type должен быть установлен на application/json, и обязательно должен быть указан номер версии API (например, v17.0). Срок действия токена обычно составляет 24 часа, после истечения срока действия его необходимо обновить с помощью процесса OAuth 2.0 (срок действия токена обновления составляет 60 дней). Рекомендуется реализовать механизм автоматического обновления токена в коде, который автоматически запускает процесс обновления при обнаружении кода ошибки 401, этот процесс обычно занимает 1500 миллисекунд.

Модуль построения полезной нагрузки должен строго соответствовать структуре JSON, установленной Meta. Стандартная полезная нагрузка текстового сообщения включает 12 обязательных полей и 8 необязательных полей, общий размер не должен превышать 10 КБ. Ниже приведено сравнение структур основных типов сообщений:

Особое внимание: все медиафайлы должны быть сначала загружены на сервер Meta для получения идентификатора медиа (длина 26 символов), этот процесс загрузки обычно занимает 3-5 секунд (в зависимости от размера файла). Полученный идентификатор медиа действителен в течение 30 дней и может быть использован повторно.

Модуль шифрования требует использования протокола TLS 1.2 или выше для сквозного шифрования. Рекомендуется использовать алгоритм AES-256-GCM для шифрования тела сообщения, длина ключа должна достигать 256 бит. Каждый запрос должен генерировать уникальный вектор инициализации (IV, длина 12 байт) и тег аутентификации (Authentication Tag, длина 16 байт). Процесс шифрования должен быть выполнен локально, общая задержка, добавленная процессом шифрования и дешифрования, должна контролироваться в пределах 300 миллисекунд.

Модуль отправки должен обрабатывать проблемы нестабильности сети. Рекомендуется установить 3-уровневый механизм тайм-аута: тайм-аут подключения (Connect Timeout) установлен на 3 секунды, тайм-аут отправки (Write Timeout) установлен на 5 секунд, тайм-аут чтения (Read Timeout) установлен на 10 секунд. Когда сервер возвращает ошибку 5xx, должен немедленно запускаться механизм повторной попытки (максимум 3 повтора, каждый с увеличенным интервалом: первый 2 секунды, второй 4 секунды, третий 8 секунд). Также необходимо отслеживать частоту вызовов API и строго соблюдать базовое ограничение скорости 1 сообщение в секунду (можно подать заявку на увеличение до 5 сообщений в секунду).

Тестирование процесса отправки

Согласно фактическим отраслевым данным, системы отправки сообщений WhatsApp, не прошедшие достаточного тестирования, в среднем имеют 12% сбоев доставки, в то время как системы, прошедшие полный процесс тестирования, могут снизить этот показатель до менее 0,3%. Полный цикл тестирования обычно занимает 72 часа, включая 3 основных этапа: модульное тестирование (охват должен достигать 95%), интеграционное тестирование (моделирование 1000 параллельных пользователей) и стресс-тестирование (непрерывная работа в течение 24 часов). В процессе тестирования необходимо отслеживать 17 ключевых показателей, наиболее важными из которых являются процент успешной доставки, медианное время ответа и пиковый уровень ошибок. Ниже приведены конкретные детали реализации тестирования:

Сначала при создании тестовой среды необходимо использовать среду-песочницу (Sandbox Environment), предоставленную Meta, эта среда полностью изолирована от производственной среды, но имеет идентичный функционал. Среда-песочница поддерживает моделирование до 50 тестовых номеров, каждый номер может отправлять 1000 бесплатных тестовых сообщений в месяц. Во время тестирования необходимо настроить специальные учетные данные API, эти учетные данные действительны в течение 30 дней и могут использоваться только в среде-песочнице. Рекомендуется использовать инструменты автоматизированного тестирования для создания тестовых скриптов, моделирующих поведение реальных пользователей: включая отправку текстовых сообщений (60%), мультимедийных сообщений (25%) и шаблонных сообщений (15%).

Установка пороговых значений ключевых показателей тестирования: процент успешной доставки должен быть ≥99,5%, среднее время ответа должно быть ≤1200 миллисекунд, уровень ошибок должен быть ≤0,2%, доступность системы должна быть ≥99,9%. Для каждого показателя необходимо установить порог предупреждения (предупреждение при достижении 80% лимита) и порог опасности (немедленное прекращение тестирования при достижении 95% лимита).

На этапе функционального тестирования необходимо проверить 8 основных сценариев: нормальная отправка сообщений, сообщения с вложениями, массовая рассылка сообщений, проверка шаблонных сообщений, получение обратного вызова статуса, механизм обработки ошибок, срабатывание ограничения скорости и логика автоматического повтора. Для каждого сценария должно быть выполнено не менее 200 тестовых примеров, общее количество тестов не менее 1600. Особое внимание следует уделить тестированию шаблонных сообщений, поскольку это требует предварительной отправки шаблона на проверку (время проверки 2-48 часов), тестирование должно охватывать все поддерживаемые форматы переменных: текстовые переменные (до 10), валютные переменные (поддержка 42 валют), переменные даты и времени (поддержка 12 форматов) и медиа-переменные (поддержка изображений и документов).

Тестирование производительности должно проводиться на трех уровнях интенсивности: сначала базовое нагрузочное тестирование (моделирование отправки 5 сообщений в секунду, длительность 1 час), затем тестирование пиковой нагрузки (моделирование 20 сообщений в секунду, длительность 30 минут) и, наконец, тестирование на выносливость (моделирование 10 сообщений в секунду, непрерывная работа в течение 24 часов). В процессе необходимо записывать 17 показателей производительности системы, включая: использование ЦП (должно быть ниже 70%), использование памяти (должно быть ниже 80%), пропускная способность сети (должна достигать 100 Мбит/с), время ответа базы данных (должно быть ниже 50 миллисекунд). Особое внимание следует уделить поведению системы при достижении предела нагрузки, чтобы гарантировать, что уровень ошибок не поднимется внезапно выше 5%.

Этап тестирования в реальной среде требует выбора 3 различных периодов времени: рабочее утро 10-12 часов (пиковый период), вечер 8-10 часов (второй пиковый период) и ночь 2-4 часа (низкий период). Каждый период длится 2 часа, общее количество отправленных сообщений контролируется в пределах 500. Во время тестирования необходимо отслеживать статус сообщений в режиме реального времени, записывая среднее время от отправки до доставки (должно быть в пределах 3 секунд), среднее время от доставки до прочтения (обычно колеблется в пределах 60 секунд). В то же время необходимо проверить механизм обратного вызова: убедиться, что 100% обновлений статуса правильно отправляется в Webhook, а задержка обработки составляет менее 500 миллисекунд.