WhatsApp Business Platform

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

В этом документе описано, как отправлять пользователям WhatsApp сообщения с помощью API.

Типы сообщений

Вы можете использовать API для отправки сообщений следующих типов.

Сообщения с адресом позволяют быстро запросить адрес доставки у пользователей WhatsApp.
В аудиосообщениях показывается значок аудио и ссылка на аудиофайл. Когда пользователь WhatsApp нажимает на значок, клиент WhatsApp загружает этот аудиофайл и воспроизводит его.
Сообщения с контактами позволяют отправлять разнообразную контактную информацию непосредственно пользователям WhatsApp, например имена, номера телефонов, физические адреса и адреса электронной почты.
Сообщения с документами — это сообщения, в которых показывается связанный с документом значок, который пользователь WhatsApp может нажать, чтобы скачать этот документ.
Сообщения с изображениями — это сообщения, в которых показываются одно изображение и необязательная подпись.
Интерактивные сообщения с кнопками призыва к действию с URL позволяют представить любой URL в виде кнопки, так что вам не придется включать длинные или непонятные необработанные URL в тело сообщения.
Интерактивные сообщения Flow позволяют отправлять структурированные сообщения, которые более понятны или удобны для ваших клиентов. Например, можно использовать WhatsApp Flows, чтобы записываться на встречи, просматривать товары, собирать отзывы клиентов, получать новые лиды продаж или выполнять какие-то другие действия.
В интерактивных сообщениях со списками вы можете представлять пользователям WhatsApp списки вариантов, которые они могут выбирать.
В сообщениях с запросом местоположения показывается текст тела и кнопка для отправки местоположения. После нажатия этой кнопки пользователи WhatsApp видят экран предоставления геоданных.
В интерактивных сообщениях с кнопками ответа вы можете отправить до трех заранее определенных ответов, из которых пользователь может выбрать нужный.
Сообщения с местоположением позволяют отправить широту и долготу местоположения пользователю WhatsApp.
В сообщениях со стикерами показываются анимированные или статические изображения стикеров в сообщении WhatsApp.
Текстовые сообщения — это сообщения, содержащие только текстовое тело и необязательный предпросмотр ссылки.
Сообщения с шаблонами позволяют отправлять пользователям WhatsApp шаблоны категории "Маркетинг", "Услуги" и "Аутентификация". В отличие от всех других типов сообщений, для сообщений с шаблонами не требуется, чтобы между вами и получателем было открыто 24-часовое окно обслуживания клиентов перед отправкой сообщения.
В видеосообщениях показывается миниатюра предпросмотра видео и необязательная подпись. Когда пользователь WhatsApp нажимает предпросмотр, видео загружается и воспроизводится.
Сообщения с реакциями — это смайлики, которые могут применяться к ранее полученным сообщениям в WhatsApp.

Окна обслуживания клиентов

Когда пользователь WhatsApp отправляет вам сообщение, начинается (или обновляется, если он уже начат) 24-часовой период, называемый окном обслуживания клиента.

Когда между вами и пользователем открыто окно обслуживания клиентов, вы можете отправлять ему сообщения любого типа. Если окно обслуживания между вами и пользователем не открыто, вы можете отправлять пользователю только сообщения с шаблонами, поскольку это единственный тип сообщений, которые можно отправлять вне окна обслуживания клиентов.

Не забывайте, что вы можете отправлять сообщения только тем пользователям, которые согласились получать их от вас.

Запросы

Во всех запросах на отправку сообщений используется конечная точка POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages:

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Тело сообщения зависит от его типа. При этом в полезных данных используется следующий общий синтаксис:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

Свойство type в полезных данных тела сообщения определяет тип отправляемого сообщения. Кроме того, в них должно быть соответствующее типу сообщения свойство, в котором описывается контент сообщения.

Ниже показан пример запроса на отправку текстового сообщения пользователю WhatsApp. Обратите внимание: для параметра type установлено значение text, а за ним следует объект text, в котором описан контент сообщения:

curl 'https://graph.facebook.com/v21.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

Вот как будет выглядеть сообщение в клиенте WhatsApp, если текстовое сообщение доставлено пользователю WhatsApp:

Ответы

Если API принял ваш запрос на отправку сообщения и не обнаружил в нем никаких ошибок, он вернет следующий ответ. Обратите внимание: в этом ответе указано, что API только принял ваш запрос. Этот ответ не говорит о доставке сообщения. Статус доставки сообщения передается через Webhooks messages.

Синтаксис ответа

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>",
      "message_status": "<PACING_STATUS>"
    }
  ]
}

