Media Message Templates

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",
          # filename is an optional parameter
          "filename": "your-document-filename"
        }
      }

      # OR

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

      # OR
  
      {
        "type": "video",
        "video": {
          "id": "your-media-id",
          "caption": "your-video-caption"
        }
      }

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

      # OR

      {
        "type": "image",
        "image": {
          "link": "http(s)://the-url",
          # provider is an optional parameter
          "provider": {
            "name" : "provider-name"
          },
        }
      }
    ]
    # 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

Name	Required	Description
`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

Name	Required	Description
`namespace`	Yes	Namespace of the template Note: 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 will fail to send
`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

Name	Required	Description
`type`	Yes	Describes the `component` type Values: `header`, `body`, `footer`
`parameters`	No	Array containing the content of the message

The `parameters` object

Name	Required	Description
`type`	Yes	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. 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.