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.
You can use the /messages endpoint to send message templates to your customers. A message template can be text-based, media-based, or interactive.
To learn more about message templates, see Messages, Business-Initiated Messages.
Make sure that you have completed the actions in the Messages — Prerequisites documentation.
Message templates are created in the WhatsApp Manager, which is part of your WhatsApp Account in the Facebook Business Manager. Your message templates will be reviewed to ensure they do not violate WhatsApp policies. Once approved, your business will have its own namespace where the message templates live.
When creating a message template, you must have the following:
When creating a message template, you can add a sample template by clicking the Add Sample button. This helps us during the review and approval process, so we can understand what kind of message you plan to send. Make sure these are examples and do not include any confidential or personal information.
See Create Message Templates for your WhatsApp Business API Account for more detailed steps for creating message templates.
Creating a welcome message where the message template name is welcome and the message is
"Welcome {{1}}. We look forward to serving you on WhatsApp." Creating an order confirmation message where the message template name is order_confirmation and the message is
"Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}." WhatsApp does not do any translations for your business. All message template translations must be entered by you in same format described here. The element name is the same for all translations. For more information, see:
POST Request to /messagesOnce you have your template, you can send it to your customers via the template object:
POST /v1/messages
{
"to": "recipient_wa_id",
"type": "template",
"template": {
"namespace": "your-namespace",
"name": "your-template-name",
"language": {
"code": "your-language-and-locale-code",
"policy": "deterministic"
},
"components": [{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
},
{
"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
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"timestamp": 1485470276
}
}
]
}]
}
}
Only URL, QUICK_REPLY, and PHONE_NUMBER button types are supported.
If a template contains a button type not on this list, the API will return an error.
template object, components object, parameters object, and the language object.language object, Localizable parameters.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. See Error and Status Codes for more information.
Starting February 6, 2024, per-user marketing template message limits apply to template messages sent to a small number of WhatsApp users in India, but will apply to all WhatsApp users with an Indian phone number by February 13, 2024.
We are rolling out new approaches, starting with consumers in India, that create high-quality user experiences and maximize marketing template message engagement. This may include limiting the number of marketing template messages a person receives from any business in a given period of time, starting with a small number of conversations that are less likely to be read. Note that the limit is determined based on the number of marketing template messages that person has already received from any business, and is not related to your business specifically.
The limit only applies to marketing template messages that would normally open a new marketing conversation. If a marketing conversation is already open between you and a WhatsApp user, marketing template messages sent to the user will not be affected.
If a marketing template message is not delivered to a given user due to the limit, On-Premises API will return error code 1026. Note, however, that this error code covers a wide range of issues that can result in non-delivery of a message, and for privacy reasons, we will not disclose if in fact the message was not delivered due to the limit. Refer to the "Why is my delivery rate not 100%?" FAQ for more information.
If you do receive one of these error codes and suspect it is due to the limit, avoid immediately resending the template message, as it will only result in another error response. Instead, retry in increasing larger time increments until the message is delivered, since the limit may be in effect for differing periods of time.
We'll continue refining our approach and appreciate your partnership as we invest in making WhatsApp the best possible experience for your business and your customers.