Skip to main content
Direct Send позволяет компаниям, соответствующим требованиям, отправлять служебные сообщения (Utility), передавая готовый контент или повторно используя существующий шаблон Utility. Meta выполняет сопоставление и генерацию шаблонов для пользовательского контента. В этом руководстве рассматривается отправка служебных сообщений через Direct Send в YCloud. Сведения об отправке сообщений в целом см. в разделе Отправка сообщения WhatsApp.

Как работает Direct Send

Direct Send использует шаблоны в фоновом режиме. Вы можете отправить готовый текст или интерактивный контент. Вы также можете указать существующий шаблон Utility и настроить YCloud на конвертацию его поддерживаемых компонентов в сообщение Direct Send. Meta сопоставляет контент вашего сообщения с существующим шаблоном. Если совпадений нет, Meta удаляет персональные данные, определяет язык и создает новый шаблон в фоновом режиме для сопоставления будущих сообщений. Например, сообщения «Ваш заказ A123456 отправлен» и «Ваш заказ B789012 отправлен» имеют одинаковую структуру. Для последующих уведомлений может повторно использоваться подходящий созданный шаблон. Созданные шаблоны сохраняют информацию о категории, качестве и эффективности. Это позволяет определять, какой контент работает хорошо, а какой вызывает проблемы с доставкой, даже если вы не создавали шаблон вручную.

Поддерживаемые возможности и ограничения

Требования и область применения

Подключите свой WABA и рабочий номер телефона к YCloud. В разделе Meta WhatsApp Manager → Шаблоны сообщений проверьте, доступна ли функция Direct Send для вашей компании. Если доступ для вашего WABA отсутствует, используйте одобренный шаблон Utility или свяжитесь с YCloud для проверки соответствия требованиям. Служебный Direct Send позволяет инициировать ожидаемое уведомление за пределами 24-часового окна обслуживания клиентов. Получите согласие клиента и убедитесь, что контент связан с его запросом, транзакцией, учетной записью или важной необходимой информацией. Рекламные акции и коды подтверждения не входят в рамки Utility.

Длина сообщений и кнопки

В приведенных ниже примерах отправки используются текстовые заголовки. В текстовых сообщениях предпросмотр URL не отображается. Ограничения аккаунта и контроль пропускной способности по-прежнему действуют. Используйте текстовые заголовки для пользовательских запросов Direct Send interactive. Заголовок с изображением доступен только при конвертации поддерживаемого шаблона и при условии, что Meta включила эту возможность для вашего WABA.

Срок жизни доставки (TTL)

ttlSeconds определяет, как долго сообщение может оставаться доступным для доставки. Если доставить его в течение этого периода не удается, оно отклоняется. Уже доставленное сообщение не удаляется после истечения срока TTL. Значение по умолчанию и допустимый пользовательский диапазон различаются. Для обновления статуса доставки, актуального только в течение 30 минут, задайте ttlSeconds: 1800; не оставляйте значение по умолчанию.

Поддерживаемые типы сообщений

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

Обработка ответов по кнопкам быстрого ответа

Хотя вы отправляете запрос interactive, Direct Send доставляет контент как шаблон. Поэтому нажатие клиентом кнопки быстрого ответа использует формат быстрого ответа шаблона: type: button, с button.payload и button.text. Соответствующие поля в событии входящего сообщения YCloud:
Используйте button.payload для идентификации действия и context.id для сопоставления ответа с wamid исходного сообщения. Не считывайте этот ответ из interactive.button_reply, который является стандартным форматом кнопок свободного ответа.

Отправка через YCloud

Подготовьте серверный API-ключ, а также номера отправителя и получателя в формате E.164. Идентификатор WABA ID требуется только в том случае, если вы решите отправлять образцы сообщений.

1. Выберите режим отправки

Название эндпоинта sendDirectly отражает тайминг отправки. Чтобы использовать Direct Send, у вашего WABA должен быть доступ, а запрос должен содержать поля Direct Send, указанные ниже.

2. Сформируйте запрос

В этих примерах полный контент отправляется синхронно. Вы также можете использовать отправку через очередь или конвертировать существующий шаблон Utility. Замените заполнители номеров телефонов и пример URL перед отправкой.

3. Отслеживайте доставку

