> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/messaging/direct-send.md). # Direct Send Send business-initiated Utility messages without creating a template first. ## What is Direct Send Direct Send lets you send business-initiated **Utility** messages without creating a template first. You send the content to the normal messages endpoint, add `"category": "utility"`, and Meta creates and manages the matching template for you. Use it when you send transactional updates that change per customer and you don't want to manage dozens of templates: order and shipping updates, appointment reminders, payment confirmations, account alerts. Keep using regular templates for Marketing messages and anything with content Direct Send doesn't support (see [Limits](#limits)). | | Regular template | Direct Send | | ---------------------------------- | ---------------- | ------------------------- | | Create and approve template first | Yes | No | | Where you send | `/messages` | `/messages` (same) | | Extra field | `type: template` | `category: utility` | | Price | Utility rate | Utility rate (same) | | Template shows in WhatsApp Manager | Yes, yours | Yes, auto-created by Meta | ## Before you start You need: * A WhatsApp number connected to 360dialog on Cloud API, with an API key. * A WABA in good standing (no recent policy violations). * Content that is truly Utility: triggered by something the customer did or asked for, with no promotion in it. ## Send your first message Every Direct Send message is a normal Cloud API message plus `"category": "utility"`. Pick the example closest to what you want to do. ### Notify a customer (plain text) Example: shipping update. ```bash curl -X POST https://waba-v2.360dialog.io/messages \ -H "D360-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "", "type": "text", "text": { "body": "Hi Jane, your order #12345 has shipped and should arrive on March 20." }, "category": "utility" }' ``` ### Ask the customer to confirm (reply buttons) Example: appointment reminder with Confirm / Reschedule. ```json { "messaging_product": "whatsapp", "to": "", "type": "interactive", "interactive": { "type": "button", "body": { "text": "Reminder: your appointment is tomorrow at 10:00." }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } }, { "type": "reply", "reply": { "id": "reschedule", "title": "Reschedule" } } ] } }, "category": "utility" } ``` ### Send the customer to a page (URL button) Example: track your delivery. ```json { "messaging_product": "whatsapp", "to": "", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Your package is out for delivery." }, "action": { "name": "cta_url", "parameters": { "display_text": "Track package", "url": "https://example.com/track/12345" } } }, "category": "utility" } ``` ### Keep your template names (optional) If your systems report by template name, set the name yourself with `direct_send_config.template_name`. Lowercase letters, numbers and underscores; unique in your WABA. Utility only, and access-restricted by Meta. ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "", "type": "text", "text": { "body": "Hi Jane, your order #12345 has been shipped and is expected to arrive on March 20." }, "category": "utility", "direct_send_config": { "template_name": "order_shipment_update" } } ``` More detail: [Business-named templates (Meta)](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/business-named-templates) ### Drop messages that arrive too late (TTL) For time-sensitive messages, set a time-to-live so WhatsApp drops the message if it can't be delivered in time. See [Meta: Direct Send](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send) for the field and allowed range. ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "", "type": "text", "text": { "body": "" }, "category": "utility", "ttl_seconds": 600 } ``` ## What happens after you send 1. Meta checks whether your content matches a template you already have. If yes, it uses it. 2. If not, the message still goes out right away, and Meta creates a new template in the background (personal data removed, language detected). 3. Auto-created templates appear in the Templates API and WhatsApp Manager with names starting `auto_generated_` and `source=AUTO_GENERATED`. You can't edit them. 4. Status webhooks work as usual and include a `template_id`, so you can see which template each message was billed against. The `category` field controls the behaviour: | `category` | What happens | | ------------- | --------------------------------------------------------------------------------- | | `utility` | Sent as a business-initiated Utility message, charged at Utility rates | | omitted | Normal Cloud API behaviour: only works inside the 24-hour customer service window | | anything else | Rejected with an error | ## Limits | You want to send | Supported | | ------------------------------------------------------ | ------------------------------------ | | Text | Yes | | Reply buttons | Yes | | URL (call-to-action) buttons | Yes, max 2 | | Reply + URL buttons mixed | Yes, max 10 buttons total, max 2 URL | | Image, video or document header | Access-restricted by Meta | | Marketing content | No, use a Marketing template | | Audio, sticker, location, contacts, address, reactions | No | | Link previews (`preview_url`) | No | Text limits: body 1,024 characters, header and footer 60, button label 20. All Cloud API languages are supported. Throughput follows your number's normal Cloud API limits. Full list: [Supported features and limits (Meta)](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/supported-features-and-limits) ### Stay Utility, or lose access Meta checks Direct Send content. If it looks like Marketing, you get a notice by email and webhook first. Repeated misuse leads to a 7-day suspension, then a 30-day ban, then permanent loss of Direct Send. Fix flagged content fast; if you think a flag is wrong, appeal to Meta. Rule of thumb: if the message would still make sense with every promotional word removed, it's Utility. See more about the [Integrity and content guidelines](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/integrity-and-content-guidelines) ## Troubleshooting | Problem | Likely cause | Fix | | ---------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- | | Request rejected right away | Unsupported `category` value, or a message type Direct Send doesn't support | Use `"category": "utility"` and a type from [Limits](#limits) | | Message only delivered to people who wrote to you recently | `category` missing, so it was sent as a service message | Add `"category": "utility"` | | Content notice by email or webhook | Meta classified the content as Marketing | Remove promotional wording, or send it as a Marketing template | | Message never arrived | TTL expired before delivery | Increase the TTL or drop it for non-urgent messages | | Can't edit a template in WhatsApp Manager | It's an `auto_generated_` template managed by Meta | Change the content you send instead | Error codes: [Cloud API error codes (Meta)](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes) ## Changes since the beta For beta participants. Your existing integration keeps working; these are the differences. | | Beta | Now | | ----------------------- | -------------------------------------- | ------------------------------------------------------------ | | Status (Utility) | Beta, enrollment form | Generally available | | Buttons | Up to 3 reply buttons, or 1 URL button | Up to 10 buttons, max 2 URL, mixing allowed | | Headers | Text only | Text; media headers access-restricted | | Languages | Excluded zh, ja, ko, th, lo, ml, ar | All Cloud API languages | | Template names | Auto-generated only | Optionally set your own (`direct_send_config.template_name`) | | Webhooks | Standard | Status webhooks include `template_id` | | Authentication category | Not available | Access-restricted by Meta | The beta enrollment form is closed. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.360dialog.com/docs/messaging/direct-send.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.