Содержимое ответа

Webhooks

Сообщения, отправляемые пользователям WhatsApp, инициируют Webhooks messages, поэтому обязательно подпишитесь на эту тему, чтобы получать уведомления о статусе сообщений.

Коммерческие сообщения

Коммерческие сообщения — это интерактивные сообщения, которые используются в сочетании с каталогом товаров. Информацию о том, как использовать сообщения такого типа, см. в статье Предоставление информации о товарах клиентам.

Ответы с контекстом

Ответы с контекстом — это особый способ ответов на сообщения пользователей WhatsApp. Отправка сообщений в виде ответа с контекстом позволяет пользователю лучше понять, на какое сообщение вы отвечаете, по цитате предыдущего сообщения в облачке с контекстом:

В виде ответа с контекстом можно отправлять сообщения любого типа, за исключением сообщений с реакцией.

Ограничения

Облачко с контекстом не появится в верхней части доставленного сообщения если:

• предыдущее сообщение было удалено или перемещено в долгосрочное хранилище (как правило, сообщения перемещаются в долгосрочное хранилище через 30 дней, если вы не активировали локальное хранилище);
• вы отправляете сообщение с аудио, изображением или видео, а пользователь WhatsApp работает на устройстве под управлением KaiOS;
• вы используете клиент WhatsApp, чтобы отправить сообщение Push-To-Talk, а пользователь WhatsApp работает на устройстве под управлением KaiOS;
• вы отправляете сообщение с шаблоном.

Синтаксис запроса

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Тело публикации

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

Параметры тела публикации

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

Пример текстового сообщения, отправляемого в качестве ответа на предыдущее сообщение.

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

Кэширование медиафайлов

Если вы используете ссылку (link) на медиаобъект на своем сервере, а не ID (id) объекта, загруженного на наши серверы, облачный API WhatsApp кэширует этот объект на статический период времени длительностью 10 минут. Если ссылка в полезных данных последующих сообщениях будет совпадать со ссылкой в полезных данных начального сообщения, в последующих запросах на отправку сообщений мы будем использовать этот кэшированный объект.

Если вы не хотите, чтобы мы использовали кэшированный объект в последующих сообщениях в течение 10 минут, добавьте к ссылке на объект в полезных данных нового запроса на отправку сообщения произвольную строку запроса. Мы сочтем этот объект новым, получим его с вашего сервера и кэшируем на 10 минут.

Пример:

• ссылка на объект в первом запросе на отправку сообщения: https://link.to.media/sample.jpg — объект получается и кэшируется на 10 минут;
• ссылка на объект во втором запросе на отправку сообщения: https://link.to.media/sample.jpg — используется кэшированный объект;
• ссылка на объект в третьем запросе на отправку сообщения: https://link.to.media/sample.jpg?abc123 — объект получается и кэшируется на 10 минут.

Последовательность доставки нескольких сообщений

При отправке серии сообщений нет гарантии того, что порядок их доставки будет соответствовать порядку ваших запросов API. Если вам необходимо обеспечить определенную последовательность доставки сообщений, подтвердите получение статуса delivered в Webhooks сообщений перед отправкой следующего сообщения в последовательности.

Время жизни сообщения (TTL)

Если нам не удается доставить сообщение пользователю WhatsApp, мы продолжаем попытки в течение некоторого времени. Оно называется временем жизни (TTL) или периодом действия сообщения.

TTL по умолчанию

• Все сообщения, кроме сообщений с шаблонами категории "Аутентификация": 30 дней.
• Шаблоны категории "Аутентификация": 10 минут.

Настройка времени жизни для шаблонов категорий "Аутентификация", "Услуги" и "Маркетинг"

Вы можете настроить устанавливаемое по умолчанию время жизни для шаблонов категорий "Аутентификация", "Услуги" и "Маркетинг", отправляемых с помощью MM Lite API.

Подробнее см. в статье Время жизни (TTL): настройка, значения по умолчанию, минимальные и максимальные значения и совместимость.

Если время жизни превышено: сброшенные сообщения

Сообщения, которые не удается доставить в течение установленного по умолчанию или настроенного пользователем времени жизни, сбрасываются.

Если вы не получите уведомление Webhooks о доставке сообщения до истечения времени жизни, это сообщение можно считать сброшенным.

Если вы отправляете сообщение, которое не доставляется, уведомление Webhooks может прийти с небольшой задержкой, поэтому сообщение стоит считать сброшенным только по прошествии некоторого времени.

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

Если у вас возникают проблемы с доставкой сообщений, обратитесь к разделу Сообщение не доставляется.