Callbacks de status da Messages API

A Messages API envia callbacks de status à URL do seu webhook para notificá-lo sempre que um evento alterar o status de uma mensagem — por exemplo, quando ela for enviada, entregue ou rejeitada.

Essas chamadas de retorno oferecem uma visão consistente do ciclo de vida das mensagens em todos os canais compatíveis, incluindo SMS, MMS, RCS, e aplicativos: WhatsApp, Viber, e Facebook Messenger.

Sempre que o status de uma mensagem é alterado, a Messages API envia um callback de status para o seu webhook configurado.
Essa chamada de retorno inclui informações importantes, como o UUID da mensagem, o canal, o carimbo de data e hora, o status de entrega e, quando aplicável, o preço e os metadados da rede.

Diferentes canais oferecem suporte a diferentes eventos e níveis de análise. Por exemplo:

Status de retorno de chamada

Callbacks de status de leitura

Para canais OTT, como o WhatsApp e o Viber, a Messages API pode enviar uma read chamada de retorno quando o provedor indicar que o usuário final leu a mensagem em seu dispositivo.

Callbacks de status de envio

Esse status significa que a Messages API encaminhou uma mensagem a um provedor de mensagens.

Retornos de chamada para status de entrega impossível

Esse status significa que a Messages API não conseguiu se conectar ao provedor de mensagens. Isso pode ser devido a uma interrupção no serviço do provedor de mensagens ou a outro incidente.

Callbacks de status de rejeição

Uma mensagem pode ser rejeitada por diversos motivos:

• Messages API não consegue processar a mensagem (por exemplo, parâmetros inválidos ou mídia não compatível).
• A operadora rejeita a mensagem — por exemplo, ao enviar um MMS para um país onde o serviço não é oferecido.
• O tempo de vida (TTL) da mensagem expira antes que ela possa ser entregue.

Nesses casos, um rejected A função de retorno é enviada com um objeto de erro que descreve a falha.

Exemplos de callbacks

SMS (Mensagem em várias partes)

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2023-05-01T14:00:00.000Z",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "client_ref": "string",
  "channel": "sms",
  "destination": {
    "network_code": "12345"
  },
  "sms": {
    "total_count": "2"
  }
}

RCS (Solicitação rejeitada com failover por SMS)

{
  "message_uuid": "001",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:00.000Z",
  "status": "rejected",
  "channel": "rcs",
  "destination": {
    "network_code": "12345"
  },
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1260",
    "title": 1260,
    "detail": "Destination unreachable - The message could not be delivered to the phone number.",
    "instance": "abc102"
  },
  "workflow": {
    "id": "1001",
    "item_number": "1",
    "items_total": "2"
  }
}

Códigos de rede

Messages API inclui um network_code em callbacks para identificar a operadora responsável pelo tratamento da mensagem. Os códigos de rede são combinações de Códigos de País de Celular (MCC) e Códigos de Rede Móvel (MNC), aplicam-se a SMS, RCS e MMS e representam os dados mais precisos disponíveis no momento do evento de callback de status.