What it is
Subscribe to whatsapp.echo_message.updated.
You receive this event when YCloud processes a matching outbound echo status for an API-created Agent. Keep the message content from the created event: status updates omit message content and type. Failed updates include source error details when available.
The current contract keeps the event name unchanged and exposes status changes
under whatsappMessage, matching the object used by the corresponding created
event.
Before you begin
- Onboard the Agent through the Public REST API.
- Subscribe an active webhook endpoint in the same account to
whatsapp.echo_message.updated.
- Verify
YCloud-Signature against the raw request body, durably accept each event, and process it idempotently.
Console-created Agents do not emit this customer webhook. Their Inbox synchronization is a separate flow.
How it works
All examples use placeholder identifiers. Route by the outer type and read
whatsappMessage, not whatsappMetaBusinessAgent, whatsappEchoMessage, or data.
Deduplicate repeated deliveries with the outer id. The outer createTime is the
webhook event time; nested updateTime and status-specific times are RFC 3339 source times.
- Match updates to the created event by
id or wamid, scoped to your account and business number.
- The customer phone and BSUID are independent. When the source status supplies both
recipient_id and recipient_user_id, the event includes to together with recipientUserId or parentRecipientUserId.
- If a status item omits those identities and the same callback contains exactly one contact, YCloud can use that contact’s explicit
wa_id and user_id. With zero or multiple contacts, missing identities remain omitted; they are never inferred from one another.
from is included only when the source callback supplies a valid business display phone number. It is not derived from phoneNumberId.- Keep the event history separate from your current message status. A late
sent event can arrive after read; record it without downgrading the current status.
- The late sent example below refers to the read example’s message. The failed example refers to a different message.
- Repeated same-rank unchanged statuses are suppressed during processing. This does not guarantee exactly-once HTTP delivery.
- A status received before its echo record can be retried internally. Do not depend on delivery order.
- Ordinary API-sent message statuses use
whatsapp.message.updated, not this event.
Request
YCloud sends these JSON bodies in HTTP POST requests to your configured webhook URL.
Response
Return a 2xx response after durably accepting each event. Process slow work asynchronously.
Echo message delivered
Request
Correlate with the created event by id or wamid. Updated events omit message content and type.
Response
Explanation
Record the delivered transition and retain the message content received in the created event.
Echo message read
Request
Correlate with the created event by id or wamid. Updated events omit message content and type.
Response
Explanation
Record the read transition using updateTime and readTime as source event times.
Late sent status after read
Request
A lower-ranked source status can arrive after read. Record the event without downgrading your current message status.
Response
Explanation
Keep this event in the delivery history, but do not downgrade a later current status such as read.
Failed echo message
Request
This is a separate failed message, not a transition from read. Failed updates include source error details when available.
Response
Explanation
Use errorCode and errorMessage for diagnostics when the source callback supplies them.
