Media and Interactive Message Templates (Beta)

Media message templates expand the content you can send recipients beyond the standard message template type to include media, headers, footers, and buttons using a components object. The components object allows you to indicate the type of message and the message's parameters.

Request

POST /v1/messages
{
    "to": "recipient_wa_id",
    "ttl": "P4D" | "3600" | 3600,
    "type": "template",
    "template": {
      "namespace": "your-namespace",
      "language": {
        "policy": "deterministic | fallback",
        "code": "your-language-and-locale-code"
      },
      "name": "your-template-name"
      "components": [
      {
        "type" : "header",
        "parameters": [
          # The following parameters code example includes several different possible header types, 
          # not all are required for a media message template API call.
  
          {
            "type": "text",
            "text": "replacement_text"
          }
  
          # OR
  
          "document": {
              "id": "your-media-id",
              # capiton and filename are optional parameters
              "caption": "your-document-caption-to-be-sent",
              "filename": "your-document-filename"
            }
  
          # OR

          "document": {
              "link": "the-provider-name/protocol://the-url"
              # provider, capiton, and filename are optional parameters
              "provider": {
                  "name" : "provider-name"
              },
              "caption": "your-document-caption",
              "filename": "your-document-filename"
            }

        # OR

          "video": {
            "id": "your-media-id",
            "caption": "your-video-caption"
          }

        # OR

          "video": {
              "link": "the-provider-name/protocol://the-url"
              # provider and capiton are optional parameters
              "provider": {
                  "name" : "provider-name"
              }
              "caption": "your-video-caption" 
          }

        # OR

          "image": {
              "link": "http(s)://the-url"
              # provider and capiton are optional parameters
              "provider": {
                  "name" : "provider-name"
              }
              "caption": "your-image-caption"
            }
  
          # OR
  
          { 
            "type": "location"
            "location": {
              "longitude": -122.425332,
              "latitude": 37.758056,
            }
          }
        ]
        # 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
      },
      {
        "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, content, 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

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