What it is
The WhatsApp Messages API sends template, text, image, video, audio, document, sticker, location, interactive, contact, and reaction messages from a connected WhatsApp business phone number.Before you begin
- Store your YCloud API key in
YCLOUD_API_KEY. - Connect a WhatsApp Business Account and phone number to YCloud.
- Collect the sender phone number in E.164 format and either the recipient phone number, BSUID, or parent BSUID.
- Use an
APPROVEDtemplate for ordinary template sends. - Upload media first when the message references a YCloud media ID.
How it works
Choose the endpoint based on when YCloud should submit the message to the WhatsApp Business API.
Both endpoints return a YCloud message object. The initial response does not
confirm final delivery. Later status changes arrive through
whatsapp.message.updated Webhooks.
Send your first message
Choose an approved template owned by your connected WABA. Replace the sender, recipient, template name, and language with your own values, then send:id and follow its whatsapp.message.updated events. An
accepted response means the request entered processing, not that the customer
received it. Configure both whatsapp.message.updated and
whatsapp.inbound_message.received when you need delivery tracking and replies.
Choose a template or session message
Use an approved template for ordinary business-initiated messages outside the customer service window. Within an open window, use supported free-form message types such as text, media, or interactive replies. Check customer service window rules at send time. A pricing window does not replace messaging eligibility. See WhatsApp pricing for current charges and entry-point conditions.Direct Send for Utility and Authentication content
Direct Send supports business-initiated Utility and Authentication messages without creating message templates first. YCloud also supports conversion of existing Utility templates. Direct Send works with either sending endpoint. ThesendDirectly endpoint
controls synchronous submission; it does not enable Direct Send by itself.
For Authentication, Direct Send accepts text or an explicit interactive OTP
button. An Authentication template cannot be converted into a Direct Send message.
Follow Direct Send best practices
for eligibility, requests, template conversion, limits, and account events.
Choose the best send time
Match the send time to the message purpose and the recipient’s local time.- Send OTPs and other time-sensitive messages immediately. Use
POST /whatsapp/messages/sendDirectlywhen your workflow needs the submission result before continuing. - Send transactional updates when the related event occurs, such as a payment, shipment, or appointment change.
- Schedule marketing messages for reasonable hours in the recipient’s time zone. Use your own delivery, read, and conversion data to test different time slots for each audience instead of assuming one universal best hour.
- Start a scheduled campaign with a small recipient group. Check delivery, response, and opt-out results before sending to the rest of the audience.
- Avoid repeated sends when a message is delayed. Store
externalIdand processwhatsapp.message.updatedWebhooks before deciding whether to retry.
Request
For Max Price marketing templates, either sending endpoint acceptsbidSpec.per_message_bid_multiplier. Omit the entire bidSpec object to use a multiplier of 1. See the Max Price integration guide for country multipliers, bid limits, and final-charge webhooks.
Choose either endpoint above, then use the request body that matches the message
type. The from value is your connected WhatsApp business phone number. Address
the recipient with to in E.164 format or with recipient set to a BSUID or
parent BSUID.
Common request fields
Provide at least one of
to or recipient. If you include both, YCloud uses
to and ignores recipient.
One-tap, zero-tap, and copy code Authentication templates require a phone
number. Explicit Direct Send OTP also requires a phone number: use
to, not
recipient alone.Explicit authentication Direct Send for OTP
Meta is rolling out Authentication Direct Send in alpha. The sender WABA needs
access to interactive Authentication OTP Direct Send; a successful text
Authentication Direct Send request does not establish access to OTP buttons.
POST /v2/whatsapp/messages/sendDirectly for
synchronous submission or POST /v2/whatsapp/messages for queued submission.
Set type to interactive, category to
authentication, interactive.type to button, and provide exactly one button
with type: "otp". Set interactive.action.buttons[0].otp.code to a string of
4–10 ASCII letters or digits. Include the same code as a standalone value in
interactive.body.text.
On iOS 26 and later, copy code and one-tap messages can provide keyboard
suggestions for numeric codes of 4–8 digits. WhatsApp notifications and security
code autofill must be enabled on the recipient’s device. This does not require
additional iOS app integration; zero-tap remains Android-only. See
Meta’s OTP experiences.
Copy code:
zero_tap_terms_accepted to true on every zero-tap request to confirm the
Meta zero-tap terms
on behalf of your business. Omit that field for one-tap and copy code. For
copy code, also omit supported_apps and autofill_text.
Optional button text and autofill_text are limited to 25 characters and must
not be empty or contain variables, line breaks, formatting, URLs, or emoji.
code_expiration_minutes specifies the code expiration time, from 1–90 minutes
(Meta defaults to 10). Your application must still verify the code and enforce
its expiry. The separate ttlSeconds field controls message delivery lifetime:
Authentication Direct Send accepts 30–900 seconds and defaults to 600 seconds.
See Direct Send TTL limits.
Check whatsapp.message.updated for delivery status and verify autofill on an
eligible device. A delivered message alone does not confirm that an autofill
handshake succeeded.
Request examples
Template message
Template message
Text message
Text message
Image message
Image message
Video message
Video message
Audio message
Audio message
Document message
Document message
Sticker message
Sticker message
Location message
Location message
Interactive message
Interactive message
Contacts message
Contacts message
Reaction message
Reaction message
Add template variables
Match the template name, language, and parameter order to your approved template. For a body with customer name and order-reference parameters, send:Reply to a specific message
Setcontext.message_id to the original WhatsApp message ID (wamid) to create
a quoted reply. Continue to check that the customer service window is open.
Apply unsubscribe and block filters
ForPOST /whatsapp/messages, set filterUnsubscribed: true and
filterBlocked: true when you need to apply your YCloud suppression lists.
Both default to false and do not apply to sendDirectly.
Inspect whatsappMessage.errorCode in status webhooks for
RECIPIENT_UNSUBSCRIBED or RECIPIENT_IN_BLOCK_LIST. Do not expect a separate
filtered status. Enforce suppression in your application before using
sendDirectly.
Use externalId to associate messages with an order or another internal record.
It is a correlation field, not a server-side idempotency key.
Response
A successful response returns the YCloud message object. An initialstatus: accepted means YCloud accepted the send request. It does not mean the
message has been sent by Meta or delivered to the WhatsApp user.
Example response
Response fields
Delivery status
Subscribe towhatsapp.message.updated Webhooks to receive later status changes
such as sent, failed, delivered, or read.
Use GET /whatsapp/messages/{id} when you need to retrieve a message directly.
Limits and troubleshooting
- Ordinary template sends require an
APPROVEDtemplate;ARCHIVEDtemplates cannot be sent as ordinary template messages. - Do not retry an accepted request without an idempotency strategy. A repeated request can send a duplicate message.
- Use the YCloud
id,wamid,externalId, and Webhook status when investigating delivery. - Inspect
whatsappApiErrorwhen a direct request reaches Meta and Meta rejects it.
Direct Send best practices
Send utility content, convert templates, and monitor category and restriction events.
Production best practices
Design status synchronization, bounded retries, consent checks, media reuse,
and throughput controls for a production integration.
Use business-scoped user IDs
Send messages and calls by BSUID, request phone numbers, manage Meta contact
book entries, and process BSUID webhook fields.

