We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.
Sending Media Message Templates
Media message templates expand the content you can send recipients beyond the standard message template type to include media and headers using a components object. The components object allows you to indicate the type of message and the message's parameters.
 |  |  |
Step 1: Make POST Request to /messages
POST /v1/messages
{
"to": "recipient_wa_id",
"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"
}
}
# OR
{
"type": "video",
"video": {
"link": "the-provider-name/protocol://the-url"
# provider is an optional parameter
"provider": {
"name" : "provider-name"
}
}
}
# 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
Media Format Recommendation
- Images taller than 1.91:1 aspect ratio are cropped vertically. To communicate the crux in such images, plan to present the most important information at the center of the image.
Step 2: Check the API Response
A successful response includes a messages object with an id.
{
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
An unsuccessful response contains an error object with 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.
Examples
These examples demonstrate the process of setting up media message templates beginning with the template creation in your Business Manager and sending the message templates with API calls to the messages endpoint.
These examples are for illustrative purposes only and cannot be used. You must create your own samples and have them approved in order to test the media message template functionality.
Movie ticket example
This example show the creation of a media message template with a QR code image.
1. Create the media message template in your Business Manager.
2. The messages API call adds in the parameter information.
POST /v1/messages
{
"to": "your-test-recipient-wa-id",
"recipient_type": "individual",
"type": "template",
"template": {
"namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
"name": "movie_ticket_update",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"id": "your-image-id"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Star Rangers"
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "May 1st, 2019 8:45pm",
"day_of_month": 20,
"year": 2019,
"month": 9,
"hour": 20,
"minute": 45
}
},
{
"type": "text",
"text": "Carnival, Sangam"
},
{
"type": "text",
"text": "Silver"
},
{
"type": "text",
"text": "F6, F7, F8"
}
]
}
]
}
}
3. Your customer receives their movie ticket message.
Flight ticket example
This example show the creation of a media message template with a PDF document.
1. Create the media message template in your Business Manager.
2. The messages API call adds in the parameter information.
POST /v1/messages
{
"to": "your-test-recipient-wa-id",
"recipient_type": "individual",
"type": "template",
"template": {
"namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
"name": "flight_confirmation",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "document",
"document": {
"filename": "MRRATH-CGK-KUL.pdf",
"link": "link-to-your-document"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "CGK (Jakarta)"
},
{
"type": "text",
"text": "KUL (Kuala Lumpur)"
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "20th April 2019, 12:20pm",
"day_of_month": 20,
"year": 2019,
"month": 9,
"hour": 12,
"minute": 10
}
}
]
}
]
}
}
3. Your customer receives their boarding pass in a PDF document.
