Comprovantes de entrega

Quando você faz uma solicitação bem-sucedida à SMS API, ela retorna um array de message objetos, um para cada mensagem. O ideal é que eles tenham um status de 0, indicando sucesso. Mas isso não significa que sua mensagem tenha chegado aos destinatários. Significa apenas que sua mensagem foi colocada com sucesso na fila para envio.

Da Vonage roteamento adaptativo em seguida, identifica o melhor transportador para a sua mensagem. Quando o transportador selecionado entrega a mensagem, ele retorna um recibo de entrega (DLR).

Para receber DLRs no seu aplicativo, você deve fornecer um webhook para que a Vonage os envie. Como alternativa, você poderia usar o Reports API para baixar periodicamente seus registros, incluindo o status de entrega de cada mensagem.

Nota: Na maioria das situações, um DLR é um indicador confiável de que uma mensagem foi entregue. No entanto, não é uma garantia absoluta. Consulte Como funcionam os comprovantes de entrega.

Como funcionam os comprovantes de entrega

Os comprovantes de entrega podem ser:

  • Operadora - retornado quando o provedor de serviços recebe a mensagem
  • Aparelho celular - retornado quando o aparelho do usuário recebe a mensagem

Nem todos os DLRs garantem que o destinatário tenha recebido sua mensagem. Alguns comprovantes de entrega indicam apenas a conclusão bem-sucedida de uma etapa do processo de entrega, como o encaminhamento da mensagem para outra operadora. Outros comprovantes de entrega são falsos. Por esse motivo, a Vonage não pode garantir totalmente que um DLR seja preciso. Isso depende do países para quem você está enviando mensagens e quais são os provedores envolvidos.

Se a sua mensagem for mais longa do que o permitido para um único SMS, as mensagens serão concatenado. Você deve receber um DLR da operadora para cada parte do SMS concatenado. Os DLRs do aparelho para uma mensagem concatenada são atrasados. Isso ocorre porque o aparelho de destino precisa processar cada parte da mensagem concatenada antes de poder confirmar o recebimento da mensagem completa.

Entendendo o comprovante de entrega

Este é um DLR típico:

{
  "err-code": "0",
  "message-timestamp": "2018-10-25 12:10:29",
  "messageId": "0B00000127FDBC63",
  "msisdn": "447547232824",
  "network-code": "23410",
  "price": "0.03330000",
  "scts": "1810251310",
  "status": "delivered",
  "to": "Vonage"
}

Os campos mais importantes são status e err-code pois elas informam se sua mensagem foi entregue e, caso contrário, o que deu errado.

Mensagens de status do DLR

O status O campo no DLR indica se sua mensagem SMS foi entregue com sucesso. Os valores possíveis são:

status Descrição
accepted A mensagem foi aceita para entrega, mas ainda não foi entregue
delivered A mensagem foi enviada
buffered A mensagem foi armazenada em buffer para ser entregue posteriormente
expired A mensagem ficou retida no esquema de novas tentativas da operadora de destino e não pôde ser entregue dentro do prazo de validade
failed Mensagem não entregue
rejected A operadora de destino se recusa a entregar a mensagem
unknown Não há informações úteis disponíveis

Códigos de erro do DLR

O err-code O campo no DLR fornece informações mais detalhadas e pode ajudar na solução de problemas relacionados a uma entrega com falha. Um código diferente de zero indica que a mensagem não pôde ser entregue.

