Receba recibos de entrega de SMS enviadas com Python

Você já aprendeu como enviar um SMS com Python. Você também aprendeu a receber mensagens SMS em aplicativos Python. Mas, a menos que você tenha acesso ao aparelho para o qual enviou o SMS, como pode ter certeza de que seu SMS chegou ao destino?

Com a Messages API, você pode confirmar a entrega por meio de webhooks e criar recibos de entrega (também conhecidos como DLRs ou relatórios de entrega). Neste tutorial, você aprenderá a configurar testes de entrega de SMS em Python com a ajuda da API do Vonage.

Observação: Existem duas SMS APIs para aplicativos de SMS na Vonage. A SMS API pode ser usada para mensagens SMS, enquanto a Messages API permite que você utilize tanto canais SMS quanto não SMS, como WhatsApp, Facebook Messenger, Viber e MMS. Este tutorial utiliza a Messages API.

Pré-requisitos

Para criar uma aplicação em Python para confirmação de entrega de SMS, você precisará primeiro de uma Account na API da Vonage. Depois de configurar sua conta da Vonage, você também precisará instalar as seguintes ferramentas:

• Python será usado como framework para o seu aplicativo.

• Flask será usado para criar seu webhook para relatórios de entrega de SMS.

• O pacote CLI da Vonage permitirá que você configure corretamente sua conta da Vonage. Ele também pode ser usado para adquirir um número virtual.

Python

Baixe a versão adequada do Python para o seu sistema operacional na página oficial página de downloads do Python.

1. Antes de instalar o Flask, crie o diretório do seu projeto e acesse-o da seguinte maneira:

mkdir delivery_receipt
cd delivery_receipt

Frasco

Instale o Flask com o pip gerenciador de pacotes. pip O Flask já vem instalado com o Python. Você usará o Flask para executar seu aplicativo. Use o seguinte comando no terminal para instalar o Flask dentro da pasta recém-criada.

pip install flask

CLI da Vonage

Instale a CLI do Vonage globalmente no seu terminal usando o npm gerenciador de pacotes:

Instruções

Depois de instalar com sucesso os pacotes acima, você poderá começar a desenvolver seu aplicativo em Python para realizar testes de envio de SMS.

Aqui estão as etapas para criar um aplicativo em Python que receba relatórios de entrega de SMS:

1. Criar um webhook para recibos de entrega de SMS

2. Torne a URL do webhook acessível ao público

3. Configure seu account da Vonage para receber confirmaciones de entrega

4. Enviar um SMS para testar relatórios de entrega em Python

1. Criar um webhook para recibos de entrega de SMS

O primeiro passo para receber confirmaciones de entrega de SMS é criar um webbook.

