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.
We are making changes to the WhatsApp Business Platform pricing model. See Pricing Updates on the WhatsApp Business Platform.
Sending 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.
Before You Start
You need to:
- Meet all the prerequisites listed in the Before You Start section of the Messages documentation.
- Have created an interactive message template on Business Manager. You can either add a call-to-action button or a quick reply button.
Once the message template is approved, you can use the API to send a message.
Constraints
- For call-to-action templates, you can add 2 buttons, up to one button of each type (call phone number and visit website).
- For quick reply templates, you can add up to 3 buttons.
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": [
{
"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
- Parameters common to all message requests
- Parameters for message templates:
templateobjectcomponentsobject: for interactive message templates, include thebuttontype and thesub_typefieldparametersobject
Step 2: Check Your 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.
Optional Step 3: Handle User Action
When a user clicks a quick reply button, a responjse is sent back to the business. See Callback from a Quick Reply Button Click for information. Users can also choose to not click the button and just send you a free form message.
Callback from a Quick Reply Button Click
{
"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": [ { ... } ]
}
Examples
These examples illustrate the process of setting up interactive message templates beginning with the template creation in your Business Manager and sending the message templates with API calls to the messages endpoint.
Trip Reminder
This example shows the creation of an interactive media message template with quick reply buttons.
1. Create the interactive 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": "upcoming_trip_reminder",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "text",
"text": "12/26"
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "*Ski Trip*"
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "29th July 2019, 8:00am",
"day_of_month": "29",
"year": "2019",
"month": "7",
"hour": "8",
"minute": "00"
}
},
{
"type": "text",
"text": "*Squaw Valley Ski Resort, Tahoe*"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 0,
"parameters": [
{
"type": "payload",
"payload": "Yes-Button-Payload"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 1,
"parameters": [
{
"type": "payload",
"payload": "No-Button-Payload"
}
]
}
]
}
}
3. Your customer receives their trip reminder message with quick reply buttons.
Product Shipment
This example show the creation of an interactive media message template with URL and phone number buttons.
1. Create the interactive 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": "oculus_shipment_update",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [{
"type": "image",
"image": {
"link": "link-to-your-image"
}
}]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Anand"
},
{
"type": "text",
"text": "Quest"
},
{
"type": "text",
"text": "113-0921387"
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "23rd Nov 2019",
"day_of_month": "20",
"year": "2019",
"month": "9"
}
}
]
},
{
"type": "button",
"index": "0",
"sub_type": "url",
"parameters": [
{
"type": "text",
"text": "1Z999AA10123456784"
}
]
}
]
}
}
3. Your customer receives their product shipment message with URL and phone call buttons:
