Что это такое
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.
Общие поля запроса
Укажите хотя бы один из
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.
Скопировать код:
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}, когда вам нужно получить сообщение напрямую.
Ограничения и устранение неполадок
- Для обычной отправки шаблонов требуется шаблон
APPROVED; шаблоныARCHIVED. нельзя отправить как обычные шаблоны сообщений. - Не повторяйте принятый запрос без стратегии идемпотентности. Повторный запрос может отправить дублирующее сообщение.
- Используйте YCloud
id,wamid,externalIdи статус Webhook, когда анализ доставки. - Проверьте
whatsappApiError, когда прямой запрос достигает Meta и Meta отклоняет его это.
Рекомендации по прямой отправке
Отправляйте служебный контент, конвертируйте шаблоны и отслеживайте события категорий и ограничений.
Рекомендации для рабочей среды
Спроектируйте синхронизацию статусов, ограниченные повторные попытки, проверки согласия, повторное использование медиафайлов,
а также средства контроля пропускной способности для продакшен-интеграции.
Используйте идентификаторы пользователей в рамках бизнеса
Отправка сообщений и звонков по BSUID, запрос телефонных номеров и управление контактом Meta
записи в книге и обрабатывать поля BSUID в webhook.