Сохраняйте возвращенный id сообщения, ваш externalId и wamid, когда он доступен. Получайте обновления через whatsapp.message.updated или запрашивайте GET /v2/whatsapp/messages/{id}. После accepted результатом отправки будет sent или failed. Успешные сообщения могут переходить в статус delivered и read. Принятый запрос не является подтверждением доставки. При ошибках синхронной отправки проверьте error.whatsappApiError, если оно присутствует. Для сообщений из очереди проверяйте последующие обновления статуса. Если время ожидания запроса истекло, выполните сверку исходного сообщения перед повторной попыткой.

Конвертация существующего шаблона Utility

Используйте существующий шаблон Utility в вашем WABA. Укажите type: "template" и useDirectSend: true. Передайте имя шаблона, язык и каждый обязательный параметр. YCloud подставляет переменные и преобразует поддерживаемые компоненты в текст или интерактивный контент с помощью category: "utility". Шаблон должен соответствовать приведенным ниже ограничениям конвертации. YCloud не требует статуса APPROVED для этой конвертации. Если у шаблона есть заголовок с изображением, убедитесь, что Meta активировала Direct Send с заголовками-изображениями для вашего WABA, прежде чем использовать его. Для этого требуется отдельный доступ от Meta. В этом примере используйте существующий шаблон категории utility с именем order_update, с текстом тела Your order {{1}} has been updated. и без заголовка, нижнего колонтитула или кнопок:
Ответ содержит сконвертированный контент. В этом примере type становится text, а переменная шаблона заменяется переданным ID заказа:
Ответ со статусом accepted не подтверждает доставку. Сохраняйте id сообщения и отслеживайте события whatsapp.message.updated. Ознакомьтесь с ограничениями конвертации ниже, прежде чем повторно использовать шаблон с заголовками или кнопками. Если YCloud возвращает WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT, проверьте заголовок шаблона, кнопки и неразрешенные переменные на соответствие ограничениям ниже. Если WABA не может использовать Direct Send, проверьте ее соответствие требованиям перед повторной попыткой или отправьте одобренный Utility template через обычный рабочий процесс шаблонов.

Установка времени жизни сообщения

Для конвертации шаблона значение ttlSeconds из запроса имеет приоритет перед TTL шаблона. Если вы опустите его, YCloud наследует положительный TTL шаблона вплоть до 43200 секунд. TTL шаблона менее 30 секунд не проходит валидацию, поэтому переопределите его допустимым значением в запросе. YCloud не наследует значения TTL шаблона более 43200. Если ни одно из значений не задано, Meta использует свой TTL по умолчанию.

Именование Utility-шаблона Direct Send

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

Ограничения на конвертацию шаблонов и языки

Utility Direct Send поддерживает текст, кнопки-ссылки CTA URL и кнопки быстрого ответа. Эти ограничения также действуют, когда YCloud конвертирует сервисный шаблон (utility template): Не комбинируйте кнопки CTA URL и кнопки быстрого ответа. Другие типы заголовков и кнопок не могут быть конвертированы. Неподдерживаемые компоненты или неразрешенные переменные шаблона возвращают HTTP 400 с кодом WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT.

Поддержка языков

Direct Send поддерживает языки шаблонов WhatsApp, за исключением: Используйте поддерживаемый язык для рабочих процессов Direct Send.

Просмотр шаблонов, созданных с помощью Direct Send в YCloud

  1. Перейдите в WhatsApp Manager → Templates в консоли YCloud.
  2. Выберите WABA, которая использовалась для отправки сообщения.
  3. Установите фильтр Creator → Auto generated. Используйте Category → Utility , чтобы отфильтровать список по сервисным шаблонам (Utility).
  4. Проверьте имя шаблона, категорию, язык, статус и время последнего обновления. Нажмите на его имя или Insights , чтобы открыть предпросмотр и аналитику эффективности.
Фильтр Creator со значением Auto generated в разделе Templates

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

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

Правила в отношении контента и целостности

Делайте служебный контент (Utility) конкретным и нерекламным

Служебные сообщения (Utility) должны следовать за ожидаемым действием клиента или предоставлять необходимую важную информацию. Четко указывайте соответствующий заказ, запись на прием, аккаунт или транзакцию. Замена category на utility не меняет смысла сообщения. Meta продолжает оценивать сгенерированные шаблоны и после отправки. Существенно отличающийся сценарий использования можно проверить с помощью образца сообщения перед отправкой.

Проверка нового сценария использования с помощью образцов сообщений (необязательно)

