Локальный API платформы WhatsApp Business

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

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

Предлагаются два типа заранее заданных кнопок:

  • Призыв к действию — позволяет вашему клиенту звонить на номер телефона и посещать веб-сайт
  • Быстрый ответ — позволяет вашему клиенту ответить с использованием простого текстового сообщения

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

Прежде чем начать

Вам потребуется:

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

Ограничения

  • В шаблоны сообщений с призывом к действию вы можете добавить 2 кнопки, по одной кнопке каждого типа (звонок на номер телефона и переход на веб-сайт).
  • В шаблоны сообщений быстрого ответа можно добавить до 3 кнопок.

Шаг 1. Выполните запрос POST к /messages.

POST /v1/messages
{
    "to": "recipient_wa_id",
    "type": "template",
    "template": {
        "namespace": "your-namespace",
        "language": {
            "policy": "deterministic",
            "code": "your-language-and-locale-code"
        },
        "name": "your-template-name",
        "components": [
            {
                "type" : "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "replacement_text"
                    }
                ]
            # end header
            },
            {
                "type" : "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "replacement_text"
                    },
                    {
                        "type": "currency",
                        "currency" : {
                            "fallback_value": "$100.99",
                            "code": "USD",
                            "amount_1000": 100990
                        }
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "February 25, 1977",
                            "day_of_week": 5,
                            "day_of_month": 25,
                            "year": 1977,
                            "month": 2,
                            "hour": 15,
                            "minute": 33, #OR
                            "timestamp": 1485470276
                        }
                    },
                    {
                        ...
                        # Any additional template parameters
                    }
                ] 
            # end body
            },

            # The following part of this code example includes several possible button types, 
            # not all are required for an interactive message template API call.
            {
                "type": "button",
                "sub_type" : "quick_reply",
                "index": "0", 
                "parameters": [
                    {
                        "type": "payload",
                        # Business Developer-defined payload
                        "payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type" : "url",
                "index": "1", 
                "parameters": [
                    {
                        "type": "text",
                        # Business Developer-defined dynamic URL suffix
                        "text": "9rwnB8RbYmPF5t2Mn09x4h"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type" : "url",
                "index": "2",
                "parameters": [
                    {                    
                        "type": "text",
                        # Business Developer-defined dynamic URL suffix
                        "text": "ticket.pdf"
                    }
                ]
            }
        ]
    }
}

Параметры

Шаг 2. Проверьте ответ API.

В случае успеха ответ содержит объект messages с указанием id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}

В противном случае ответ содержит объект ошибки со строкой ошибки, кодом ошибки и прочей информацией.

Если шаблон отправляется аккаунту, который не может его получить, на настроенный сервер Webhooks будет отправлен объект ошибки 1026 (ReceiverIncapable).

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

Дополнительный шаг 3. Обработайте действие пользователя.

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

Обратный вызов при нажатии кнопки быстрого ответа

Когда клиент нажимает кнопку быстрого ответа, отправляется определенный отклик. Ниже приведен пример формата обратного вызова. Примечание. Возможна ситуация, когда клиент не нажимает кнопку, а отвечает на интерактивное сообщение или просто отправляет сообщение вам. Поддержку такого сценария также необходимо реализовать. Подробные сведения см. в документации по Webhooks. 
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

Примеры

В этих примерах демонстрируется процесс настройки интерактивных шаблонов сообщений от создания шаблона в Business Manager до отправки шаблонов через вызовы API к конечной точке messages.

Напоминание о поездке

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

1. Создайте интерактивный шаблон сообщения с медиафайлом в Business Manager.

2. Добавьте информацию о параметрах с помощью вызова API messages.

POST /v1/messages
{
    "to": "your-test-recipient-wa-id",
    "recipient_type": "individual",
    "type": "template",
    "template": {
        "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
        "name": "upcoming_trip_reminder",
        "language": {
            "code": "en",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "12/26"
                    }
                ]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "*Ski Trip*"
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "29th July 2019, 8:00am",
                            "day_of_month": "29",
                            "year": "2019",
                            "month": "7",
                            "hour": "8",
                            "minute": "00"
                        }
                    },
                    {
                            "type": "text",
                            "text": "*Squaw Valley Ski Resort, Tahoe*"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                    {
                        "type": "payload",
                        "payload": "Yes-Button-Payload"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 1,
                "parameters": [
                    {
                        "type": "payload",
                        "payload": "No-Button-Payload"
                    }
                ]
            }
        ]
    }
}

3. Ваш клиент получит напоминание о поездке, в котором будут кнопки быстрого ответа.

Отправка товара

В этом примере создается интерактивный шаблон сообщения с медиафайлом с URL и кнопками звонка на номер телефона.

1. Создайте интерактивный шаблон сообщения с медиафайлом в Business Manager:

2. Добавьте информацию о параметрах с помощью вызова API messages.

POST /v1/messages
{
    "to": "your-test-recipient-wa-id",
    "recipient_type": "individual",
    "type": "template",
    "template": {
        "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
        "name": "oculus_shipment_update",
        "language": {
            "code": "en",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "header",
                "parameters": [{
                    "type": "image",
                    "image": {
                        "link": "link-to-your-image"
                    }
                }]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Anand"
                    },
                    {
                        "type": "text",
                        "text": "Quest"
                    },
                    {
                        "type": "text",
                        "text": "113-0921387"
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "23rd Nov 2019",
                            "day_of_month": "20",
                            "year": "2019",
                            "month": "9"
                        }
                    }
                ] 
            },
            {
                "type": "button",
                "index": "0",
                "sub_type": "url",
                "parameters": [
                    {
                        "type": "text",
                        "text": "1Z999AA10123456784"
                    }
                ]
            }
        ]
    }
}

3. Ваш клиент получит сообщение об отправке его товара, в котором будут URL и кнопки звонка на номер телефона: