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

В этом документе описано, как отправлять пользователям 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/v20.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 принял ваш запрос на отправку сообщения и не обнаружил в нем никаких ошибок, он отправляет следующий ответ:

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

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

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

Webhooks

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

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

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

Ответы

Можно отправить сообщение любого типа в качестве ответа на предыдущее сообщение. Предыдущее сообщение отобразится в верхней части нового сообщения в разделе контекста.

Ограничения

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

• Предыдущее сообщение было удалено или перемещено в хранилище для длительного хранения (как правило, сообщения перемещаются в хранилище для длительного хранения через 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!"
  }
}'

Медиаобъекты

Медиаобъекты, отправляемые в сообщениях, необходимо загружать для номера телефона компании, с которого будет отправляться сообщение, либо вы должны хранить объект на общедоступном сервере и добавить его URL в запрос на отправку сообщения.

Чтобы уменьшить вероятность ошибок и избежать отправки лишних запросов на ваш общедоступный сервер, рекомендуем загрузить медиафайлы и использовать их ID при отправке сообщений.

HTTP-кэширование медиафайлов

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

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

Заголовок Cache-Control указывает нам, как выполнять кэширование объекта. Мы поддерживаем следующие инструкции:

• max-age=n — указывает, время в секундах (n), в течение которого объект должен храниться в кэше. Мы будем повторно использовать кэшированный объект в последующих сообщениях до истечения указанного времени. После этого, если потребуется, мы запросим объект снова. Пример: Cache-Control: max-age=604800.
• no-cache — указывает, что объект можно кэшировать, но необходимо обновить, если заголовок Last-Modified в предыдущем ответе отличается от текущего. Требуется заголовок Last-Modified. Пример: Cache-Control: no-cache.
• no-store — указывает, что объект не требуется кэшировать. Пример: Cache-Control: no-store.
• private — указывает, что объект персонализирован для получателя и его не нужно кэшировать.

Last-Modified

Указывает, когда объект был изменен. Используется с Cache-Control: no-cache. Если значение Last-Modified в предыдущем ответе отличается, а в ответе имеется инструкция Cache-Control: no-cache, мы заменим кэшированную версию объектом из ответа. Пример: Date: Tue, 22 Feb 2022 22:22:22 GMT.

Заголовки ETag

ETag — это уникальная строка, определяющая версию объекта. Пример: ETag: "33a64df5". Если в ответе отсутствуют заголовки Cache-Control и Last-Modified, этот заголовок игнорируется. В этом случае мы кэшируем объект в соответствии с нашей внутренней логикой, которая не подлежит разглашению.

Пример запроса с заголовками

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

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

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

Время жизни

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

• Время жизни для всех сообщений, за исключением сообщений с шаблонами категории "Аутентификация", составляет 30 дней.
• Время жизни сообщений с шаблонами категории "Аутентификация" составляет 10 минут.

Вы можете настроить собственное время жизни для сообщений с шаблонами категорий "Аутентификация" и "Услуги". См. раздел Настройка времени жизни.

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

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

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

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