> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp echo message updated

> Handle delivered, read, late sent, and failed echo message status events.

## 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

1. Onboard the Agent through the [Public REST API](/en/api-reference/meta-business-agents/onboard).
2. Subscribe an active webhook endpoint in the same account to `whatsapp.echo_message.updated`.
3. Verify `YCloud-Signature` against the raw request body, durably accept each event, and process it idempotently.

<Warning>
  Console-created Agents do not emit this customer webhook. Their Inbox synchronization is a separate flow.
</Warning>

See [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events) for endpoint setup.

## 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`](/en/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples), 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}
```

### Response

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}
```

### Response

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}
```

### Response

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}
```

### Response

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Use `errorCode` and `errorMessage` for diagnostics when the source callback supplies them.

### Related examples

* [WhatsApp echo message created](/en/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [WhatsApp Agent handover updated](/en/api-reference/guides/examples/webhook-examples/whatsapp-meta-business-agent-handover-updated)
* [Echo and Agent handover examples](/en/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [Complete payload catalog](/en/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.