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, # The "ttl" field will be deprecated in v2.35.
    "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

Name Description

type

Required for message templates.

The type of message being sent.
Options:

  • text - Default
  • image
  • audio
  • document
  • template - Use this to send a media template message
  • hsm

to

Required.

The WhatsApp ID to whom the message is being sent.

ttl
To be deprecated in v2.35

Optional.

As of v2.21.3 — Time To Live (TTL) duration.
Default: 7 days
Other options: The minimum and maximum supported durations are 1 to 30 days (both inclusive).


Accepts both a string in the ISO-8601 duration format as well as just seconds. Durations must be specified in exact multiple of days; any values that are in between are automatically rounded to the nearest day. See the ttl object section for more information.

recipient_type

Optional.

Value: individual

template

Required for template messages.

Contains all the template information.

hsm

Required for message templates.

The containing element for the message content. Indicates that the message is highly structured. Parameters contained within provide the structure.

The template object

NameDescription

namespace

Required.

Namespace of the template.


Beginning with v2.27.8, this must be the namespace associated with the WhatsApp business account that owns the phone number associated with the current WhatsApp Business API client or the message fails to send.

name

Required.

Name of the template.

language

Required.

Specifies the language the template may be rendered in. Only the deterministic language policy works with media template messages. See the Language section for more information.

components

Optional.

Array containing the parameters of the message.

The components object

NameDescription

type

Required.

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

parameters

Optional.

Array containing the content of the message.

The parameters object

NameDescription

type

Required.

Describes the parameter type.
Values: text, currency, date_time, image, document, video


The media types (image, document and video) follow the same format as those used in standard media messages, see the Media documentation for more information. Only PDF documents are currently supported for media message templates.


For more information about currency and date_time, see the Localizable Parameters section. 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

NameDescription

sub_type

Required.

Type of button being created.
Values: quick_reply, url

index

Required.

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

parameters

Required.

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

The sub_type parameter

NameDescription

quick_reply

Optional.

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

Optional.

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

NameDescription

type

Required.

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

payload

Required 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

Required 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 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": [ { ... } ]
}