Skip to main content

What is Direct Send

Direct Send lets you send business-initiated Utility and Authentication messages without creating templates first. Submit the complete content and a category through the YCloud WhatsApp Messages API; Meta matches or generates the template. Use Utility for messages tied to a customer’s action or request, such as order updates and appointment reminders. Use Authentication for identity verification with one-time passwords (OTPs). Marketing messages use regular templates. Before you start
  • Get a YCloud API key and connect a WhatsApp business phone number.
  • Check that your WhatsApp Business Account (WABA) has Direct Send access for the selected category. See eligibility requirements.
  • Obtain the customer’s permission and follow Meta’s category guidelines.
For existing integrations, see changes and compatibility.

Send messages

Set YCLOUD_API_KEY to your API key and replace the phone number placeholders with E.164 numbers. The example below uses synchronous submission; you can also submit asynchronously.

Utility message examples

Each tab contains a complete cURL request. Replace the API key, phone numbers, and example URLs before sending.
Synchronous and asynchronous APIs Both endpoints accept the same Direct Send request body. Authenticate with the X-API-Key header and set Content-Type: application/json. The sendDirectly endpoint controls submission timing; it does not enable Direct Send by itself. Track the delivery result through message status and callbacks. Request parameters Omitting both category and useDirectSend sends an ordinary free-form message, which requires an open 24-hour customer service window.

Authentication OTP examples

Choose one of the three OTP experiences below. Each example is a complete YCloud request body for either endpoint in Synchronous and asynchronous APIs. Your WABA must have access to Authentication Direct Send OTP. Use a phone number in to; Authentication does not support a business-scoped user ID (BSUID) recipient. Replace 123456 in both otp.code and interactive.body.text. Use 4–10 ASCII letters or digits and include the code as a standalone value in the body.
Use copy_code for a copy code button. Omit supported_apps, autofill_text, and zero_tap_terms_accepted.
For one-tap and zero-tap, supported_apps accepts 1–5 Android apps with unique package names. Each signature_hash must contain exactly 11 characters. The sample package name and hash above are examples; they will not enable autofill for your app. See the app setup and complete parameter rules. code_expiration_minutes describes the code expiry in minutes; your application must verify the code and enforce its expiry. ttlSeconds controls how long WhatsApp attempts delivery. Authentication Direct Send accepts 30–900 seconds and defaults to 600 seconds. On iOS 26 and later, copy code and one-tap messages can provide keyboard suggestions for 4–8 digit numeric codes when WhatsApp notifications and security code autofill are enabled. Zero-tap is Android-only. See Meta’s OTP experiences. Text-only Authentication Direct Send also remains supported. A delivered message confirms delivery, not that the Android autofill handshake succeeded.

Delivery lifetime (TTL)

Set ttlSeconds to stop delivery attempts after the message is no longer useful. For example, ttlSeconds: 1800 gives a Utility update a 30-minute delivery lifetime. Authentication has a 15-minute maximum. TTL does not delete delivered messages or replace your application’s OTP expiry checks. Meta TTL reference.

Custom template names

Optionally set templateName to name a Utility Direct Send template. To enable Direct Send, also set category: "utility" or useDirectSend: true.
YCloud validates templateName before accepting a send request. If the name is invalid or already used by a regular template, update it and try again. Use 1 to 512 lowercase letters, digits, or underscores. YCloud rejects uppercase letters, spaces, and other characters. The same WABA cannot use a name that belongs to an existing regular WhatsApp message template, including a rejected template. Deleted templates do not reserve the name, and you can reuse a name that Meta previously generated for Direct Send. If a regular template already uses the name, the API returns HTTP 400 with target templateName and message A template with the same name already exists. Monitor message status even after YCloud accepts the request. For name conflicts or template creation failures, see common errors. Meta’s retry rules are described in its business-named template reference. templateName is not supported for Authentication Direct Send. YCloud ignores it for messages that do not use Direct Send.

Message status and callbacks

Delivery status YCloud reports delivery through whatsapp.message.updated. Save the returned YCloud id and WhatsApp message ID (wamid) to correlate updates. accepted means YCloud accepted the request; sent means it is in transit within WhatsApp. Use delivered, read, or failed to track the subsequent outcome. You can also query GET /v2/whatsapp/messages/{id} using the YCloud id. Set externalId to your own reference when you need to reconcile a message with your system. It does not prevent duplicate sends. If a request times out, check the original message before retrying. Configure status webhooks. Reply-button callbacks When a customer taps a Direct Send reply button, the inbound message has type: button. Read the customer’s selection from button.payload and button.text. Relevant fields in a YCloud inbound-message event:
Use button.payload to identify the action and context.id to correlate the reply with the original message’s wamid. Do not read this response from interactive.button_reply, which is the ordinary free-form reply-button format.

