Monitorar o status de entrega das mensagens em Ruby

Neste breve tutorial, mostraremos como monitorar o status de entrega das mensagens enviadas com o Programmable SMS em seu aplicativo da Web em Ruby. A Twilio notificará você sobre o status de suas mensagens SMS e MMS por meio de um webhook, e depois você poderá registrar essas informações ou optar por enviar os dados de entrega de volta para a Twilio.

A Twilio pode enviar ao seu aplicativo da Web uma solicitação HTTP quando certos eventos ocorrem, como uma mensagem de texto recebida para um dos números de telefone da Twilio. Essas solicitações são chamadas de webhooks ou retornos de chamada de status. Para mais informações, consulte o nosso guia Introdução aos webhooks da Twilio. Encontre outras páginas do webhook, como um guia de segurança e perguntas frequentes na seção Webhooks dos documentos.

Os fragmentos de código neste guia foram elaborados usando a linguagem Ruby versão 2.0.0 ou superior e usam os seguintes módulos:

O que é um Webhook?

Os webhooks são retornos de chamada HTTP definidos pelo usuário. Geralmente, eles são acionados por algum evento, como receber uma mensagem SMS ou uma chamada telefônica. Quando esse evento ocorre, a Twilio faz uma solicitação HTTP (geralmente uma POST ou GET) para o URL configurado para o webhook.

Para lidar com um webhook, você só precisará criar um aplicativo da Web simples que possa aceitar as solicitações HTTP.

Os webhooks funcionam da mesma maneira em todos os aplicativos Twilio:

A Twilio faz uma solicitação HTTP para um URI que você fornece.
Seu aplicativo executa qualquer lógica que seja necessária: leitura/gravação de um banco de dados, integrar‐se a outra API ou executar algum cálculo.
Seu aplicativo então responde à Twilio com uma resposta TwiML com as instruções que você deseja que a Twilio execute.

Receba eventos de status em seu aplicativo da Web

Entre os status para os quais você pode receber notificações estão:

aceita
em fila
enviando
enviada
falha
entregue
não entregue
recebendo
recebida
lida (somente WhatsApp)

Para obter uma descrição completa desses e outros status de mensagem, consulte a documentação de referência da API.

Para fazer com que a Twilio chame seu webhook, você precisa fornecer um URL para seu aplicativo no parâmetro status_callback de cada mensagem para a qual deseja os retornos de chamada de status.

Vamos dar uma olhada em um exemplo de como você pode especificar esse parâmetro. Normalmente, você incluiria um URL que aponta para o seu aplicativo. Aqui usaremos um URL RequestBin no lugar, para que possamos inspecionar facilmente as solicitações do webhook que a Twilio envia:

Loading Code Sample...

Show sample response

Example JSON response

Show code

Envie um SMS com um URL de StatusCallback

Para que este exemplo de código seja executado, faça o seguinte:

Preencha o account_sid e o auth_token (encontrados no dashboard do console da Twilio)
Substitua o número de telefone from por um de seus números Twilio
Substitua o número to pelo seu número de telefone celular.

Não há problema em codificar suas credenciais ao testar localmente, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de confirmar qualquer código ou implantar na produção. Confira como definir variáveis de ambiente para obter mais informações.

Em seguida, vá para RequestBin e crie um novo bin clicando no link "public bin" (bin público) abaixo do botão azul "Create Request Bin" (Criar bin de solicitação). Copie o URL do novo bin, que é exibido próximo à parte superior da página. Substitua o valor do parâmetro statusCallback no fragmento pelo URL do bin.

Ao executar o código, você deve receber sua mensagem de texto. Além disso, você deve ver pelo menos uma solicitação entrar na lista de solicitações do RequestBin, com conteúdo semelhante a:

"AccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
"From": "+15017250604"
"MessageSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"
"MessageStatus": "sent"
"SmsSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"
"SmsStatus": "sent"

Essa solicitação mostra o MessageStatus como enviada. Supondo que tudo tenha sido bem‐sucedido, você deve ver a solicitação a seguir com o status entregue (pode levar alguns minutos para aparecer).

Assim que você aprender como o retorno de chamada de status funciona, estará pronto para lidar com o retorno de chamada em seu aplicativo.

Veja um exemplo de como você pode fazer isso registrando o status de cada mensagem:

Loading Code Sample...

Show sample response

Example JSON response

Show code

Handle a SMS StatusCallback

Obter eventos de status para mensagens geradas por TwiML

Respondendo a mensagens usando TwiML? Você ainda pode monitorar as ações do usuário por meio de webhooks de retorno de chamada.

Ao responder a uma mensagem de entrada com o verbo <Message>, você também pode fornecer um atributo action para especificar o URL para seu webhook de retorno de chamada. O retorno de chamada pode ser o mesmo que aqueles explorados nas seções anteriores.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message action="http://postb.in/b/1234abcd">This message will be tracked!</Message>
</Response>

Fornecer feedback de entrega de mensagens à Twilio

Do feedback direto de operadoras parceiras até a entrega de dados de alguns clientes maiores, bem como várias outras técnicas de monitoramento, a Twilio tem muitas fontes de dados que ajudam a otimizar a capacidade de entrega geral. Mas nada supera os dados coletivos em tempo real de nossos clientes.

O recurso API Message Feedback da Twilio permite que você reporte programaticamente as informações de entrega críticas à Twilio. As ações que indicam que uma mensagem foi recebida podem ser usadas pela Twilio para identificar problemas de rede e melhorar a capacidade de entrega de suas mensagens. Ao analisar dados agregados e dados específicos da sua conta, temos uma chance maior de aprimorar a entrega de suas mensagens.

Quer saber mais? Confira este guia sobre como enviar feedback de entrega de mensagens para a Twilio do seu aplicativo.

Contribuidores:

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.