voice.message.updated

Usa voice.message.updated para gestionar este evento en tu endpoint de webhook.

Desencadenadores

Se produce cuando se actualiza el estado de un mensaje de voz y este cambia a delivered o undelivered. Suscríbete a voice.message.updated cuando configures tu endpoint de webhook.

Sintaxis

YCloud envía una solicitud HTTP POST a la URL de webhook que hayas configurado. La siguiente estructura muestra una variante de la carga útil. Los valores entre corchetes angulares son marcadores de posición; sus tipos se indican en Parámetros. A continuación se describen los campos opcionales y otras variantes.

{
  "id": "<ID>",
  "type": "voice.message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "voice": {
    "id": "<ID>",
    "to": "<TO>",
    "status": "<STATUS>",
    "externalId": "<EXTERNAL_ID>"
  }
}

Parámetros

Valida el encabezado HTTP YCloud-Signature antes de procesar el cuerpo JSON. Consulta validación de firma.

Envoltorio del evento

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único del evento. Longitud mínima: `6`. Longitud máxima: `128`.
`type`	string	Sí	Siempre `voice.message.updated`.
`apiVersion`	string	Sí	La versión de la API utilizada para procesar este evento.
`createTime`	string (date-time)	Sí	Fecha y hora en que se creó este evento, con formato RFC 3339. P. ej., `2022-06-01T12:00:00.000Z`.

Carga útil del evento

Parámetro	Tipo	Obligatorio	Descripción
`voice`	object	No	Carga útil específica de `voice` para el evento.

Los cuatro campos comunes del envoltorio son obligatorios. Los campos de la carga útil dependen de la variante del evento. En cada tabla de objetos, Obligatorio se aplica cuando su objeto superior está presente. Los campos opcionales pueden omitirse; un ejemplo no hace que un campo sea obligatorio.

voice

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único para el objeto. Longitud mínima: `6`. Longitud máxima: `128`.
`to`	string	Sí	El número de teléfono del destinatario en formato E.164.
`verificationCode`	string	No	El código de verificación que se enviará, de 4 a 6 dígitos.
`language`	string	No	Código de idioma ISO 639.
`regionCode`	string	No	Código de país ISO 3166-1 alfa-2.
`totalSegments`	integer (int32)	No	Número de segmentos del mensaje. Siempre es 1 para llamadas de voz. Mínimo: `1`.
`totalPrice`	number (double)	No	Precio total de este mensaje.
`currency`	string	No	Moneda del precio. Código de moneda ISO 4217.
`status`	string	No	Estado de entrega. Uno de los siguientes: `accepted`, `sent`, `delivered`, `undelivered` o `failed`. `accepted`: la solicitud de mensajería ha sido aceptada por nuestro sistema. `failed`: no se pudo enviar el mensaje desde nuestro sistema. `sent`: el mensaje ha sido enviado desde nuestro sistema. `delivered`: nuestro sistema ha recibido un comprobante de entrega que indica que el mensaje se entregó. `undelivered`: nuestro sistema ha recibido un comprobante de entrega que indica que el mensaje no se entregó.
`errorCode`	string	No	Código de error cuando el mensaje no se puede entregar.
`createTime`	string (date-time)	No	Fecha y hora en que se creó este mensaje, con formato RFC 3339. P. ej., `2022-03-01T12:00:00.000Z`.
`updateTime`	string (date-time)	No	La fecha y hora en que se actualizó el informe de entrega de este mensaje, con formato RFC 3339. Por ejemplo, `2022-03-01T12:00:00.000Z`.
`externalId`	string	No	Una cadena única (recomendada) para hacer referencia al objeto. Puede ser un número de pedido o similar, y puede usarse para conciliar el objeto con tus sistemas internos.
`callbackUrl`	string	No	URL del informe de entrega. Puedes proporcionar una URL y enviaremos a tiempo el informe de estado actualizado a tu servidor. Por ejemplo, https://httpbin.org/anything?tag=api. Nota: Recomendamos configurar Webhook Endpoints en su lugar.
`bizType`	string	No	Puede estar vacío o ser uno de `voice` o `verify`. El valor predeterminado es `voice`. `voice`: indica que el mensaje se envía a través del producto Voice. `verify`: indica que el mensaje se envía a través del producto Verify.
`verificationId`	string	No	El ID de verificación. Solo se incluye cuando `bizType` es `verify`.

Ejemplo

El siguiente JSON es el cuerpo entregado a tu receptor. Los ID, números de teléfono y otros valores de cuenta son ilustrativos.

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

Tras verificar la firma y aceptar de forma duradera el evento, devuelve una respuesta 2xx. Procesa las tareas lentas de forma asíncrona.

HTTP/1.1 200 OK

Para consultar tutoriales paso a paso de situaciones de uso, consulta los ejemplos anotados.

Primeros pasos

Guías

Endpoints

Webhook reference

voice.message.updated

Desencadenadores

Sintaxis

Parámetros

Envoltorio del evento

Carga útil del evento

voice

Ejemplo

​Desencadenadores

​Sintaxis

​Parámetros

​Envoltorio del evento

​Carga útil del evento

​voice

​Ejemplo

Desencadenadores

Sintaxis

Parámetros

Envoltorio del evento

Carga útil del evento

voice

Ejemplo