err-code Significado Descrição
0 Entregue A mensagem foi enviada com sucesso
1 Desconhecido A mensagem não foi entregue, e não foi possível identificar o motivo
2 Assinante ausente - Temporário A mensagem não foi entregue porque o aparelho estava temporariamente indisponível — tente novamente
3 Assinante ausente - Permanente O número não está mais ativo e deve ser removido do seu banco de dados
4 Chamada bloqueada pelo usuário Este é um erro permanente. O número deve ser removido do seu banco de dados, e o usuário deve entrar em contato com sua operadora de rede para remover o bloqueio
5 Erro de portabilidade Há um problema relacionado à portabilidade do número, e você deve entrar em contato com a operadora para resolvê-lo
6 Rejeição antispam A mensagem foi bloqueada pelo filtro antispam de uma operadora
7 Aparelho ocupado O aparelho não estava disponível no momento em que a mensagem foi enviada — tente novamente
8 Erro de rede A mensagem não foi enviada devido a um erro de rede — tente novamente
9 Número ilegal O usuário solicitou expressamente não receber mensagens de um serviço específico
10 Mensagem ilegal Há um erro em um parâmetro da mensagem, por exemplo, um sinalizador de codificação incorreto
11 Não roteável A Vonage não consegue encontrar uma rota adequada para entregar a mensagem — entre em contato apoio
12 Destino inacessível Não foi possível localizar a rota para o número — confirme o número do destinatário
13 Restrição de idade para assinantes O destinatário não pode receber sua mensagem devido à sua idade
14 Número bloqueado pela operadora O destinatário deve solicitar à sua operadora que habilite o serviço de SMS em seu plano
15 Fundo insuficiente no cartão pré-pago O destinatário está em um plano pré-pago e não tem crédito suficiente para receber sua mensagem
16 Quota do gateway excedida A entrega da mensagem falhou porque o número permitido de solicitações por período foi excedido. Observação: Esse erro é exibido apenas para contas registradas nos EUA e na França.
17 Mensagem bloqueada pela operadora O provedor de mensagens decidiu bloquear esta mensagem. Isso pode ser devido ao conteúdo ou a restrições impostas pelo provedor.
20 Regra de Tráfego do Fraud Defender A mensagem foi rejeitada por uma regra de tráfego do Fraud Defender. Revisar as regras de trânsito no painel do cliente. Mais informações sobre as regras de tráfego do Fraud Defender
22 Proteção contra enxurradas de SMS do Fraud Defender O limite de tráfego foi atingido
23 Proteção AIT A mensagem foi rejeitada pelo Fraud Defender AIT Protection
24 Regra Nacional do Fraud Defender A mensagem foi rejeitada por uma regra nacional do Fraud Defender. Verificar as regras do país no painel do cliente.
25 Regra da Rede de Defesa contra Fraudes A mensagem foi rejeitada por uma regra da Rede de Proteção contra Fraudes. Verificar as regras da rede no painel do cliente.
39 Endereço de remetente inválido para destino nos EUA Todas as mensagens SMS enviadas para os EUA devem ter origem em um número longo pré-aprovado nos EUA ou em um código curto associado à sua conta da Vonage. Mais informações sobre os recursos e restrições do SMS nos EUA
41 Limite diário ultrapassado O controle de envio foi limitado devido ao atingimento do volume máximo para o período
50 Filtro de entidades A mensagem falhou devido a entity-id estar incorreto ou não ter sido fornecido. Mais informações sobre as regulamentações específicas de cada país
51 Filtro de cabeçalho A mensagem falhou porque o ID do cabeçalho (from (número de telefone) estava incorreto ou faltava. Mais informações sobre as regulamentações específicas de cada país
52 Filtro de conteúdo A mensagem falhou devido a content-id estar incorreto ou não ter sido fornecido. Mais informações sobre as regulamentações específicas de cada país
53 Filtro de consentimento A mensagem não foi enviada porque o consentimento não foi autorizado. Mais informações sobre as regulamentações específicas de cada país
54 Erro de regulação Erro inesperado na regulação – entre em contato apoio
99 Erro geral Ocorreu um erro ao processar sua solicitação — entre em contato com apoio

Os demais campos do DLR são explicados no Referência da API.

Como usar a SMS API em campanhas

Antes de iniciar sua campanha de mensagens, verifique o guia de características específicas por país para os países para os quais você está enviando. Se o país para o qual você está enviando não fornecer DLRs confiáveis, use o Conversion API para fornecer à Vonage mais pontos de dados e garantir o melhor roteamento.

Opcionalmente, você pode identificar clientes ou campanhas específicos incluindo uma referência em cada mensagem enviada. Essas referências são incluídas no comprovante de entrega. Insira a referência escolhida na solicitação, especificando um client-ref parâmetro com até 40 caracteres.

Outros recursos