Skip to main content
Sending a request and delivering a message are different events. A successful API response confirms the request’s result at that stage; it does not guarantee that the customer has received or read the message. Use the YCloud message status and any available error details to understand what happened.

​
Outbound message statuses

The YCloud outbound WhatsApp message resource uses these statuses: A typical successful progression is accepted → sent → delivered → read. Do not assume that your application will receive every intermediate update or that updates will arrive in that exact order.

​
Why a successful request is not final delivery

With the queued endpoint, YCloud accepts the request and submits it asynchronously. With the direct endpoint, submission to the WhatsApp Business API happens synchronously. Final delivery is still asynchronous in both cases. For implementation details, see Send a WhatsApp message. If the current status is still accepted or sent, do not repeatedly submit the same content. An additional request can result in a duplicate message.

​
Delivery and read receipts

Delivered means that the message reached the customer’s device. It does not mean that the customer opened the conversation. Read receipts are not available in every situation. For example, the customer’s read-receipt settings can affect whether a read update is reported. The absence of a read update is not proof that the customer ignored the message. For the upstream status definitions, see Meta’s message status webhook reference.

​
Track the same message across systems

When troubleshooting, keep the following information together: Do not include API keys or unnecessary customer information when sharing troubleshooting records. API integrations can receive whatsapp.message.updated webhooks and retrieve the message resource. See WhatsApp messaging best practices for synchronization and retry handling.

​
Investigate a failed message

Start with the returned error, not the status name alone.
  • Template issue: confirm that the template is available and that its language and parameters are correct.
  • Window issue: check whether the message requires an open customer service window.
  • Account or number issue: inspect the affected asset and its current restrictions.
  • Content or media issue: check the requirements of the selected message type.
  • Delivery control: follow the specific error guidance. Immediate repeated retries may not resolve a platform restriction.
A failed message does not establish that a customer blocked your number. Use the actual error details and avoid inferring customer behavior that the platform has not reported. For platform delivery controls, see Quality and delivery controls. For an enforcement notice, see Account restrictions and appeals.

​
Decide whether retrying is safe

A good message record ties one intended business action to its requests and results. Your external reference helps correlation, but do not assume it provides API idempotency unless the endpoint explicitly guarantees that behavior.

​
Example of delayed status updates

Your system receives delivered, then a delayed sent event for the same message. Do not change the customer’s status back to “not delivered.” Store event timestamps and apply a state model that tolerates duplicate and out-of-order updates. Likewise, a missing read event is not a failed message. Separate these measures:
  • Delivered reach: messages with delivery evidence.
  • Read reach: messages with a reported read receipt.
  • Customer response: an actual inbound reply or interaction.
  • Business conversion: a confirmed booking, purchase, or successful verification in the system that owns it.

​
Next steps

​
Frequently asked questions

You cannot conclude that. Read receipts may be unavailable, including when the recipient disables them. Keep delivered and read as separate measurements. Neither a missing read receipt nor a general undeliverable error identifies the customer’s reason or proves blocking.
Not immediately. The platform may already have accepted the request. Check the message identifier, available logs, and later webhook events before issuing another send. Correlate attempts to the same business action and design duplicate protection; an external reference is not automatically an endpoint idempotency guarantee.
A display limitation and a delivery failure are different. Inspect the actual direction, status, message type, and any error. For incoming content, follow the Inbox unsupported-message guide; do not guess the content or count a placeholder as a failed outbound send.