voice.message.updated

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.

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.

{
  "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.

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. 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 format.
`verificationCode`	string	No	The verification code to be sent, 4 to 6 digits.
`language`	string	No	ISO 639 Language Code.
`regionCode`	string	No	ISO 3166-1 alpha-2 country code.
`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.
`status`	string	No	Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`. `accepted`: The messaging request is accepted by our system. `failed`: The message failed to be sent from our system. `sent`: The message has been sent from our system. `delivered`: Our system has received a delivery receipt indicating that message is delivered. `undelivered`: Our system has received a delivery receipt indicating that message is not delivered.
`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. 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. 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. Note: We recommend configuring Webhook Endpoints instead.
`bizType`	string	No	This can be either empty or one of `voice`, or `verify`. Defaults to `voice`. `voice`: Indicates that the message is sent via the Voice product. `verify`: Indicates that the message is sent via Verify product.
`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.

{
  "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/1.1 200 OK

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

voice.message.updated

Triggers

Syntax

Parameters

Event envelope

Event payload

voice

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​voice

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

voice

Example