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

Что такое Direct Send

Прямая отправка позволяет отправлять инициированные бизнесом сообщения Utility и Authentication без предварительного создания шаблонов. Отправьте полное содержимое и category через YCloud WhatsApp Messages API; Meta сопоставит или создаст шаблон. Используйте служебную категорию для сообщений, связанных с действием или запросом клиента, например для обновлений по заказу и напоминаний о встречах. Для подтверждения личности с помощью одноразовых паролей (OTP) используйте категорию аутентификации. Маркетинговые сообщения используют обычные шаблоны. Прежде чем начать Для существующих интеграций см. изменения и совместимость.

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

Укажите в YCLOUD_API_KEY свой ключ API и замените заполнители номеров телефонов на номера в формате E.164. В примере ниже используется синхронная отправка; вы также можете отправлять асинхронно.

Примеры служебных сообщений

Каждая вкладка содержит полный запрос cURL. Перед отправкой замените ключ API, номера телефонов и примеры URL.
Синхронные и асинхронные API Оба эндпоинта принимают одно и то же тело запроса Direct Send. Аутентифицируйтесь с помощью заголовка X-API-Key и задайте Content-Type: application/json. Эндпоинт sendDirectly управляет моментом отправки; сам по себе он не включает Direct Send. Отслеживайте результат доставки через статус сообщения и обратные вызовы. Параметры запроса Если пропустить и category, и useDirectSend, будет отправлено обычное сообщение в свободной форме, для которого требуется открытое 24-часовое окно обслуживания клиентов.

Примеры OTP-аутентификации

Выберите один из трёх сценариев работы с OTP, приведённых ниже. Каждый пример — это полное тело запроса YCloud для любого из эндпоинтов в синхронных и асинхронных API. Ваш WABA должен иметь доступ к функции Authentication Direct Send OTP. Используйте номер телефона в to; Аутентификация не поддерживает получателя с идентификатором пользователя в рамках бизнеса (BSUID). Замените 123456 как в otp.code, так и в interactive.body.text. Используйте 4–10 ASCII-букв или цифр и добавьте код в тело отдельным значением.
Используйте copy_code для кнопки копирования кода. Не указывайте supported_apps, autofill_text и zero_tap_terms_accepted.
Для сценариев в одно касание и без касания supported_apps принимает от 1 до 5 Android-приложений с уникальными именами пакетов. Каждый signature_hash должен содержать ровно 11 символов. Имя пакета и хэш, приведённые выше, — это примеры; они не активируют автозаполнение для вашего приложения. См. настройку приложения и полные правила параметров. code_expiration_minutes описывает срок действия кода в минутах; ваше приложение должно проверять код и обеспечивать соблюдение срока его действия. ttlSeconds определяет, как долго WhatsApp пытается доставить сообщение. Прямая отправка аутентификационных сообщений принимает значения от 30–900 секунд, по умолчанию — 600 секунд. В iOS 26 и более поздних версиях сообщения с копированием кода и сообщения с одним нажатием могут отображать подсказки на клавиатуре для 4–8-значных цифровых кодов, если включены уведомления WhatsApp и автозаполнение кодов безопасности. Zero-tap доступен только на Android. См. сценарии OTP в Meta. Прямая отправка текстовых сообщений категории Authentication по-прежнему поддерживается. Доставленное сообщение подтверждает доставку, но не успешное завершение рукопожатия автозаполнения Android.

Время жизни доставки (TTL)

Установите ttlSeconds, чтобы прекратить попытки доставки, когда сообщение перестанет быть полезным. Например, ttlSeconds: 1800 задаёт утилитарному обновлению срок доставки 30 минут. Для аутентификации максимальный срок — 15 минут. TTL не удаляет доставленные сообщения и не заменяет проверки истечения срока действия OTP в вашем приложении. Справочник Meta по TTL.

Пользовательские названия шаблонов

При необходимости задайте templateName, чтобы указать имя утилитарного шаблона Direct Send. Чтобы включить Direct Send, также задайте category: "utility" или useDirectSend: true.
YCloud проверяет templateName перед принятием запроса на отправку. Если имя недействительно или уже используется обычным шаблоном, измените его и повторите попытку. Используйте от 1 до 512 строчных букв, цифр или символов подчёркивания. YCloud отклоняет заглавные буквы, пробелы и другие символы. Один и тот же WABA не может использовать имя, принадлежащее существующему обычному шаблону сообщения WhatsApp, включая отклонённый шаблон. Удалённые шаблоны не резервируют это имя, и вы можете повторно использовать имя, которое Meta ранее сгенерировала для Direct Send. Если обычный шаблон уже использует это имя, API возвращает HTTP 400 с target templateName и message A template with the same name already exists. Отслеживайте статус сообщения даже после того, как YCloud примет запрос. О конфликтах имён и ошибках создания шаблонов см. типичные ошибки. Правила повторных попыток Meta описаны в её справочнике по шаблонам с именем бизнеса. templateName не поддерживается для Authentication Direct Send. YCloud игнорирует его в сообщениях, которые не используют Direct Send.

