Sending WhatsApp message with Direct Send
Send a Utility message through the Messaging API without creating a message template and without waiting for Meta to approve it. You send a regular message with the directSend attribute, and Meta takes care of the template that WhatsApp requires to deliver the message.
BETA: RESTRICTED ACCESSDirect Send is in beta, and it is not open to every account. Meta grants access only to an allowlist of WhatsApp Business Accounts (WABAs). If you send a message with Direct Send before Meta enables it for your WABA, the message fails.
This page explains how to send a message with Direct Send through the Messaging API. For the complete description of the feature, how Meta manages it, its benefits, and how to view the templates that Meta generates, see WhatsApp Direct Send.
Before you begin
- Check that your WABA has access to Direct Send. Meta grants the access at the WABA level. You are responsible for verifying in your Meta Business Manager or in WhatsApp Manager that your WABA already has access. For more information, see Enable access.
- Send only Utility content. You are fully responsible for the content you send with Direct Send and for its correct classification as Utility. See Your responsibility.
- Do not create a message template. You send the content of the message in the request, not the name of a template.
NOTEIf your WABA does not have access to Direct Send yet, continue to send your Utility messages with message templates as usual.
The directSend attribute
To send a message with Direct Send, add the optional directSend attribute to the request object of a regular message.
| Parameter | Type | Required | Description |
|---|---|---|---|
request.directSend | Boolean | No | Set to true to deliver the message with Direct Send. Your WABA must have Direct Send enabled by Meta. The default value is false. |
Keep the following rules in mind:
- Send
directSendonly when you want to use Direct Send. If you do not want to use it, do not include the attribute in your request. directSendapplies only to regular messages. It does not apply to message templates.- If you send
directSendtogether with a message template, the template prevails. The platform processes the message as a standard message template send and ignoresdirectSend.
The following table summarizes what happens in each case:
| What you send | directSend | Result |
|---|---|---|
| Regular message (text or interactive) | true | The platform sends the message with Direct Send. Your WABA must have access. |
| Regular message (text or interactive) | false or not included | The platform sends a regular message. The 24-hour session window applies. |
Message template (templateName or templateId) | true | The template prevails. The platform sends a standard message template and ignores directSend. |
Message template (templateName or templateId) | false or not included | The platform sends a standard message template. |
Supported message types
Direct Send supports the following message types:
| Message type | What you can include | interactive.type |
|---|---|---|
| Text | A simple text message. | Not applicable |
| Interactive message with reply buttons | Text or multimedia header (image, video, or document), footer, and reply buttons. | button |
| Interactive message with a CTA URL button | Text or multimedia header (image, video, or document), footer, and a URL button. | cta_url |
Direct Send does not support any other message type at this time, for example interactive lists, contacts, location, or media messages that are not part of an interactive message.
NOTEThese are the message types supported at this time. Meta can enable additional message types for Direct Send in the future.
Send a text message with Direct Send
HTTP Request: POST /notification
Use a text message to send a short Utility update, such as a shipping notification. This example sends a text message with Direct Send:
{
"channel": "WHATSAPP",
"request": {
"from": "1000000001",
"to": "+1000000002",
"type": "text",
"message": "Your order #45890 has shipped and will arrive tomorrow.",
"directSend": true
},
"callbacks": [
"http://www.mycallback.com?id=123"
]
}Send an interactive message with reply buttons with Direct Send
HTTP Request: POST /notification
Use an interactive message with reply buttons when the user needs to answer with one tap, for example to confirm an appointment. This example sends an interactive message with a text header, a footer, and three reply buttons:
{
"channel": "WHATSAPP",
"request": {
"from": "1000000001",
"to": "+1000000002",
"directSend": true,
"type": "interactive",
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "Appointment reminder"
},
"body": {
"text": "Your appointment is scheduled for Friday at 3:00 PM. Do you want to confirm it?"
},
"footer": {
"text": "Select an option below"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "0",
"title": "Confirm"
}
},
{
"type": "reply",
"reply": {
"id": "1",
"title": "Reschedule"
}
},
{
"type": "reply",
"reply": {
"id": "2",
"title": "Cancel"
}
}
]
}
}
},
"callbacks": [
"http://www.mycallback.com?id=123"
]
}The following limits apply to this type of message:
- Header text: up to 60 characters.
- Body text: up to 1,024 characters.
- Footer text: up to 60 characters.
- Reply buttons: up to 3 buttons. Each button has a unique
idand atitleof up to 20 characters.
To use a multimedia header instead of a text header, set header.type to image, video, or document, and include the link to the file. For more information, see Sending WhatsApp interactive message session.
Direct Send also supports interactive messages with a CTA URL button, in which interactive.type is set to cta_url. For the structure of the interactive object in this type of message, see Interactive message with a URL button.
Request parameters
All the parameters of a regular message work the same way with Direct Send. The following table describes the parameters used in the examples on this page. For the complete description of each parameter, see Sending WhatsApp text message session and Sending WhatsApp interactive message session.
| Parameter | Required | Description |
|---|---|---|
channel | Yes | Delivery channel of the notification message. Set it to "WHATSAPP". |
request.from | Yes | Phone number of the sender. It is the phone number provided during the WABA setup. It only accepts numeric characters. Do not include the "+" sign. |
request.to | Conditional | Destination phone number. Use the E.164 format: the "+" sign and the country code. Required if you do not send recipient. |
request.directSend | No | Set to true to use Direct Send. |
request.type | Yes | Type of message. Set it to text for a text message, or to interactive for an interactive message. |
request.message | Yes, for text messages | Text of the message. |
request.interactive | Yes, for interactive messages | Object with the content of the interactive message: type of interaction, header, body, footer, and buttons. |
callbacks | No | One or more webhook URLs that receive the status of the message. See WhatsApp status. |
Response
If the platform accepts your request, the response is an HTTP 202 status code with the meta object:
{
"meta": {
"timestamp": 1642531254980,
"transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
"explain": "Send Notification"
}
}This response confirms that the platform accepted the request. It does not confirm that the message was delivered. To follow the delivery status, use the callbacks parameter. For the list of statuses, see WhatsApp status.
Your responsibility
IMPORTANTYou are fully responsible for the content you send with Direct Send and for its correct classification as Utility.
Direct Send is only for Utility messages. A Utility message is transactional or informational, it is strictly non-promotional, and it provides an update that the user expects or requested. For example, order confirmations, shipping updates, appointment reminders, or payment alerts.
Do not use Direct Send to send promotional content, such as offers, discounts, product announcements, newsletters, or invitations. This content is Marketing. To send Marketing content, use a Marketing message template.
If Meta detects marketing content sent with Direct Send, Meta can sanction the use and suspend your access to Direct Send or to your WABA.
Message logs
Direct Send messages do not have their own analytics. However, the exported Messaging logs report includes the SendMode column, which shows the way the platform sent each message: STANDARD, TEMPLATE, or DIRECT_SEND. You can use it to run your own analysis. For more information, see Message logs.
Updated 1 day ago
