Media Message Templates

Beginning with v2.25.4, media message templates expand the content you can send recipients beyond the standard message template type to include media, headers, and footers 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",
      "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

      {
        "type": "document",
        "document": {
          "id": "your-media-id",
          # caption and filename are optional parameters
          "caption": "your-document-caption-to-be-sent",
          "filename": "your-document-filename"
        }
      }

      # OR

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

      # OR

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

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
Note: This must be the namespace associated with the WhatsApp business account that owns the phone number associated with the current WhatsApp Business API client

name

Yes

Name of the template

language

Yes

Specifies the language the template may be rendered in
Only the deterministic language policy works with media template messages
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

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
The media types (image and document) follow the same format as those used in standard media messages, see the Media documentation for more information. Note: Only PDF documents are currently supported for media message templates.
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.

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.