Статус сообщения и обратные вызовы

Статус доставки YCloud сообщает о доставке через whatsapp.message.updated. Сохраните возвращённый YCloud id и идентификатор сообщения WhatsApp (wamid), чтобы сопоставлять обновления. accepted означает, что YCloud принял запрос; sent означает, что сообщение находится в процессе передачи в WhatsApp. Используйте delivered, read или failed, чтобы отслеживать последующий результат. Вы также можете запросить GET /v2/whatsapp/messages/{id} с помощью YCloud id. Укажите в externalId собственный идентификатор, когда вам нужно сопоставить сообщение с вашей системой. Это не предотвращает дублирование отправок. Если запрос завершается по тайм-ауту, проверьте исходное сообщение перед повторной попыткой. Настройте статусные Webhook. Обратные вызовы кнопки ответа Когда клиент нажимает кнопку ответа Direct Send, входящее сообщение содержит type: button. Считывайте выбор клиента из button.payload и button.text. Соответствующие поля в событии входящего сообщения YCloud:
Используйте button.payload, чтобы определить действие, и context.id, чтобы сопоставить ответ с wamid исходного сообщения. Не считывайте этот ответ из interactive.button_reply — это обычный формат кнопки ответа в свободной форме.

Расширения YCloud

YCloud предоставляет просмотр шаблонов и аналитику в консоли, а также расширение API, которое преобразует существующие шаблоны Utility в сообщения Direct Send. Meta выполняет сопоставление и генерацию шаблонов.

Просмотр созданных шаблонов

Созданные шаблоны появляются в YCloud после синхронизации, которая может завершиться уже после отправки сообщения. Чтобы найти их:
  1. Откройте WhatsApp Manager → Шаблоны в консоли YCloud.
  2. Выберите WABA, которая использовалась для отправки сообщения.
  3. Задайте Создатель → Создано автоматически. Используйте Категория → Utility , чтобы сузить список до шаблонов Utility.
  4. Проверьте название шаблона, категорию, язык, статус и время последнего обновления. Нажмите на его название или на Аналитика , чтобы открыть предпросмотр и подробные сведения об эффективности.
В разделе Шаблоны для фильтра по создателю выбрано значение Создано автоматически.

Set Creator to Auto generated. This test WABA has no matching generated templates.

Автоматически назначенные имена начинаются с auto_generated; пользовательские имена совпадают с указанным вами именем. Используйте Создатель → Создано автоматически , чтобы найти оба типа. См. справочник Meta по созданным шаблонам. На странице аналитики отображаются предварительный просмотр сообщения и доступная статистика доставки, сбоев, прочтений и взаимодействий за выбранный период. При анализе предупреждения или приостановленного шаблона учитывайте статус и содержимое шаблона вместе. Сгенерированные шаблоны нельзя редактировать или удалять вручную. Чтобы изменить служебное сообщение, обновите содержимое в запросе на отправку. Затем Meta подбирает или создаёт шаблон для этого содержимого. Meta удаляет созданные автоматически шаблоны, которые ни разу не использовались, спустя 24 часа. Ранее использовавшиеся шаблоны могут быть архивированы после периода неактивности.

Преобразование шаблонов в Direct Send

Это расширение YCloud для существующих шаблонов Utility. Укажите useDirectSend: true; YCloud заполнит параметры шаблона и отправит содержимое через Direct Send. template.name выбирает существующий шаблон для преобразования. Используйте templateName, чтобы указать имя шаблона, который Meta сопоставляет или создает для Utility Direct Send. Используйте шаблон Utility из вашего WABA. Задайте type: "template" и useDirectSend: true, а также укажите его название, язык и все обязательные параметры. Шаблон должен соответствовать приведённым ниже ограничениям преобразования; ему не требуется статус APPROVED. Шаблоны аутентификации нельзя преобразовать. Чтобы отправить OTP через Direct Send, используйте запрос Authentication. В этом примере используйте существующий шаблон категории Utility с именем order_update и текстом Your order {{1}} has been updated., без заголовка, нижнего колонтитула и кнопок. Отправьте его асинхронно с помощью следующего запроса:
Пример ответа после того, как YCloud принимает сообщение в очередь. Содержимое уже преобразовано в type: "text":
accepted не означает, что сообщение было доставлено. Сохраните возвращённый id и отслеживайте whatsapp.message.updated или запросите GET /v2/whatsapp/messages/{id}. Если YCloud возвращает WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT, проверьте заголовок шаблона, кнопки и неразрешённые переменные на соответствие приведённым ниже ограничениям. Если WABA не может использовать прямую отправку, проверьте её право на использование перед повторной попыткой или отправьте одобренный шаблон категории Utility через обычный процесс работы с шаблонами. Время жизни сообщения При преобразовании шаблона определите срок доставки в следующем порядке:
  1. Значение запроса: Если вы укажете ttlSeconds, оно имеет приоритет и должно находиться в диапазоне от 30 до 43 200 секунд.
  2. Значение шаблона: В противном случае используйте TTL шаблона, если он составляет от 30 до 43 200 секунд. Положительный TTL шаблона меньше 30 секунд не проходит проверку; укажите допустимое значение ttlSeconds, чтобы переопределить его.
  3. Значение по умолчанию: Если TTL шаблона не задан, неположителен или превышает 43 200 секунд, используйте TTL Meta по умолчанию.
