sms.message.updated

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

Gatilhos

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

Sintaxe

A YCloud envia uma requisição HTTP POST para a URL de webhook configurada. O formato 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": "sms.message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "sms": {
    "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. Comprimento mínimo: `6`. Comprimento máximo: `128`.
`type`	string	Sim	Sempre `sms.message.updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	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
`sms`	object	Não	Payload do `sms` 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 objeto, Obrigatório se aplica quando o objeto pai estiver presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

sms

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do objeto. Comprimento mínimo: `6`. Comprimento máximo: `128`.
`to`	string	Sim	O número de telefone do destinatário no formato E.164.
`text`	string	Não	O texto desta mensagem.
`senderId`	string	Não	Sender ID a ser usado.
`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. Consulte Codificação de caracteres de SMS para obter mais informações. 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 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 recibo de entrega indicando que a mensagem foi entregue. `undelivered`: Nosso sistema recebeu um recibo de entrega indicando que a mensagem não foi entregue.
`errorCode`	string	Não	Código de erro quando a mensagem não pode ser entregue.
`createTime`	string (date-time)	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 momento 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 ser vazio ou um destes valores: `sms` ou `verify`. O padrão é `sms`. `sms`: indica que a mensagem é enviada pelo produto SMS. `verify`: indica que a mensagem é enviada pelo produto Verify.
`verificationId`	string	Não	O ID de verificação. Incluído somente quando `bizType` for `verify`.

Exemplo

O JSON a seguir é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são meramente ilustrativos.

{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+12025550123",
    "status": "delivered",
    "externalId": "order_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 conferir tutoriais de cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

sms

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​sms

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

sms

Exemplo