YCloud extensions

YCloud provides template viewing and analytics in the console, plus an API extension that converts existing Utility templates into Direct Send messages. Meta handles template matching and generation.

View generated templates

Generated templates appear in YCloud after synchronization, which can finish after the message is sent. To find them:
  1. Open WhatsApp Manager → Templates in the YCloud console.
  2. Select the WABA used to send the message.
  3. Set Creator → Auto generated. Use Category → Utility to narrow the list to Utility templates.
  4. Check the template’s name, category, language, status, and last updated time. Click its name or Insights to open its preview and performance details.
Creator filter set to Auto generated in Templates

Set Creator to Auto generated. This test WABA has no matching generated templates.

Automatically assigned names start with auto_generated; custom names match the name you supplied. Use Creator → Auto generated to find both types. See Meta’s generated-template reference. The insight page shows the message preview and available delivery, failure, read, and interaction statistics for the selected period. Use the template’s status and content together when investigating a warning or a paused template. Generated templates cannot be edited or deleted manually. To change a Utility message, update the content in your send request. Meta then matches or generates a template for that content. Meta deletes generated templates that have never been used after 24 hours. Previously used templates can be archived after a period of inactivity.

Convert templates to Direct Send

This is a YCloud extension for existing Utility templates. Set useDirectSend: true; YCloud fills the template parameters and sends the content through Direct Send. template.name selects the existing template to convert. Use templateName to name the template Meta matches or generates for Utility Direct Send. Use a Utility template from your WABA. Set type: "template" and useDirectSend: true, and supply its name, language, and all required parameters. The template must meet the conversion limits below; it does not need APPROVED status. Authentication templates cannot be converted. To send an OTP through Direct Send, use an Authentication request. For this example, use an existing Utility template named order_update with the body Your order {{1}} has been updated. and no header, footer, or buttons. Submit it asynchronously with the following request:
Example response after YCloud accepts the message into the queue. The content is already converted to type: "text":
accepted does not mean the message was delivered. Save the returned id and track whatsapp.message.updated, or query GET /v2/whatsapp/messages/{id}. If YCloud returns WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT, check the template’s header, buttons, and unresolved variables against the limits below. If the WABA cannot use Direct Send, check its eligibility before retrying or send an approved Utility template through the ordinary template workflow. Message lifetime For template conversion, determine the delivery lifetime in this order:
  1. Request value: If you provide ttlSeconds, it takes precedence and must be 30–43,200 seconds.
  2. Template value: Otherwise, use the template TTL when it is 30–43,200 seconds. A positive template TTL below 30 seconds fails validation; provide a valid ttlSeconds to override it.
  3. Default value: If the template TTL is unset, non-positive, or above 43,200 seconds, use Meta’s default TTL.
Conversion limits The following limits apply to YCloud’s conversion of an existing Utility template into Direct Send content: Do not combine CTA URL and quick reply buttons. Other header and button types cannot be converted. Unsupported components or unresolved template variables return HTTP 400 with code WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT. Before converting a template with an image header, confirm that your WABA can use media headers. See supported features and limits and Meta’s media header requirements. Message sample checks (optional) POST /v2/whatsapp/messages/{wabaId}/messageSamples submits one example to Meta and returns the detected category without sending a message to a customer. This YCloud endpoint is optional. Check representative content when introducing a new use case; a sample result does not exempt subsequent messages from Meta’s category and quality checks. Replace WABA_ID with your WABA ID and set YCLOUD_API_KEY to your API key. Use fictional customer details in the sample:
Example response:
Check category before using the content in a Utility Direct Send request. If Meta detects MARKETING or AUTHENTICATION, revise the content or use the appropriate messaging workflow. For a button sample, submit the type and interactive fields from a Utility button example above; omit recipient and sending fields.

Supported features and limits

WABA access Check availability in Meta WhatsApp Manager → Message templates. Business portfolios with a messaging limit of 100,000 or unlimited are generally eligible for Utility; Authentication is in alpha. See Meta’s eligibility requirements. Message formats, languages, and pricing The following limits apply to the message formats used in this guide’s examples. See Meta’s supported message types for platform requirements. All WhatsApp template languages are supported. Standard messaging limits and throughput apply. Pricing follows the corresponding Utility or Authentication category.

Integrity and content guidelines

Utility content must be non-promotional and tied to a customer action, request, or qualifying essential information. Identify the relevant order, appointment, account, or transaction so the customer understands why you are contacting them. Follow Meta’s template category guidelines. Do not add promotions, discounts, or cross-sell offers to a Utility update. Use Authentication for OTPs and Marketing templates for promotional content. Setting category: "utility" does not override Meta’s content assessment. For a new use case, you can run a message sample check before sending. If Meta flags the content, inspect the category notice and follow account status and troubleshooting, including the review process when you disagree with the decision.

Account status and troubleshooting

Warnings, restrictions, and reviews A template can be paused because of low quality. Messages that match it, or are very similar, can then fail with Meta error 132015. Find the affected template in YCloud, inspect its content and status, and address the cause before resuming messages that use it. Repeated category misuse can restrict Direct Send for the entire WABA: Follow the account notice for the active restriction and expiry. A successful review of one template does not automatically lift an account-level restriction. Request a category review If you believe the content was incorrectly flagged, open Meta Business Support Home → WhatsApp account → Direct Send template updates → Available for review. Select the affected templates and choose Request review. Submit the request within 60 days of the notification. Each flagged template can be reviewed once. Track the result as In review, Reversed, or Unchanged. If the review option is unavailable, contact YCloud with the WABA ID, template name or ID, language, and notification details. Status notifications Subscribe to whatsapp.template.correct_category_detection through your webhook endpoint. Compare whatsappTemplate.previousCategory with whatsappTemplate.category; if they are UTILITY and MARKETING, respectively, review the message for Marketing content. See the category-detection webhook example. These notifications concern template categories and do not fire for every message. Sample-check results come from the messageSamples response; delivery results come through whatsapp.message.updated. Relevant fields from a YCloud account-restriction event:
Use the WABA ID to pause the affected workflow. Read violationType for the reason and restrictions[].expiration for its expiry, when supplied. For Direct Send-specific violation types and the warning, restriction, and recovery payloads, see Meta’s Webhook for account restriction. Common errors For synchronous errors, inspect error.whatsappApiError when present. For queued messages, inspect the failure details in whatsapp.message.updated.

Changes and compatibility

You can keep using the same synchronous or asynchronous YCloud endpoint and X-API-Key authentication. Existing Utility text and button requests, and Authentication text requests, remain supported. The table compares existing usage with the options available now.
New capabilities still require the relevant WABA access. Authentication Direct Send remains in alpha. Platform availability and formats follow Meta’s eligibility requirements and supported features.

Direct Send FAQ

No. Send the complete content with category: "utility" or category: "authentication", and Meta matches or generates a template. For Utility messages, you can optionally set templateName to name the Direct Send template.To convert an existing Utility template, provide template.name and useDirectSend: true. These fields serve a different purpose from templateName. Authentication templates cannot be converted to Direct Send.
Meta uses templates for category and quality checks, performance reporting, and troubleshooting. Direct Send handles template matching and generation for you, so you do not have to create a template manually before sending. See how Direct Send works.
Yes. Direct Send supports business-initiated Utility and Authentication messages outside the customer service window, provided your WABA has access to the selected category and the message meets Meta’s consent and content requirements. Ordinary free-form messages still require an open customer service window. See eligibility and sending scope.
Standard Direct Send can use an onboarding template while Meta generates a matching template asynchronously. Synchronization to YCloud can finish after the message is sent. Select the correct WABA and use Creator → Auto generated to find the generated template.During template generation, Meta redacts personal information and detects the language.Business-named Utility templates do not use this onboarding-template fallback.
Meta deletes generated templates that have never been used for sending 24 hours after creation. Previously used templates are periodically archived after a period of inactivity. Meta manages this cleanup; Direct Send templates cannot be manually edited or deleted. See Meta’s Direct Send FAQ.
No. Meta assesses the actual message content. Keep promotional content out of Utility messages. If you believe a category decision is incorrect, follow the review process. A successful send does not exempt future messages from category or quality checks.
Direct Send messages follow the applicable Utility or Authentication pricing rules. Automatic template generation does not make the message free. See WhatsApp pricing for current rates and applicable conditions.