Перейти к основному содержанию

Что это такое

WhatsApp Messages API отправляет шаблонные, текстовые, графические, видео-, аудиосообщения, документы, стикеры, геолокации, интерактивные сообщения, контакты и реакции с подключенного бизнес-номера WhatsApp.

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

  • Сохраните свой API-ключ YCloud в YCLOUD_API_KEY.
  • Подключите WhatsApp Business Account и номер телефона к YCloud.
  • Получите номер телефона отправителя в формате E.164, а также номер телефона получателя, BSUID или родительский BSUID.
  • Для стандартной отправки шаблонов используйте шаблон со статусом APPROVED.
  • Если в сообщении используется ID медиафайла YCloud, сначала загрузите медиафайл.

Принцип работы

Выберите эндпоинт в зависимости от того, когда YCloud должен отправить сообщение в WhatsApp Business API. Оба эндпоинта возвращают объект сообщения YCloud. Первоначальный ответ не подтверждает окончательную доставку. Последующие изменения статуса приходят через Webhook-уведомления whatsapp.message.updated.

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

Выберите одобренный шаблон, принадлежащий вашему подключенному WABA. Укажите свои значения для отправителя, получателя, имени шаблона и языка, затем отправьте:
Сохраните возвращенный id и отслеживайте его события whatsapp.message.updated. Ответ accepted означает, что запрос поступил в обработку, а не то, что клиент его получил. Настройте как whatsapp.message.updated, так и whatsapp.inbound_message.received, если вам нужны отслеживание доставки и получение ответов.

Выбор шаблона или сессионного сообщения

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

Прямая отправка для утилитарного контента и контента аутентификации

Direct Send поддерживает инициированные бизнесом утилитарные сообщения и сообщения аутентификации без предварительного создания шаблонов сообщений. YCloud также поддерживает преобразование существующих утилитарных шаблонов. Direct Send работает с любой из конечных точек отправки. Конечная точка sendDirectly управляет синхронной отправкой; сама по себе она не включает Direct Send. Для аутентификации Direct Send принимает текст или явную интерактивную кнопку OTP. Шаблон аутентификации нельзя преобразовать в сообщение Direct Send. Следуйте рекомендациям по Direct Send относительно критериев допуска, запросов, преобразования шаблонов, лимитов и событий аккаунта.

Выбор оптимального времени отправки

Подбирайте время отправки с учетом назначения сообщения и местного времени получателя.
  • Отправляйте OTP и другие срочные сообщения немедленно. Используйте POST /whatsapp/messages/sendDirectly, когда для продолжения рабочего процесса требуется результат отправки.
  • Отправляйте транзакционные обновления в момент совершения соответствующего события, например оплаты, отправки заказа или переноса встречи.
  • Планируйте маркетинговые рассылки на разумные часы в часовом поясе получателя. Используйте собственные данные о доставке, прочтениях и конверсиях для тестирования различных временных интервалов для каждой аудитории, вместо того чтобы полагаться на один универсальный оптимальный час.
  • Запускайте запланированную кампанию на небольшой группе получателей. Проверьте показатели доставки, откликов и отписок перед отправкой остальной части аудитории.
  • Избегайте повторных отправок при задержке сообщения. Сохраните externalId и обработайте Webhook-уведомления whatsapp.message.updated, прежде чем принимать решение о повторной попытке.

Запрос

Для маркетинговых шаблонов с Max Price оба эндпоинта отправки принимают bidSpec.per_message_bid_multiplier. Опустите весь объект bidSpec, чтобы использовать множитель 1. Сведения о множителях для стран, лимитах ставок и вебхуках с итоговой стоимостью см. в руководстве по интеграции Max Price. Выберите один из приведенных выше эндпоинтов, затем используйте тело запроса, соответствующее типу сообщения. Значение from — это ваш подключенный бизнес-номер телефона WhatsApp. Укажите получателя с помощью to в формате E.164 или с помощью recipient, установив значение BSUID либо родительского BSUID.

Общие поля запроса

filterUnsubscribed и filterBlocked применяются только к POST /whatsapp/messages; они не применяются к sendDirectly. Отфильтрованный сообщение в очереди завершается ошибкой с RECIPIENT_UNSUBSCRIBED или RECIPIENT_IN_BLOCK_LIST в его webhook статуса. Для синхронных отправок, обеспечивайте проверку согласия, отписки и блокировки в вашем приложении.
Укажите хотя бы один из to или recipient. Если вы укажете оба, YCloud использует to и игнорирует recipient.
Шаблоны аутентификации с одним нажатием, без нажатия и с копированием кода требуют телефон номер. Явная отправка OTP через Direct Send также требует номер телефона: используйте to, а не recipient отдельно.

Прямая отправка с явной аутентификацией для OTP