POST /v2/whatsapp/messages/{wabaId}/messageSamples отправляет один пример в Meta и возвращает категорию, определенную Meta. Сообщение клиенту при этом не отправляется. Эта проверка необязательна; ее не требуется вызывать для каждого сообщения или перед использованием Direct Send. Для нового сценария Utility рекомендуется проверить три-четыре репрезентативных образца, по одному на запрос. Замените WABA_ID на идентификатор вашего WhatsApp Business Account и задайте YCLOUD_API_KEY в вашем окружении. В образце используйте вымышленные данные клиента:
Пример ответа:
Проверьте category перед использованием содержимого в запросе Direct Send категории Utility. Если Meta определяет MARKETING или AUTHENTICATION, скорректируйте текст или используйте соответствующий сценарий обмена сообщениями. Для проверки кнопок передайте поля type и interactive из приведенного выше примера отправки; поля получателя и отправки указывать не нужно.

Как отличить приостановку шаблона от ограничения аккаунта

Шаблон может быть приостановлен из-за низкого качества. В таком случае отправка сообщений, которые совпадают с ним или очень похожи, завершается ошибкой Meta 132015. Найдите затронутый шаблон в YCloud, проверьте его содержимое и статус и устраните причину, прежде чем возобновлять отправку этого уведомления. Повторное некорректное использование категорий может привести к ограничению Direct Send для всего WABA: Ориентируйтесь на уведомление в аккаунте касательно действующего ограничения и срока его действия. Успешный пересмотр одного шаблона не снимает автоматически ограничение на уровне аккаунта.

Получение уведомлений YCloud

Подпишитесь на whatsapp.template.correct_category_detection через вашу конечную точку Webhook, если хотите получать уведомления об определении категорий. Это не ответ на messageSamples, и оно отправляется не для каждого сообщения. В объекте whatsappTemplate события сравните previousCategory с category. Например, previousCategory: "UTILITY" и category: "MARKETING" означает, что Meta обнаружила маркетинговый контент в шаблоне Utility Direct Send. Проверьте содержимое перед повторной отправкой аналогичных сообщений. Для отслеживания доставки используйте whatsapp.message.updated отдельно. Соответствующие поля события об ограничении аккаунта YCloud:
Используйте WABA ID, чтобы приостановить затронутый сценарий. Обратите внимание на violationType, где указана причина, и restrictions[].expiration, где указан срок окончания (если предоставлен).

Запрос на пересмотр решения по категории

Если вы считаете, что контент был помечен ошибочно, откройте Главная страница Meta Business Support → Аккаунт WhatsApp → Обновления шаблонов Direct Send → Доступно для проверки. Выберите нужные шаблоны и нажмите Запросить проверку. Отправьте запрос в течение 60 дней с момента получения уведомления. Каждый помеченный шаблон можно отправить на проверку только один раз. Отслеживайте результат: In review, Reversed или Unchanged. Если возможность запросить проверку недоступна, обратитесь в YCloud, указав WABA ID, имя или ID шаблона, язык и сведения об уведомлении.

Часто задаваемые вопросы о Direct Send

Для произвольного контента — нет. Передайте полное сообщение, и Meta сопоставит или сгенерирует шаблон. Чтобы преобразовать существующий шаблон Utility, укажите его template.name и установите useDirectSend: true. Необязательное поле templateName задает имя для шаблона Utility Direct Send; оно не выбирает существующий шаблон.
Шаблоны необходимы для проверки категорий и качества, отчетности по эффективности и устранения неполадок. Direct Send избавляет от необходимости создавать их вручную, но не отменяет шаблонную обработку сообщений.
Да, для подходящих уведомлений Utility Direct Send. Ваш WABA должен иметь соответствующий доступ, клиент должен ожидать сообщение, а контент должен соответствовать требованиям категории Utility. Обычные сервисные сообщения в свободной форме по-прежнему требуют открытого сервисного окна.
Генерация и синхронизация шаблонов происходят асинхронно и могут завершиться уже после отправки сообщения. После завершения выберите нужный WABA и примените фильтр Auto generated .
Meta удаляет сгенерированные шаблоны, которые ни разу не использовались для отправки, через 24 часа. Ранее использовавшиеся шаблоны могут быть архивированы после периода неактивности. Удалять их вручную не требуется.
Нет. Meta оценивает фактическое содержимое. Удалите рекламные формулировки из уведомлений Utility и воспользуйтесь процедурой пересмотра, если подлинное сообщение Utility было помечено ошибочно.
Для сообщений категории Utility действуют те же правила тарификации Utility-сообщений, что и для созданных вручную шаблонов Utility. См. раздел WhatsApp pricing.