Платформа WhatsApp Business > Облачный API > Руководства

Модель платы за переписку изменилась. Чтобы узнать о работе новой модели платы за переписку, ознакомьтесь со статьей Расценки.

Кроме того, с 1 июля 2023 г. изменилась видимость metric_types. Подробнее см. в таблице аналитики переписок.

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

Шаблоны сообщений 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/v19.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"
            }
          }
        ]
      }
    ]
  }
}'

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

{
  "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/v19.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/v19.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>"
      }
    }
  ]
}

Свойства

Заполнитель	Описание	Пример значения
`<ADDRESS>`	Адрес, который отображается после значения `<NAME>` под изображением карты в верхней части сообщения.	`1 Hacker Way, Menlo Park, CA 94025`
`<LATITUDE>`	Географическая широта точки.	`37.483307`
`<LONGITUDE>`	Географическая долгота точки.	`122.148981`
`<NAME>`	Текст под изображением карты в верхней части сообщения.	`Pablo Morales`

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

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

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

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 сообщений.

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

Начиная с 6 февраля 2024 года ограничения количества сообщений с шаблоном типа "Маркетинг" на пользователя применяются к шаблонам сообщений, отправляемым небольшому количеству пользователей WhatsApp в Индии, однако с 13 февраля 2024 года они будут применяться ко всем пользователям WhatsApp с индийскими номерами телефонов.

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

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

Если сообщение с шаблоном типа "Маркетинг" не доставляется конкретному пользователю из-за ограничений, облачный API вернет ошибку с кодом 131026, а локальный API — ошибку с кодом 1026. Однако помните, что эти коды обозначают широкий спектр проблем, которые могут воспрепятствовать доставке сообщения. Из соображений конфиденциальности мы не будем сообщать, действительно ли сообщение не было доставлено из-за ограничения. Описание причин, по которым не доставляются сообщения, и информацию о том, как определить причину проблемы, см. в документе Устранение неполадок для облачного API и в вопросе "Почему доставляются не все сообщения?" в часто задаваемых вопросах для локального API.

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

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

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

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

Платформа WhatsApp Business | Облачный API | API Business Management