Ограничения конвертации Следующие ограничения применяются к преобразованию существующего шаблона Utility в содержимое Direct Send, выполняемому YCloud: Не объединяйте кнопки CTA URL и быстрого ответа. Другие типы заголовков и кнопок преобразовать нельзя. Для неподдерживаемых компонентов или неразрешенных переменных шаблона возвращается HTTP 400 с кодом WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT. Перед преобразованием шаблона с заголовком-изображением убедитесь, что ваш WABA может использовать медиа-заголовки. См. поддерживаемые функции и ограничения и требования Meta к медиа-заголовкам. Проверки примера сообщения (необязательно) POST /v2/whatsapp/messages/{wabaId}/messageSamples отправляет один пример в Meta и возвращает распознанную категорию, не отправляя сообщение клиенту. Этот эндпоинт YCloud необязателен. Проверяйте репрезентативный контент при внедрении нового сценария использования; результат проверки примера не освобождает последующие сообщения от проверок категории и качества Meta. Замените WABA_ID на ваш WABA ID и укажите YCLOUD_API_KEY в качестве ключа API. Используйте вымышленные данные клиента в примере:
Пример ответа:
Проверьте category перед использованием содержимого в запросе Utility Direct Send. Если Meta обнаружит MARKETING или AUTHENTICATION, измените содержимое или используйте соответствующий рабочий процесс обмена сообщениями. Для примера кнопки укажите поля type и interactive из приведенного выше примера кнопки Utility; не указывайте поля получателя и отправки.

Поддерживаемые функции и ограничения

Доступ к WABA Проверьте доступность в Meta WhatsApp Manager → Шаблоны сообщений. Бизнес-портфелям с лимитом обмена сообщениями 100 000 или без лимита обычно доступна прямая отправка сообщений категории Utility. Прямая отправка сообщений категории Authentication находится на стадии альфа-тестирования. См. требования Meta к соответствию критериям. Форматы сообщений, языки и тарифы Следующие ограничения применяются к форматам сообщений, используемым в примерах этого руководства. Чтобы узнать требования платформы, см. поддерживаемые типы сообщений Meta. Поддерживаются все языки шаблонов WhatsApp. Применяются стандартные ограничения на обмен сообщениями и пропускная способность. Тарификация выполняется по соответствующей категории Utility или Authentication.

Рекомендации по добросовестности и содержанию

Утилитарный контент должен быть нерекламным и связанным с действием клиента, его запросом или важной информацией, соответствующей критериям. Укажите соответствующий заказ, запись на приём, аккаунт или транзакцию, чтобы клиент понимал, почему вы с ним связываетесь. Следуйте рекомендациям Meta по категориям шаблонов. Не добавляйте рекламные акции, скидки или предложения по кросс-продажам в обновление Utility. Используйте Authentication для OTP, а шаблоны Marketing — для рекламного контента. Настройка category: "utility" не отменяет оценку контента Meta. Для нового сценария использования вы можете запустить проверку образца сообщения перед отправкой. Если Meta пометит содержимое, изучите уведомление о категории и обратитесь к разделу статус аккаунта и устранение неполадок, включая процесс проверки, если вы не согласны с решением.

Статус аккаунта и устранение неполадок

