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

# voice.message.updated

> Occurs when a voice message status is updated, and the status changes to `delivered` or `undelivered`.

Use `voice.message.updated` to handle this event at your webhook endpoint.

## Triggers

Occurs when a voice message status is updated, and the status changes to `delivered` or `undelivered`.

Subscribe to `voice.message.updated` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Syntax

YCloud sends an HTTP `POST` request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under **Parameters**. Optional fields and other variants are described below.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "voice.message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "voice": {
    "id": "<ID>",
    "to": "<TO>",
    "status": "<STATUS>",
    "externalId": "<EXTERNAL_ID>"
  }
}
```

## Parameters

Validate the `YCloud-Signature` HTTP header before you process the JSON body. See [signature validation](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Event envelope

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique ID for the event. Minimum length: `6`. Maximum length: `128`. |
| `type` | string | Yes | Always `voice.message.updated`. |
| `apiVersion` | string | Yes | The API version used to render this event. |
| `createTime` | string (date-time) | Yes | The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. |

### Event payload

| Parameter | Type | Required | Description |
| - | - | - | - |
| `voice` | object | No | Event-specific `voice` payload. |

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, **Required** applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

#### voice

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique ID for the object.Minimum length: `6`. Maximum length: `128`. |
| `to` | string | Yes | The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. |
| `verificationCode` | string | No | The verification code to be sent, 4 to 6 digits. |
| `language` | string | No | [ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). |
| `regionCode` | string | No | [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). |
| `totalSegments` | integer (int32) | No | Number of message segments. It's always 1 for voice calls.Minimum: `1`. |
| `totalPrice` | number (double) | No | Total price of this message. |
| `currency` | string | No | Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). |
| `status` | string | No | Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`.<ul><li>`accepted`: The messaging request is accepted by our system.</li><li>`failed`: The message failed to be sent from our system.</li><li>`sent`: The message has been sent from our system.</li><li>`delivered`: Our system has received a delivery receipt indicating that message is delivered.</li><li>`undelivered`: Our system has received a delivery receipt indicating that message is not delivered.</li></ul> |
| `errorCode` | string | No | Error code when the message is undeliverable. |
| `createTime` | string (date-time) | No | The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. |
| `updateTime` | string (date-time) | No | The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. |
| `externalId` | string | No | A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems. |
| `callbackUrl` | string | No | Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., [https://httpbin.org/anything?tag=api](https://httpbin.org/anything?tag=api). Note: We recommend configuring Webhook Endpoints instead. |
| `bizType` | string | No | This can be either empty or one of `voice`, or `verify`. Defaults to `voice`.<ul><li>`voice`: Indicates that the message is sent via the **Voice** product.</li><li>`verify`: Indicates that the message is sent via **Verify** product.</li></ul> |
| `verificationId` | string | No | The verification ID. Included only when `bizType` is `verify`. |

## Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+12025550123",
    "status": "delivered",
    "externalId": "verification_123"
  }
}
```

After verifying the signature and durably accepting the event, return a `2xx` response. Process slow work asynchronously.

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

For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples).


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