voice.message.updated

Use voice.message.updated para processar este evento no endpoint do seu webhook.

Gatilhos

Ocorre quando o status de uma mensagem de voz é atualizado e o status muda para delivered ou undelivered. Inscreva-se em voice.message.updated quando você configurar o endpoint do seu webhook.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de Webhook configurada. A estrutura a seguir mostra uma variante do payload. Os valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variantes são descritos abaixo.

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

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte a validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`type`	string	Sim	Sempre `voice.message.updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (data-hora)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`voice`	objeto	Não	Payload de `voice` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objetos, Obrigatório se aplica quando o objeto pai estiver presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

voice

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do objeto. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`to`	string	Sim	O número de telefone do destinatário no formato E.164.
`verificationCode`	string	Não	O código de verificação a ser enviado, de 4 a 6 dígitos.
`language`	string	Não	Código de idioma ISO 639.
`regionCode`	string	Não	Código de país ISO 3166-1 alfa-2.
`totalSegments`	integer (int32)	Não	Número de segmentos da mensagem. É sempre 1 para chamadas de voz. Mínimo: `1`.
`totalPrice`	number (double)	Não	Preço total desta mensagem.
`currency`	string	Não	Moeda do preço. Código de moeda ISO 4217.
`status`	string	Não	Status de entrega. Um de `accepted`, `sent`, `delivered`, `undelivered` ou `failed`. `accepted`: a solicitação de envio de mensagem foi aceita pelo nosso sistema. `failed`: falha ao enviar a mensagem pelo nosso sistema. `sent`: a mensagem foi enviada pelo nosso sistema. `delivered`: nosso sistema recebeu um comprovante de entrega indicando que a mensagem foi entregue. `undelivered`: nosso sistema recebeu um comprovante de entrega indicando que a mensagem não foi entregue.
`errorCode`	string	Não	Código de erro quando a mensagem não puder ser entregue.
`createTime`	string (data-hora)	Não	O momento em que esta mensagem foi criada, formatado em RFC 3339. Ex.: `2022-03-01T12:00:00.000Z`.
`updateTime`	string (date-time)	Não	O horário em que o relatório de entrega desta mensagem foi atualizado, formatado em RFC 3339. Por exemplo, `2022-03-01T12:00:00.000Z`.
`externalId`	string	Não	Uma string exclusiva (recomendada) para fazer referência ao objeto. Pode ser um número de pedido ou similar, e pode ser usada para reconciliar o objeto com seus sistemas internos.
`callbackUrl`	string	Não	URL do relatório de entrega. Você pode fornecer uma URL e enviaremos o relatório de status atualizado para o seu servidor a tempo. Por exemplo, https://httpbin.org/anything?tag=api. Observação: recomendamos configurar Webhook Endpoints como alternativa.
`bizType`	string	Não	Pode estar vazio ou ser um dos seguintes valores: `voice` ou `verify`. O padrão é `voice`. `voice`: indica que a mensagem foi enviada por meio do produto Voice. `verify`: indica que a mensagem foi enviada por meio do produto Verify.
`verificationId`	string	Não	O ID de verificação. Incluído apenas quando `bizType` for `verify`.

Exemplo

O JSON a seguir é o corpo entregue ao seu destinatário. IDs, números de telefone e outros valores de conta são 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"
  }
}

Depois de verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Para orientações passo a passo sobre cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

voice.message.updated

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

voice

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​voice

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

voice

Exemplo