WhatsApp Business Platform

Сообщения с шаблонами

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

Сначала нужно создать шаблон сообщения. Подробнее об этом см. в статье Создание шаблонов сообщений для аккаунта WhatsApp Business. Если ваш аккаунт ещё не подтвержден, вы можете использовать один из предварительно одобренных шаблонов.

Сейчас вы можете использовать шаблоны следующих типов:

• шаблоны текстовых сообщений;
• шаблоны сообщений с медиафайлами;
• шаблоны интерактивных сообщений;
• шаблоны сообщений с местоположением;
• шаблоны категории "Аутентификация" с кнопками одноразового пароля;
• шаблоны сообщений с несколькими товарами.

Все вызовы API в этом руководстве должны быть аутентифицированы с помощью маркера доступа. Разработчики могут аутентифицировать вызовы API с помощью маркера доступа, сгенерированного в разделе Панель приложений > WhatsApp > Настройка API. Партнеры по решениям должны пройти аутентификацию с помощью маркера доступа с использованием разрешения whatsapp_business_messaging.

Оценивание

Недавно созданные или разблокированные маркетинговые шаблоны должны пройти оценивание. См. Оценивание шаблонов.

Шаблоны текстовых сообщений

Чтобы отправить шаблон текстового сообщения, выполните вызов POST к /PHONE_NUMBER_ID/messages и добавьте объект сообщения с параметром type=template. Затем добавьте объект template.

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

curl -X  POST \
 'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "text-string"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Шаблоны сообщений с медиафайлами

Чтобы отправить шаблон сообщения с медиафайлом, выполните вызов POST к /PHONE_NUMBER_ID/messages и добавьте объект сообщения с параметром type=template. Затем добавьте объект template. Поддерживается кэширование HTTP для медиафайлов.

Чтобы отправить шаблон сообщения с медиафайлом, используйте конечную точку /PHONE_NUMBER_ID/messages. Задайте для свойства type значение template. С помощью свойства template определите объект шаблона и его медиаобъект.

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

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

Медиафайлы также можно кэшировать. См. раздел HTTP-кэширование для медиафайлов.

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

curl -X  POST \
 'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT-STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Шаблоны интерактивных сообщений

В шаблонах интерактивных сообщений получателям можно отправлять более сложные сообщения с кнопками, используя объект components. Существует два типа заранее заданных кнопок:

• призыв к действию позволяет вашему клиенту позвонить на номер телефона и перейти на сайт;
• быстрый ответ позволяет вашему клиенту ответить простым текстовым сообщением.

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

Чтобы отправить шаблон интерактивного сообщения, выполните вызов POST к /PHONE_NUMBER_ID/messages и добавьте объект сообщения с параметром type=template. Затем добавьте объект template с выбранным параметром button.

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

curl -X  POST \
 'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Шаблоны сообщений с местоположением

Чтобы отправить шаблон, в заголовке которого указано местоположение, запрос должен содержать объект header с объектом location.

Синтаксис

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

Свойства

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

В этом примере запроса на отправку существующего шаблона указаны следующие компоненты:

• заголовок с местоположением;
• тело текста с переменной;
• нижний колонтитул;
• кнопка быстрого ответа.

curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12245554792",
  "type": "template",
  "template": {
    "name": "order_delivery_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "37.483307",
              "longitude": "122.148981",
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "566701"
          }
        ]
      }
    ]
  }
}'

Шаблоны категории "Аутентификация"

При попытке отправить устаревшие шаблоны аутентификации (шаблоны без кнопок одноразовых паролей) будет возвращена ошибка с кодом 100, если значения переменных содержат более 15 символов, содержат ссылки или смайлики, или же компонент тела шаблона содержит ссылку. Вместо этого создайте и используйте шаблон аутентификации с кнопкой одноразового пароля.

См. статьи Шаблоны категории "Аутентификация" и Отправка шаблонов сообщений категории "Аутентификация".

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

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

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

WhatsApp предоставляет настройку (Предложения и объявления), которая позволяет пользователям останавливать или возобновлять получение сообщений с шаблоном категории "Маркетинг" от вашей компании или указывать уровень своей заинтересованности в сообщениях такого типа.

Кнопки "Остановить" и "Возобновить"

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

Если вы попытаетесь отправить шаблон категории "Маркетинг" пользователю WhatsApp, который остановил получение сообщений с шаблоном категории "Маркетинг" от вашей компании, API обработает этот запрос, но не отправит сообщение. Вместо этого API активирует компонент Webhooks сообщений, в котором:

• status — значение failed,
• code — значение 131050,
• title — значение Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business

Чтобы получать уведомления всякий раз, когда пользователь WhatsApp останавливает или возобновляет получение сообщений с шаблоном категории "Маркетинг" от вашей компании, подпишитесь на user_preferences webhook.

Отзывы "Интересует" и "Не интересует"

Пользователи WhatsApp могут использовать эту настройку, чтобы указать, насколько они заинтересованы в получении сообщений с маркетинговыми шаблонами от вашей компании.

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

Ограничения количества сообщений с шаблоном категории "Маркетинг" на пользователя

Что это такое?

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

Почему это важно?

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

Почему это важно для вашей компании?

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

Пример:

• Первое сообщение с шаблоном категории "Маркетинг" доставляется и открывает 24-часовое окно обслуживания клиента для маркетинговой переписки. Действует ограничения количества сообщений с шаблоном категории "Маркетинг" на пользователя.

• В существующей переписке можно отправить второе сообщение с шаблоном категории "Маркетинг".

• Каждый раз, когда пользователь WhatsApp ответит в окне существующей переписки, вы можете отправить ему еще одно сообщение с шаблоном категории "Маркетинг". При этом вы можете отправлять неограниченной количество сообщений в свободной форме.

Какой код ошибки будет использоваться для уведомления?

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

Если сообщение с шаблоном категории "Маркетинг" не отправлено из-за ограничения количества шаблонов категории "Маркетинг" на пользователя, будет запущен компонент Webhooks сообщений со статусом "Не удалось" и кодом (ошибки) 131049 (для облачного API) или 1026 (для локального API).

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

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

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

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