Что такое Direct Send
Прямая отправка позволяет отправлять инициированные бизнесом сообщения Utility и Authentication без предварительного создания шаблонов. Отправьте полное содержимое иcategory через YCloud WhatsApp Messages API; Meta сопоставит или создаст шаблон.
Используйте служебную категорию для сообщений, связанных с действием или запросом клиента, например для обновлений по заказу и напоминаний о встречах. Для подтверждения личности с помощью одноразовых паролей (OTP) используйте категорию аутентификации. Маркетинговые сообщения используют обычные шаблоны.
Прежде чем начать
- Получите ключ API YCloud и подключите бизнес-номер WhatsApp.
- Убедитесь, что ваш аккаунт WhatsApp Business (WABA) имеет доступ к Direct Send для выбранной категории. См. требования к допуску.
- Получите согласие клиента и следуйте рекомендациям Meta по категориям.
Отправка сообщений
Укажите вYCLOUD_API_KEY свой ключ API и замените заполнители номеров телефонов на номера в формате E.164. В примере ниже используется синхронная отправка; вы также можете отправлять асинхронно.
Примеры служебных сообщений
Каждая вкладка содержит полный запрос cURL. Перед отправкой замените ключ API, номера телефонов и примеры URL.- Текст
- Кнопки ответа
- Кнопка URL
- Медиа-заголовок
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-букв или цифр и добавьте код в тело отдельным значением.
- Копировать_код
- в одно_касание
- zero_tap
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.
Запрос с пользовательским именем шаблона
Запрос с пользовательским именем шаблона
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:
Пример Webhook для кнопки ответа
Пример Webhook для кнопки ответа
button.payload, чтобы определить действие, и context.id, чтобы сопоставить ответ с wamid исходного сообщения. Не считывайте этот ответ из interactive.button_reply — это обычный формат кнопки ответа в свободной форме.
Расширения YCloud
YCloud предоставляет просмотр шаблонов и аналитику в консоли, а также расширение API, которое преобразует существующие шаблоны Utility в сообщения Direct Send. Meta выполняет сопоставление и генерацию шаблонов.Просмотр созданных шаблонов
Созданные шаблоны появляются в YCloud после синхронизации, которая может завершиться уже после отправки сообщения. Чтобы найти их:- Откройте WhatsApp Manager → Шаблоны в консоли YCloud.
- Выберите WABA, которая использовалась для отправки сообщения.
- Задайте Создатель → Создано автоматически. Используйте Категория → Utility , чтобы сузить список до шаблонов Utility.
- Проверьте название шаблона, категорию, язык, статус и время последнего обновления. Нажмите на его название или на Аналитика , чтобы открыть предпросмотр и подробные сведения об эффективности.

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., без заголовка, нижнего колонтитула и кнопок.
Отправьте его асинхронно с помощью следующего запроса:
type: "text":
accepted не означает, что сообщение было доставлено. Сохраните возвращённый id и отслеживайте whatsapp.message.updated или запросите GET /v2/whatsapp/messages/{id}.
Если YCloud возвращает WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT, проверьте заголовок шаблона, кнопки и неразрешённые переменные на соответствие приведённым ниже ограничениям. Если WABA не может использовать прямую отправку, проверьте её право на использование перед повторной попыткой или отправьте одобренный шаблон категории Utility через обычный процесс работы с шаблонами.
Время жизни сообщения
При преобразовании шаблона определите срок доставки в следующем порядке:
- Значение запроса: Если вы укажете
ttlSeconds, оно имеет приоритет и должно находиться в диапазоне от 30 до 43 200 секунд. - Значение шаблона: В противном случае используйте TTL шаблона, если он составляет от 30 до 43 200 секунд. Положительный TTL шаблона меньше 30 секунд не проходит проверку; укажите допустимое значение
ttlSeconds, чтобы переопределить его. - Значение по умолчанию: Если TTL шаблона не задан, неположителен или превышает 43 200 секунд, используйте TTL Meta по умолчанию.
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.Рекомендации по добросовестности и содержанию
Утилитарный контент должен быть нерекламным и связанным с действием клиента, его запросом или важной информацией, соответствующей критериям. Укажите соответствующий заказ, запись на приём, аккаунт или транзакцию, чтобы клиент понимал, почему вы с ним связываетесь. Следуйте рекомендациям Meta по категориям шаблонов.category: "utility" не отменяет оценку контента Meta.
Для нового сценария использования вы можете запустить проверку образца сообщения перед отправкой. Если Meta пометит содержимое, изучите уведомление о категории и обратитесь к разделу статус аккаунта и устранение неполадок, включая процесс проверки, если вы не согласны с решением.
Статус аккаунта и устранение неполадок
Предупреждения, ограничения и проверки Шаблон может быть приостановлен из-за низкого качества. Сообщения, которые совпадают с ним или очень на него похожи, после этого могут завершаться ошибкой Meta132015. Найдите затронутый шаблон в YCloud, проверьте его содержимое и статус и устраните причину, прежде чем возобновить отправку сообщений, использующих его.
Повторяющееся неправильное использование категории может ограничить Direct Send для всего WABA:
whatsapp.template.correct_category_detection через свой эндпоинт Webhook. Сравните whatsappTemplate.previousCategory с whatsappTemplate.category; если они равны UTILITY и MARKETING соответственно, проверьте сообщение на наличие контента Marketing. См. пример Webhook для определения категории.
Эти уведомления относятся к категориям шаблонов и не срабатывают для каждого сообщения. Результаты проверки образцов поступают из ответа messageSamples; результаты доставки приходят через whatsapp.message.updated.
Поля, относящиеся к событию ограничения аккаунта YCloud:
Пример Webhook об ограничении аккаунта
Пример Webhook об ограничении аккаунта
violationType, чтобы узнать причину, и restrictions[].expiration, чтобы узнать срок действия, если он указан.
См. описание типов нарушений, характерных для Direct Send, а также полезных нагрузок предупреждений, ограничений и восстановления в документации Meta: Webhook для ограничения аккаунта.
Типичные ошибки
При синхронных ошибках проверяйте error.whatsappApiError, если он присутствует. Для сообщений в очереди проверяйте сведения о сбое в whatsapp.message.updated.
Изменения и совместимость
Вы можете продолжать использовать тот же синхронный или асинхронный эндпоинт YCloud и аутентификациюX-API-Key. По-прежнему поддерживаются существующие запросы на отправку текстовых сообщений и сообщений с кнопками категории Utility, а также текстовых сообщений категории Authentication. В таблице приведено сравнение текущего использования с вариантами, доступными сейчас.
Прямая отправка: часто задаваемые вопросы
Нужно ли указывать имя шаблона перед отправкой?
Нужно ли указывать имя шаблона перед отправкой?
category: "utility" или category: "authentication", и Meta сопоставит или создаст шаблон. Для служебных сообщений вы можете дополнительно задать templateName, чтобы указать имя шаблона Direct Send.Чтобы преобразовать существующий утилитарный шаблон, укажите template.name и useDirectSend: true. Эти поля выполняют иную функцию, чем templateName. Шаблоны аутентификации нельзя преобразовать в Direct Send.Почему Direct Send по-прежнему создаёт шаблоны?
Почему Direct Send по-прежнему создаёт шаблоны?
Можно ли отправлять сообщения за пределами 24-часового окна обслуживания клиентов?
Можно ли отправлять сообщения за пределами 24-часового окна обслуживания клиентов?
Почему сообщение может успешно отправиться до того, как появится его сгенерированный шаблон?
Почему сообщение может успешно отправиться до того, как появится его сгенерированный шаблон?
Как выполняется очистка неиспользуемых созданных шаблонов?
Как выполняется очистка неиспользуемых созданных шаблонов?
Гарантирует ли назначение категории utility, что Meta примет эту категорию?
Гарантирует ли назначение категории utility, что Meta примет эту категорию?
Как тарифицируется прямая отправка?
Как тарифицируется прямая отправка?

