We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

Sending Interactive Message Templates

Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons using the components object.

There are two types of predefined buttons offered:

  • Call-to-Action — Allows your customer to call a phone number and visit a website
  • Quick Reply — Allows your customer to return a simple text message

These buttons can be attached to text messages or media messages. Once your interactive message templates have been created and approved, you can use them in notification messages as well as customer service/care messages.

Before You Start

You need to:

Once the message template is approved, you can use the API to send a message.

Constraints

  • For call-to-action templates, you can add 2 buttons, up to one button of each type (call phone number and visit website).
  • For quick reply templates, you can add up to 3 buttons.

Step 1: Make POST Request to /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"
                    }
                ]
            }
        ]
    }
}

Parameters

Step 2: Check Your API Response

A successful response includes a messages object with an id.

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

An unsuccessful response contains an error object with an error string, error code and other information.

If a template is sent to an account that is incapable of receiving the template, the 1026 (ReceiverIncapable) error will be sent in the error object to the configured Webhook server.

See Error and Status Codes for more information on errors.

Optional Step 3: Handle User Action

When a user clicks a quick reply button, a responjse is sent back to the business. See Callback from a Quick Reply Button Click for information. Users can also choose to not click the button and just send you a free form message.

Callback from a Quick Reply Button Click

When your customer clicks on a quick reply button, a response is sent. Below is an example of the callback format. Note: A customer may not click a button and either reply to the interactive template message or just send you a message. Make sure that you are able to support this type of scenario as well. See the Webhooks documentation for more information.
{
    "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": [ { ... } ]
}

Examples

These examples illustrate the process of setting up interactive message templates beginning with the template creation in your Business Manager and sending the message templates with API calls to the messages endpoint.

Trip Reminder

This example shows the creation of an interactive media message template with quick reply buttons.

1. Create the interactive media message template in your Business Manager.

2. The messages API call adds in the parameter information.

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. Your customer receives their trip reminder message with quick reply buttons.

Product Shipment

This example show the creation of an interactive media message template with URL and phone number buttons.

1. Create the interactive media message template in your Business Manager:

2. The messages API call adds in the parameter information.

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. Your customer receives their product shipment message with URL and phone call buttons: