What is Direct Send
Direct Send lets you send business-initiated Utility and Authentication messages without creating templates first. Submit the complete content and acategory 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.
Send messages
SetYCLOUD_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.- Text
- Media header
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 into; 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.
- copy_code
- one_tap
- zero_tap
Use
copy_code for a copy code button. Omit supported_apps, autofill_text, and zero_tap_terms_accepted.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)
SetttlSeconds 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 settemplateName to name a Utility Direct Send template. To enable Direct Send, also set category: "utility" or useDirectSend: true.
Request with a custom template name
Request with a custom template name
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 throughwhatsapp.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:
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:- Open WhatsApp Manager → Templates in the YCloud console.
- Select the WABA used to send the message.
- Set Creator → Auto generated. Use Category → Utility to narrow the list to Utility templates.
- Check the template’s name, category, language, status, and last updated time. Click its name or Insights to open its preview and performance details.

Set Creator to Auto generated. This test WABA has no matching generated templates.
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. SetuseDirectSend: 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:
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:
- Request value: If you provide
ttlSeconds, it takes precedence and must be 30–43,200 seconds. - 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
ttlSecondsto override it. - Default value: If the template TTL is unset, non-positive, or above 43,200 seconds, use Meta’s default TTL.
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:
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 error132015. 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:
Account-restriction webhook example
Account-restriction webhook example
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 andX-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.
Direct Send FAQ
Do I need a template name before sending?
Do I need a template name before sending?
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.Why does Direct Send still generate templates?
Why does Direct Send still generate templates?
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.
Can I send outside the 24-hour customer service window?
Can I send outside the 24-hour customer service window?
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.
Why can a message succeed before its generated template appears?
Why can a message succeed before its generated template appears?
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.
How are unused generated templates cleaned up?
How are unused generated templates cleaned up?
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.
Does setting utility guarantee that Meta will accept the category?
Does setting utility guarantee that Meta will accept the category?
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.
How is Direct Send billed?
How is Direct Send billed?
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.

