Рекомендации по API сообщений WhatsApp

​

Перед началом работы

• Подключите и зарегистрируйте бизнес-номера телефонов WhatsApp, с которых будут отправляться сообщения.
• Сохраните свой API-ключ YCloud на сервере.
• Настройте подписанный эндпоинт Webhook для whatsapp.message.updated.
• Определите, как ваша система фиксирует согласие, отказы от рассылки, цель сообщений и сроки хранения данных.
• Назначьте ответственных за отправку, обработку Webhook и реагирование на инциденты.

​

Выбор эндпоинта отправки

​

Создание одной внутренней записи об отправке

​

Связывание ответа с Webhook статуса

​

1. Отправка сообщения

curl --request POST https://api.ycloud.com/v2/whatsapp/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "externalId": "order-ready-10001",
    "filterUnsubscribed": true,
    "filterBlocked": true,
    "template": {
      "name": "orders_pickup_ready_v2",
      "language": {
        "code": "en_US",
        "policy": "deterministic"
      }
    }
  }'

​

2. Сохранение принятого ответа

{
  "id": "MESSAGE_ID",
  "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "template",
  "status": "accepted",
  "externalId": "order-ready-10001",
  "createTime": "2026-08-27T09:00:00.000Z"
}

​

3. Применение последующих событий статуса

{
  "id": "evt_MESSAGE_STATUS_1",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-27T09:00:02.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "externalId": "order-ready-10001",
    "sendTime": "2026-08-27T09:00:01.000Z"
  }
}

​

Построение модели сходящихся статусов

1. Проверяйте подпись Webhook по исходному (raw) телу запроса.
2. Надежно сохраняйте событие, используя id события в качестве ключа дедупликации.
3. Своевременно возвращайте ответ 2xx, после чего обрабатывайте событие асинхронно.
4. Сопоставляйте whatsappMessage.id с внутренней записью об отправке.
5. Сохраняйте статус события и доступные метки времени сообщения. Сохраняйте исходные метаданные события, необходимые для аудита, но удаляйте ненужный контент сообщения.
6. Обновляйте текущее бизнес-представление, не отбрасывая противоречивые или более поздние данные. Рассматривайте read как подтверждение факта доставки, даже если отдельное событие delivered отсутствует.
7. Запрашивайте GET /whatsapp/messages/{id}, когда события конфликтуют, финальный статус задерживается сверх установленных целевых показателей обслуживания или если конвейер Webhook был недоступен.

​

Повторные попытки без создания дубликатов отправок

• Блокируйте или атомарно резервируйте внутренний бизнес-ключ.
• Проверьте, содержит ли запись уже id от YCloud или событие статуса.
• Не используйте новый externalId, чтобы скрыть более раннюю неоднозначную попытку.
• Останавливайте попытки после достижения настроенного лимита количества или времени жизни.
• Требуйте явного действия оператора перед повторным выполнением неоднозначной отправки.

​

Выбор шаблонов и сессионных сообщений

​

Эффективная работа с медиафайлами

• Проверяйте поддерживаемый MIME-тип и размер файла перед загрузкой. Не повторяйте попытку загрузки неподдерживаемого или превышающего лимиты файла без изменений.
• Загружайте файлы от имени того бизнес-номера телефона, с которого будет отправлено сообщение.
• Используйте возвращенный ID медиафайла повторно для регулярных отправок одного и того же утвержденного ресурса, пока он остается действительным. Загруженные медиафайлы хранятся 30 дней.
• Сохраняйте контрольную сумму ресурса, MIME-тип, ID медиафайла, отправителя и срок действия, чтобы воркеры не загружали один и тот же файл для каждого получателя заново.
• Выполняйте повторную загрузку после истечения срока действия или при изменении контекста отправителя.
• Используйте публичный URL-адрес, если схема сообщения требует ссылки, включая медиафайлы в заголовках интерактивных сообщений.
• Передавайте большие файлы потоком из хранилища, задавайте таймауты запросов и удаляйте временные локальные файлы после использования.

​

Контроль согласия и минимизация данных

​

Контроль пропускной способности пакетов

• ответы 429
• задержка запросов и таймауты
• ответы 5xx
• время нахождения в очереди или накопление повторных попыток
• задержка Webhook и необработанные сообщения со статусом accepted

​

Распространенные антипаттерны

• Пометка сообщения как доставленного, когда API возвращает accepted.
• Использование externalId в качестве ключа идемпотентности YCloud.
• Повторная отправка каждого ответа, отличного от 2xx, или таймаута без ограничения количества попыток.
• Использование sendDirectly для всего трафика.
• Предположение, что вебхуки уникальны, упорядочены или полны.
• Отправка сообщений в свободной форме за пределами окна обслуживания клиентов.
• Загрузка одного и того же медиафайла для каждого получателя.
• Использование фильтров подавления без фиксации согласия.
• Логирование ключей API, полных полезных нагрузок или избыточных персональных данных.
• Запуск пакетной обработки с неограниченным параллелизмом и без противодавления (backpressure).

​

Чек-лист перед запуском в продакшн

• Выбор эндпоинта соответствует рабочей нагрузке и требованиям к задержке.
• Правило уникальности в базе данных защищает внутренний бизнес-ключ.
• Для externalId, id YCloud и wamid определены и задокументированы отдельные роли.
• Первоначальные ответы остаются неокончательными до получения подтверждения статуса.
• Протестированы подписи вебхуков, дедупликация событий, быстрое подтверждение получения и повторная обработка.
• Запланированная задача выборки сверяет задержанные или отсутствующие события.
• Ошибки, допускающие и не допускающие повторные попытки, имеют ограниченные сценарии обработки.
• Правила шаблонов и сессионных окон проверяются перед отправкой.
• Загрузка медиафайлов валидируется, файлы используются повторно, срок их действия отслеживается, а очистка выполняется безопасно.
• Проверены механизмы согласия, отписки, черных списков, хранения данных и логирования.
• Очереди пакетной обработки имеют ограничения параллелизма, противодавление, дашборды и алерты.
• Операторы могут приостанавливать отправку и проверять неоднозначные попытки без их автоматического повтора.