Quando você envia mensagens pelo seu (aplicativo Vonage)[https://developer.vonage.com/en/getting-started/Concepts/glossary#vonage-application], o comprovante de entrega é encaminhado para o seu aplicativo Python, caso você tenha definido uma URL de webhook no seu painel do Vonage. Configuraremos a parte do Vonage mais adiante, mas, por enquanto, vamos configurar nosso aplicativo Flask para aceitar essa solicitação POST.

Você aceitará uma POST solicitação no seu manipulador de webhook para receber atualizações de status das mensagens. As solicitações de webhook da Messages API são POST são solicitações. Você criará um endpoint no Flask para essa solicitação.

Crie um receipt.py arquivo no seu projeto Flask e adicione o seguinte código:

#!/usr/bin/env python3
from flask import Flask, request, jsonify
from pprint import pprint

app = Flask(__name__)

@app.route("/webhooks/message-status", methods=['POST'])
def message_status():
  if request.is_json:
    data = request.get_json()
    pprint(data)
  else:
      data = dict(request.form) or dict(request.args)
      pprint(data)

  return "200"

if __name__ == '__main__':
  app.run(host="", port=3000)

No código acima, você criou o endpoint do webhook, /webhooks/message-status, que aceita o código de status do SMS por meio de webhooks.

O endpoint também analisa a solicitação recebida e, em seguida, utiliza a request.get_json() função para verificar se a solicitação está no formato JSON. As solicitações codificadas em JSON têm seu mimetype definido como application/json ou application/*+json.

Se a solicitação não estiver no formato JSON, então request.form e request.args recuperar os pares chave/valor no corpo da solicitação ou na string de consulta da URL, respectivamente.

Em seguida, o endpoint analisa os dados da solicitação e os transfere para a data variável e os exibe no terminal usando pprint. O último comando executa o servidor do aplicativo na porta 3000.

2. Torne a URL do Webhook acessível ao público

Agora, você criará uma URL acessível ao público para a qual as APIs da Vonage possam enviar as solicitações de webhook. Dessa forma, a API da Vonage poderá acessar o webhook que você criou para os comprovantes de entrega.

ngrok é um mecanismo leve e rápido que simula um servidor web. Portanto, você não precisará fazer ajustes de DNS, configurações de SSL e outras tarefas que seriam necessárias em um cenário real de produção. O ngrok é uma ferramenta útil para testes rápidos em um ambiente de desenvolvimento. Você pode conferir este tutorial para obter mais informações sobre como usar o ngrok.

Primeiro, instale o ngrok a partir do site oficial site.

Em seguida, execute o ngrok no seu terminal:

Você receberá uma URL pública semelhante à seguinte:

Você pode fazer solicitações da Web para a URL que ngrok foi gerada para você. Ela está disponível na porta 3000 da sua máquina local.

Observe os seguintes pontos:

• A URL muda sempre que você reinicia o ngrok servidor, caso você esteja no plano gratuito.

• No plano gratuito, uma sessão do servidor ngrok tem duração de 1 hora; após esse período, você pode iniciar o servidor novamente e receberá uma nova URL pública.

Você precisa acrescentar seu endpoint à URL do ngrok recém-gerada para formar a URL do seu webhook da seguinte maneira:

• https://f9db-102-89-43-137.eu.ngrok.io/webhooks/message-status

A URL acima é a URL completa do seu webhook.

3. Configure sua conta da Vonage para receber recibos de entrega

Agora que seu webhook de confirmação de entrega está pronto, você vai concluir a configuração na sua conta da Vonage.

Acesse as página de configurações no seu painel e acesse as seção de configurações de SMS para selecionar a Messages API. Você pode manter os outros valores padrão, como a versão da Messages API, em 1.0.

Em seguida, acesse as página de Applications para criar um aplicativo da Vonage. Clique em botão “+ Criar aplicativo” . Em seguida, digite o nome desejado no campo Nome .

Na seção “Recursos”, selecione Mensagens e insira o URL do seu webhook URL de status. Você precisará inserir sua URL tanto para “Inboud” quanto para “Status URL”. Confira nosso Como receber mensagens SMS em Python para saber como configurar a URL de entrada para aceitar mensagens SMS recebidas.

Seu painel deve ficar assim, com suas URLs do ngrok:

ngrok-webhooks-configured-for-messages-api.png

Clique em “Gerar novo aplicativo” para concluir o processo de criação. Isso o levará automaticamente à página do aplicativo

Na página do aplicativo, você pode vincular seu número ou comprar um número virtual, caso esteja usando um Account pago da Vonage.

4. Enviar um SMS para testar relatórios de entrega em Python

Neste momento, seu servidor ngrok já deve estar em execução na porta 3000. Certifique-se de também ter configurado seu aplicativo com um número virtual no seu Account da Vonage.

Agora, você pode iniciar o aplicativo Flask em outra janela do terminal para manter a janela anterior em execução com o ngrok.

Use o comando a seguir para iniciar o aplicativo na porta especificada 3000. O ngrok obtém o aplicativo da porta e o disponibiliza na internet por meio de sua URL pública.

Para testar nosso código, precisaremos enviar um SMS do nosso número da Vonage por meio da Messages API.

Primeiro, vamos criar um novo arquivo em nosso projeto chamado send-sms.sh

Nesse arquivo, vamos adicionar o seguinte código:

curl -X POST https://api.nexmo.com/v1/messages \
  -H 'Authorization: Bearer '$JWT\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
          "message_type": "text",
          "text": "Vonage Delivery Receipt Testing",
          "to": "'$TO_NUMBER'",
          "from": "'$FROM_NUMBER'",
          "channel": "sms"
}'

Substitua $TO_NUMBER pelo seu número pessoal, $FROM_NUMBER pelo seu número virtual da Vonage e $JWT por um JWT criado por você para o aplicativo. Você pode usar nossa ferramenta online de geração de JWT.

Certifique-se de adicionar o código do seu país a YOUR_PERSONAL_NUMBER , por exemplo, 23400000001

Em seguida, abra uma nova aba no seu terminal e execute:

bash send-sms.sh

Você deverá ver uma resposta com o message_id, assim:

{"message_uuid":"6cdbd8ed-7217-4bbf-ba3f-da9cdcaeaf2b"}

Então, se você der uma olhada na aba do ngrok, verá uma solicitação POST bem-sucedida, assim:

POST /webhooks/message-status  200 OK

E, por fim, você verá na aba do seu aplicativo o status do comprovante de entrega no terminal, conforme mostrado a seguir:

{'channel': 'sms',
 'destination': {'network_code': '42507'},
 'from': '972523083911',
 'message_uuid': '30af1182-e2c9-4986-bf60-0129a14bbc79',
 'sms': {'count_total': '1'},
 'status': 'submitted',
 'timestamp': '2023-06-19T10:23:16Z',
 'to': '972532208911',
 'usage': {'currency': 'EUR', 'price': '0.093'}}

Observe que o status é submitted. Em alguns segundos, você deverá receber uma segunda resposta semelhante a esta:

{'channel': 'sms',
 'destination': {'network_code': '42507'},
 'from': '972523083911',
 'message_uuid': '30af1182-e2c9-4986-bf60-0129a14bbc79',
 'status': 'delivered',
 'timestamp': '2023-06-19T10:23:23Z',
 'to': '972532208911'}

Conclusão

Ao trabalhar com mensagens SMS, os comprovantes de entrega podem ser fundamentais — especialmente ao desenvolver aplicativos de grande escala. Ao criar um aplicativo em Python para comprovantes de entrega, você ficará sabendo quando houver falhas na entrega e poderá tomar medidas corretivas

Este artigo mostra como obter recibos de entrega de mensagens SMS enviadas por meio da Messages API da Vonage. Você aprendeu a criar um aplicativo em Python para lidar com relatórios de entrega de SMS e também a testar esse aplicativo com o ngrok. Agora, você pode incluir o recurso de recibos de entrega em qualquer aplicativo em Python que criar.

Leitura complementar

Você pode consultar alguns dos nossos recursos para saber mais sobre a Messages API:

1. Visão geral da Messages API

2. Referência da Messages API

3. Guia de recibos de entrega

4. Restrições relativas aos comprovantes de entrega

Você gostou deste tutorial? Teve alguma dificuldade? Entre em contato pelo Twitter ou na Slack da Comunidade Vonage. Estamos ansiosos para ver o que você está criando!