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.
Starting April 1, 2025, we are temporarily pausing delivery of marketing template messages to WhatsApp users who have a United States phone number. See Per-User Marketing Template Message Limits for additional information.
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 /messages
Once 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 November 22, 2024, we will begin gradually rolling out user preferences for marketing messages. This feature may not be available to WhatsApp users in some regions initially.
WhatsApp provides a setting (Offers and announcements) that allows users to stop or resume delivery of marketing template messages from your business, or indicate their interest level in these types of messages.
WhatsApp users can use the setting to stop or resume delivery of marketing template messages from your business using the Stop and Resume buttons in the Offers and announcements overlay.
If you attempt to send a marketing template to a WhatsApp user who has stopped marketing template messages from your business, the API will process the request but not send the message. Instead, the API will trigger a message webhook with (error) code
set to 498
:
{ "statuses": [ { "errors": [ { "code": 498, "href": "https://developers.facebook.com/docs/whatsapp/api/errors/", "title": "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business" } ], "id": "<WHATSAPP_MESSAGE_ID>", "message": { "recipient_id": "<WHATSAPP_USER_PHONE_NUMBER>" }, "status": "failed", "timestamp": <WEBHOOK_SENT_TIMESTAMP>, "type": "message" } ] }
To be notified whenever a WhatsApp user stops or resumes delivery of marketing template messages from your business, subscribe to the user_preferences webhook.
WhatsApp users can use the setting to indicate how interested they are in receiving marketing template messages from your business.
If a user chooses Not interested, it can affect per-user marketing template messaging limits between you and the user.
Starting April 1, 2025, we will temporarily pause delivery of all marketing template messages to WhatsApp users who have a United States phone number (a number composed of a +1 dialing code and a US area code). This pause is intended to allow us to focus on building a better consumer experience in the US, which will ultimately lead to improved outcomes for businesses.
Attempting to send a template message to a WhatsApp user with a US phone number after this date will result in an error.
WhatsApp may limit the number of marketing template messages a person receives from any business in a given period of time, starting with delivering fewer marketing conversations to those users who are less likely to engage with them. In most WhatsApp markets, this is determined based on a number of factors, including a dynamic view of an individual’s marketing message read rate.
For individuals with United States phone numbers (numbers composed of a +1 dialing code and a US area code), where WhatsApp is growing quickly but at an earlier stage, WhatsApp will not deliver any marketing template messages to focus on building the consumer experience.
WhatsApp has found that per-user marketing template limits maximize message engagement and improve the user experience, measured through improvements in user read rates and sentiment. This limit helps WhatsApp users find business messaging more valuable and feel less like they receive too many business messages.
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, you may send one additional marketing template message. Further marketing template messages can only be sent in an open marketing conversation if the person responds to any message.
Example:
If a marketing template message is not sent due to per-user marketing template limit enforcement, a messages webhook will be triggered with status set to failed and (error) code set to 131049
(for Cloud API) or 1026
(for On-Premises API).
If you do receive this error code and suspect it is due to the limit, avoid immediately resending the template message. Doing so will only result in another error response since the limit may be in effect for differing periods of time. Instead, retry sending the message in increasingly larger time increments until it is delivered.
We will continue to refine our approach, and we appreciate your partnership as we invest in making WhatsApp the best possible experience for your business and your customers.