Предупреждения, ограничения и проверки Шаблон может быть приостановлен из-за низкого качества. Сообщения, которые совпадают с ним или очень на него похожи, после этого могут завершаться ошибкой Meta 132015. Найдите затронутый шаблон в YCloud, проверьте его содержимое и статус и устраните причину, прежде чем возобновить отправку сообщений, использующих его. Повторяющееся неправильное использование категории может ограничить Direct Send для всего WABA: Ориентируйтесь на уведомление аккаунта о действующем ограничении и сроке его действия. Успешная проверка одного шаблона не снимает автоматически ограничение на уровне аккаунта. Запросить проверку категории Если вы считаете, что контент был ошибочно отмечен, откройте Meta Business Support Home → аккаунт WhatsApp → обновления шаблонов Direct Send → Доступно для проверки. Выберите затронутые шаблоны и нажмите Запросить проверку. Отправьте запрос в течение 60 дней с момента уведомления. Каждый помеченный шаблон можно рассмотреть один раз. Отслеживайте результат в статусе На рассмотрении, Отменено или Без изменений. Если опция рассмотрения недоступна, обратитесь в YCloud, указав WABA ID, имя или ID шаблона, язык и сведения об уведомлении. Уведомления о статусе Подпишитесь на whatsapp.template.correct_category_detection через свой эндпоинт Webhook. Сравните whatsappTemplate.previousCategory с whatsappTemplate.category; если они равны UTILITY и MARKETING соответственно, проверьте сообщение на наличие контента Marketing. См. пример Webhook для определения категории. Эти уведомления относятся к категориям шаблонов и не срабатывают для каждого сообщения. Результаты проверки образцов поступают из ответа messageSamples; результаты доставки приходят через whatsapp.message.updated. Поля, относящиеся к событию ограничения аккаунта YCloud:
Используйте WABA ID, чтобы приостановить затронутый рабочий процесс. Прочитайте violationType, чтобы узнать причину, и restrictions[].expiration, чтобы узнать срок действия, если он указан. См. описание типов нарушений, характерных для Direct Send, а также полезных нагрузок предупреждений, ограничений и восстановления в документации Meta: Webhook для ограничения аккаунта. Типичные ошибки При синхронных ошибках проверяйте error.whatsappApiError, если он присутствует. Для сообщений в очереди проверяйте сведения о сбое в whatsapp.message.updated.

Изменения и совместимость

Вы можете продолжать использовать тот же синхронный или асинхронный эндпоинт YCloud и аутентификацию X-API-Key. По-прежнему поддерживаются существующие запросы на отправку текстовых сообщений и сообщений с кнопками категории Utility, а также текстовых сообщений категории Authentication. В таблице приведено сравнение текущего использования с вариантами, доступными сейчас.
Для новых возможностей по-прежнему требуется соответствующий доступ к WABA. Прямая отправка для аутентификации по-прежнему находится в альфа-версии. Доступность на платформах и форматы определяются требованиями Meta к допустимости и поддерживаемыми функциями.

Прямая отправка: часто задаваемые вопросы

Нет. Отправьте полное содержимое с помощью category: "utility" или category: "authentication", и Meta сопоставит или создаст шаблон. Для служебных сообщений вы можете дополнительно задать templateName, чтобы указать имя шаблона Direct Send.Чтобы преобразовать существующий утилитарный шаблон, укажите template.name и useDirectSend: true. Эти поля выполняют иную функцию, чем templateName. Шаблоны аутентификации нельзя преобразовать в Direct Send.
Meta использует шаблоны для проверок категории и качества, отчетности по эффективности и устранения неполадок. Direct Send выполняет подбор и генерацию шаблонов за вас, поэтому вам не нужно вручную создавать шаблон перед отправкой. См. как работает Direct Send.
Да. Прямая отправка поддерживает инициированные бизнесом утилитарные сообщения и сообщения аутентификации вне окна обслуживания клиентов, при условии, что ваш WABA имеет доступ к выбранной категории, а сообщение соответствует требованиям Meta к согласию и содержанию. Обычные сообщения в свободной форме по-прежнему требуют открытого окна обслуживания клиентов. См. условия допуска и область отправки.
В стандартной прямой отправке можно использовать шаблон онбординга, пока Meta асинхронно создает соответствующий шаблон. Синхронизация с YCloud может завершиться после отправки сообщения. Выберите правильный WABA и используйте Создатель → Создано автоматически , чтобы найти созданный шаблон.При создании шаблонов Meta скрывает персональные данные и определяет язык.Утилитарные шаблоны с именем бизнеса не используют этот резервный вариант шаблона онбординга.
Meta удаляет сгенерированные шаблоны, которые ни разу не использовались для отправки, через 24 часа после создания. Ранее использовавшиеся шаблоны периодически архивируются после периода неактивности. Этой очисткой управляет Meta; шаблоны Direct Send нельзя редактировать или удалять вручную. См. часто задаваемые вопросы Meta о Direct Send.
Нет. Meta оценивает фактическое содержание сообщения. Не добавляйте рекламный контент в служебные сообщения. Если вы считаете, что решение о категории неверно, воспользуйтесь процессом проверки. Успешная отправка не освобождает будущие сообщения от проверок категории и качества.
Сообщения прямой отправки подчиняются применимым правилам тарификации категорий Utility и Authentication. Автоматическое создание шаблонов не делает сообщение бесплатным. Актуальные тарифы и применимые условия см. в разделе Тарифы WhatsApp.