Retornos de chamada para status de SMS

A Messages API utiliza callbacks de status para notificar seu aplicativo quando o status de uma mensagem for alterado, por exemplo, quando ela for enviada, entregue ou rejeitada. Essas chamadas de retorno oferecem visibilidade do ciclo de vida da mensagem em todos os canais, incluindo SMS. Este guia explica como os recibos de entrega de SMS (DLRs) são tratados e mapeados para as chamadas de retorno de status da Messages API.

Quando você envia uma mensagem usando o canal SMS na Messages API, a SMS API subjacente da Vonage entrega a mensagem a uma operadora ou provedor e retorna os comprovantes de entrega (DLRs). Esses DLRs descrevem até que ponto a mensagem avançou pela rede. Messages API, então, converte esses DLRs de SMS em um conjunto padronizado de callbacks de status e os envia para a URL do webhook que você configurou.

Ciclo de vida das mensagens SMS

Uma mensagem SMS geralmente passa pelas seguintes etapas:

Palco Descrição Fato Gerador Status da Messages API
Aceito pela SMS API A mensagem foi aceita e encaminhada por meio de gateways da SMS API. Sim submitted
Entregue no dispositivo Um aviso de entrega (DLR) da rede confirma que a mensagem chegou ao dispositivo do usuário final. Sem custo adicional delivered
Vencido, com falha ou rejeitado A mensagem não pôde ser entregue ou foi rejeitada pela SMS API ou pelo provedor. — rejected

Observação: a confiabilidade dos relatórios de entrega de SMS pode variar dependendo da operadora. Algumas redes podem não enviar esses relatórios ou podem apresentar informações imprecisas sobre o status das mensagens.

DLRs de SMS x Callbacks de status da Messages API

As operadoras de SMS enviam comprovantes de entrega (DLRs) para indicar o andamento da mensagem. A Messages API processa esses DLRs e os mapeia para seu próprio modelo de status.

Status do SMS DLR Status da Messages API Notas
accepted submitted Enviado quando a SMS API aceita a mensagem para entrega.
buffered (ignorado) Raramente utilizado pela SMS API; não é encaminhado.
delivered delivered Indica o recebimento pelo dispositivo do usuário final (se compatível com a operadora).
expired rejected Mapas para o interior código de erro 1360.
failed rejected Indica falha do provedor ou erro de rede.
unknown rejected Mapas para o interior código de erro 1330.
rejected rejected Mapas de acordo com Correspondências de códigos de erro de MMS/SMS.

Exemplo: Retorno de chamada de status de SMS

Quando uma mensagem SMS for aceita com sucesso pela SMS API, você receberá uma submitted uma função de retorno semelhante a esta:

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

Se, posteriormente, um DLR confirmar a entrega, será enviada outra notificação com "status": "delivered".

Mais informações