Meta начинает внедрять Authentication Direct Send в альфа-версии. У WABA отправителя должен быть доступ к интерактивному Direct Send для OTP-аутентификации. Успешный запрос Authentication Direct Send на отправку только текста не подтверждает наличие доступа к кнопкам OTP.
Используйте то же тело запроса с POST /v2/whatsapp/messages/sendDirectly для синхронной отправки или POST /v2/whatsapp/messages для отправки в очередь. Установите type в interactive, category в authentication, interactive.type в button и укажите ровно одну кнопку с type: "otp". Установите interactive.action.buttons[0].otp.code в строку из 4–10 ASCII-букв или цифр. Включите тот же код как отдельное значение в interactive.body.text. В iOS 26 и более поздних версиях сообщения с копированием кода и сообщения с одним нажатием могут отображать подсказки клавиатуры для цифровых кодов из 4–8 цифр. На устройстве получателя должны быть включены уведомления WhatsApp и автозаполнение кодов безопасности. Это не требует дополнительной интеграции с приложением iOS; функция zero-tap по-прежнему доступна только на Android. См. сценарии использования OTP в Meta. Скопировать код:
Автозаполнение в одно касание:
Автозаполнение без нажатий:
Для one-tap и zero-tap укажите от 1 до 5 приложений Android с уникальными именами пакетов и 11-символьным хешем ключа подписи для каждого приложения. Замените пример имени пакета и хеша значениями вашего приложения. Имена пакетов могут содержать не более 224 символов и должны включать как минимум два сегмента, разделённых точками; каждый сегмент начинается с буквы и содержит только буквы, цифры или символы подчёркивания. Перед запросом кода настройте процедуру рукопожатия OTP WhatsApp для вашего приложения. Чтобы узнать о настройке и требованиях к устройствам, см. руководство Meta по OTP-сценариям. Установите для zero_tap_terms_accepted значение true в каждом запросе zero-tap, чтобы подтвердить условия Meta для zero-tap от имени вашего бизнеса. Не передавайте это поле для one-tap и копирования кода. Для копирования кода также не передавайте supported_apps и autofill_text. Необязательные поля кнопки text и autofill_text ограничены 25 символами и не должны быть пустыми или содержать переменные, разрывы строк, форматирование, URL-адреса или эмодзи. code_expiration_minutes задает срок действия кода — от 1 до 90 минут (по умолчанию в Meta — 10). Ваше приложение по-прежнему должно проверять код и обеспечивать соблюдение срока его действия. Отдельное поле ttlSeconds управляет временем жизни сообщения при доставке: Authentication Direct Send принимает значения от 30 до 900 секунд, по умолчанию — 600 секунд. См. Ограничения TTL для Direct Send. Проверьте whatsapp.message.updated, чтобы узнать статус доставки, и проверьте автозаполнение на подходящем устройстве. Само по себе доставленное сообщение не подтверждает, что рукопожатие автозаполнения прошло успешно.

Примеры запросов

Добавьте переменные шаблона

Приведите название шаблона, язык и порядок параметров в соответствие с утверждённым шаблоном. Для текста сообщения с параметрами имени клиента и ссылки на заказ отправьте:
См. примеры шаблонных сообщений для получения информации о дополнительных компонентах и типах сообщений.

Ответ на конкретное сообщение

Укажите context.message_id в качестве исходного ID сообщения WhatsApp (wamid), чтобы создать ответ с цитатой. Продолжайте проверять, что окно обслуживания клиентов открыто.

Применение фильтров отписки и блокировки

Для POST /whatsapp/messages задайте filterUnsubscribed: true и filterBlocked: true, если вам нужно применить списки подавления YCloud. Оба по умолчанию имеют значение false и не применяются к sendDirectly. Проверяйте whatsappMessage.errorCode в Webhook статусов на наличие RECIPIENT_UNSUBSCRIBED или RECIPIENT_IN_BLOCK_LIST. Не ожидайте отдельного статуса filtered. Обеспечьте подавление в вашем приложении перед использованием sendDirectly. Используйте externalId, чтобы связать сообщения с заказом или другой внутренней записью. Это поле корреляции, а не серверный ключ идемпотентности.

Ответ

Успешный ответ возвращает объект сообщения YCloud. Исходное значение status: accepted означает, что YCloud принял запрос на отправку. Это не означает, что сообщение было отправлено Meta или доставлено пользователю WhatsApp.

Пример ответа

Поля ответа

Статус доставки

Подпишитесь на whatsapp.message.updated Webhooks, чтобы получать последующие изменения статуса, такие как sent, failed, delivered или read. Используйте GET /whatsapp/messages/{id}, когда вам нужно получить сообщение напрямую.
Для сообщений с медиафайлами сначала загрузите файл с помощью POST /whatsapp/media/{phoneNumber}/upload, а затем используйте возвращённый ID медиафайла в полезной нагрузке сообщения.

Ограничения и устранение неполадок

  • Для обычной отправки шаблонов требуется шаблон APPROVED; шаблоны ARCHIVED. нельзя отправить как обычные шаблоны сообщений.
  • Не повторяйте принятый запрос без стратегии идемпотентности. Повторный запрос может отправить дублирующее сообщение.
  • Используйте YCloud id, wamid, externalId и статус Webhook, когда анализ доставки.
  • Проверьте whatsappApiError, когда прямой запрос достигает Meta и Meta отклоняет его это.
Сведения об ограничениях пропускной способности см. в разделе Ограничения скорости.

Рекомендации по прямой отправке

Отправляйте служебный контент, конвертируйте шаблоны и отслеживайте события категорий и ограничений.

Рекомендации для рабочей среды

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

Используйте идентификаторы пользователей в рамках бизнеса

Отправка сообщений и звонков по BSUID, запрос телефонных номеров и управление контактом Meta записи в книге и обрабатывать поля BSUID в webhook.

Полные примеры интеграции

Полный процесс создания шаблонов и привязки переменных описан в разделах Примеры создания шаблонов и Примеры обмена сообщениями. Используйте Обработка ошибок WhatsApp, чтобы отличить отклонение запроса от последующих ошибок доставки, а Реализация приёмника Webhook — чтобы проверять подписи и надёжно принимать обновления статуса.