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.

Request

POST /v1/messages
{
    "to": "recipient_wa_id",
    "ttl": "P4D" | "3600" | 3600,
    "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

NameRequiredDescription

to

Yes

WhatsApp ID of the recipient

ttl

No

Time To Live (TTL) duration
See the ttl object section above for more information

type

No

Set to template to send a media template message

template

Yes (For template messages)

Contains all the template information

The template object

NameRequiredDescription

namespace

Yes

Namespace of the template

name

Yes

Name of the template

language

Yes

Specifies the language the template may be rendered in
See the Message Template — Language documentation for more information.

components

No

Array containing the parameters of the message

The components object

NameRequiredDescription

type

Yes

Describes the component type
Values: header, body, footer, button

parameters

No

Array containing the content of the message

The parameters object

NameRequiredDescription

type

Yes

Describes the parameter type
Values: text, currency, date_time, image, document, video, location, button
For more information about media types (image, document, and video) see the Media documentation. Note: The document media message template type is currently limited to PDF format.
For more information about currency and date_time, see the Message Templates — Localizable Parameters documentation. Note: The currency and date_time parameters for template messages uses fallback_value in place of default. See the Request sample above for an example.

The button type

NameRequiredDescription

sub_type

Yes

Type of button being created
Values: quick_reply, url

index

Yes

Position index of the button
You can have up to 3 buttons using index values of 0-2

parameters

Yes

The parameters for the button, which are set at creation time in your Business Manager

The sub_type parameter

NameRequiredDescription

quick_reply

No

Refers to a previously created quick reply button that allows for the customer to return a predefinied message
See Callback from a Quick Reply Button Click below for an example of a response from a quick reply button

url

No

Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the pre-defined prefix URL in the template

The parameters object

NameRequiredDescription

type

Yes

Indicates the type of parameter for the button
Values: payload, text

payload

Yes (for quick_reply buttons)

Developer-defined payload that will be returned when the button is clicked in addition to the display text on the button
See Callback from a Quick Reply Button Click below for an example of a response from a quick reply button

text

Yes (for url buttons)

Developer provided suffix that will be appended to a previously created dynamic URL button

Response

A successful response includes a messages object with an id.

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

An unsuccessful response will contain an error object that will contain 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.

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 message or just send you a message. Make sure that you are able to support this type of scenario as well. See the Webhooks docuemntation for more information.

{
    "context": {
         "from": "sender-wa_id",
         "group_id": "message-group-id",
         "id": "message-id",
         "mentions": [ "wa-id1", "wa-id2" ],
    },

    "from": "sender-wa_id",
    "group_id": "message-group-id",
    "id": "message-id",
    "timestamp": "message-timestamp",
    "type": "button"
    "button": {
        "payload": "developer-defined-payload"
        "text": "display-text"
    }
    # Only in case of error, errors field (array) will be present        
    "errors": [ { ... } ],    
}