Compartilhar:
){kind=small}
Liz Acosta é Developer Advocate na Vonage. Embora sua trajetória profissional — de estudante de cinema a profissional de marketing, de engenheira a Developer Advocate — possa parecer pouco convencional, ela é bastante comum na área de Relações com Desenvolvedores! Liz adora pizza, plantas, pugs e Python.
Como enviar mensagens SMS com Python, Flask e Vonage
Tempo de leitura: 14 minutos
Este tutorial passo a passo mostra como enviar SMS com Python e Flask usando a Messages API for Vonage. Você criará um aplicativo web funcional, configurará webhooks e lidará com recibos de entrega em tempo real. Embora o In-App Messaging tenha ganhado popularidade, o SMS ainda atende a uma variedade de casos de uso, que vão desde lembretes de compromissos até transmissões de emergência e verificação de identidade por meio da autenticação de dois fatores (2FA). Ao final deste tutorial, você será capaz de implementar com sucesso a estrutura necessária para enviar um SMS usando a Vonage e um aplicativo Python Flask.
Antes de começarmos o tutorial, vamos abordar alguns dos termos e tecnologias utilizados no aplicativo de exemplo. Se você já estiver familiarizado com esses Concepts, pode pular direto para o tutorial sobre como enviar mensagens SMS com Python.
A Messages API da Vonage se integra a SMS, MMS, RCS, WhatsApp, Messenger e Viber, permitindo uma comunicação personalizada de acordo com o canal de sua escolha. No que diz respeito ao SMS, em particular, a Messages API permite que você envie mensagens de texto programaticamente, por meio de uma solicitação HTTP a um endpoint da API. A API encaminha a mensagem para a rede celular para que seja entregue no dispositivo do destinatário. Independentemente do tipo de mensagem que você estiver enviando, a API exige os seguintes campos:
Tipo de mensagem: O tipo de mensagem a ser enviada, ou seja,
textouimage.Conteúdo da mensagem: O conteúdo declarado no
message_typecampo, ou seja, a mensagem de texto ou a URL acessível ao público da imagem anexada.Para: O destinatário da mensagem.
De: O remetente da mensagem.
Canal: O canal pelo qual a mensagem está sendo enviada, ou seja,
smsoumms.
O corpo da solicitação tem a seguinte aparência:
{
"message_type": "text",
"text": "Hello from Vonage",
"to": "14155551234",
"from": "14155551098",
"channel": "sms",
}A 202 resposta contém o seguinte:
{
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}Onde message_uuid é o identificador exclusivo da mensagem e workflow_id refere-se ao ID do fluxo de trabalho de failover – que só está presente se a solicitação tiver sido enviada com a propriedade failover. Você pode saber mais sobre esses valores na documentação da Messages API.
No SDK do Python da Vonage, a API é representada assim:
from vonage_messages import Sms
message = Sms(
from_='14155551098',
to='14155551234',
text='Hello from Vonage!',
)
A Vonage possui duas APIs de mensagens: uma SMS API simples e dedicada e uma Messages API mais avançada. A SMS API permite enviar e receber mensagens SMS por meio de programação. Se isso for tudo o que você precisa, essa API dará conta do recado. No entanto, os desenvolvedores costumam optar pela Messages API para poderem usá-la para enviar e receber mensagens por diferentes canais, incluindo SMS. Em outras palavras, se você começar com a Messages API hoje e quiser adicionar mais canais amanhã, não precisará desmontar sua integração e recomeçar do zero.
Além disso, a estrutura das solicitações e os formatos dos webhooks são consistentes em todos os canais. Ela oferece suporte a SMS, MMS, RCS, WhatsApp, Viber e Facebook Messenger. A Messages API também oferece suporte a conteúdo avançado, de modo que suas mensagens podem incluir imagens, arquivos, modelos e mensagens interativas nos canais que oferecem suporte a esses recursos. Para este tutorial, usaremos a Messages API.
Significa Serviço de Mensagens Curtas.
Utiliza protocolos de comunicação padronizados para enviar mensagens de texto curtas para dispositivos ou entre eles.
Significa Serviço de Mensagens Multimídia.
Permite enviar conteúdo multimídia, como imagens, Videos e áudio, além de textos mais longos do que os que podem ser enviados em uma única mensagem SMS.
Envia mensagens pela rede móvel sem que o destinatário precise ter uma conexão de dados ou Wi-Fi.
Significa “Rich Communication Services”.
É um protocolo de comunicação para o envio de mensagens para e entre dispositivos conectados a uma rede de telefonia celular.
Pode incluir texto, fotos, Videos e arquivos, bem como elementos interativos, como respostas sugeridas e botões de ação sugeridos.
Ela apresenta algumas semelhanças com as mensagens MMS, mas também algumas diferenças importantes no conteúdo da mensagem.
É necessário um aplicativo para enviar e receber mensagens, independentemente do dispositivo.
Existem diferentes requisitos quanto a quem pode enviar mensagens e como fazê-lo.
Neste tutorial, vamos criar um aplicativo web para enviar um SMS usando Flask, um framework web leve, porém poderoso, para Python. Como framework, ele permite que os desenvolvedores criem rapidamente um aplicativo de software usando tecnologias web para ser executado em um navegador. Nós o escolhemos para este tutorial devido à sua facilidade de uso e abordagem minimalista — ao contrário de outros frameworks de desenvolvimento web em Python, ele nos oferece apenas o essencial de que precisamos para criar um aplicativo de SMS de exemplo.
Um webhook é a forma pela qual uma aplicação baseada na web envia dados ou notificações de eventos para outra aplicação, permitindo a comunicação automática, em vez de uma aplicação ter que consultar constantemente a outra em busca de atualizações. Em geral, isso significa interagir pela web por meio de uma API, utilizando uma solicitação HTTP. Neste tutorial específico, usaremos um webhook para encaminhar o comprovante de entrega da Messages API confirmação de entrega para o aplicativo Flask.
Neste tutorial, vamos criar um aplicativo web e executá-lo localmente no seu computador. Como ele estará sendo executado localmente, não poderá ser acessado pela internet pública; e, se o seu aplicativo web não puder ser acessado, a Vonage não poderá enviar uma solicitação ao webhook. É aí que entra o tunelamento. O tunelamento expõe servidores locais à internet pública por meio de URLs públicas temporárias ou estáticas. O ngrok é uma plataforma de software que oferece esse serviço.
Em resumo, vamos criar um aplicativo web em Python Flask com um webhook e usar o ngrok para tornar seu aplicativo local acessível por meio de um tunelamento para uma URL pública, de modo que a Vonage possa efetivamente enviar dados para um status webhook.
Neste tutorial, usaremos o Flask para implementar um aplicativo que envia mensagens de texto e também define um webhook. Usaremos o ngrok para expor o webhook à internet pública, para que a Vonage possa fazer solicitações a ele.
Se preferir, você pode abrir o código para enviar um SMS na GitHub da Comunidade Vonage.
Para concluir este tutorial, você precisará do seguinte:
Python 3.8 ou superior
Uma Account no ngrok e instalação
Antes de começarmos a construir, vamos colocar tudo em ordem.
A Messages API precisa ter acesso ao seu webhook para poder enviar solicitações a ele; portanto, a URL do endpoint deve estar acessível pela internet pública.
Depois de instalar o ngrok, abra uma janela de terminal e execute:
ngrok http 5000Este comando irá gerar as URLs públicas para as quais seu servidor local se conectará via túnel na porta 5000. Anote a URL pública, pois vamos usá-la ao criar nosso aplicativo Vonage; ela deve ter um formato semelhante a este:
Forwarding https://4647-135-180-11-118.ngrok-free.app -> http://localhost:5000Observação: A menos que você esteja usando um dos planos pagos do ngrok, as URLs públicas geradas não são permanentes. Em outras palavras, toda vez que você executar o ngrok comando, as URLs resultantes mudarão, e você precisará atualizar a configuração do seu aplicativo Vonage. Para evitar isso, deixe o ngrok em execução durante todo o tutorial.
Como vamos usar a Messages API, você também precisará configurar suas configurações da conta de acordo com isso. Na barra de navegação à esquerda do painel do desenvolvedor, selecione Configurações da API. Nas seção de configurações de SMS , selecione Messages API e siga as instruções exibidas para salvar suas alterações.
A screenshot of the API Settings menu in the Vonage developer dashboard indicating where to configure the SMS settings to use the Messages API.Crie um aplicativo da Messages API e vincule seu número a ele
Primeiro, você precisa criar um aplicativo da Messages API. O “aplicativo” ao qual nos referimos aqui é um contêiner para as informações de configuração e segurança necessárias para a Messages API. Não é a mesma coisa que o aplicativo web Flask que também iremos criar.
Crie seu aplicativo da Messages API no painel do desenvolvedor acessando a Applications no menu à esquerda e clicando no botão botão “Criar novo aplicativo” . Isso abrirá o menu de criação de aplicativos. Dê ao seu aplicativo o nome send-sms.
No âmbito das seção “Recursos” , ative a opção para Mensagens, o que exibirá uma lista de campos de texto. No campo de texto intitulado URL de status, insira a URL pública do ngrok complementada com o webhook que definiremos no aplicativo Flask. Ficará mais ou menos assim https://0a6ec0a950eb.ngrok-free.app/webhooks/message-status.
Como não estamos lidando com mensagens recebidas neste tutorial, o URL de entrada não será usada. No entanto, como a criação de um aplicativo exige uma, você pode fornecer http://example.com/webhooks/inbound para atender a esse requisito.
Clique no botão “Gerar novo pedido”.
A screenshot of the Create an application menu in the Vonage developer dashboard indicating which options need to be configured in order to create a Messages application.Agora que seu aplicativo foi criado, você pode vincular seu número a ele clicando no botão “Vincular” na tabela de números disponíveis. Certifique-se de selecionar um número com recursos de SMS e MMS.
Em uma nova janela do terminal, execute o seguinte comando para criar um novo diretório de projeto e acessá-lo:
mkdir vonage-send-sms && cd vonage-send-sms
Agora que você já tem tudo configurado, é hora de começar a construir.
Pule para qualquer seção que desejar clicando nas etapas abaixo:
Os ambientes virtuais do Python permitem que você instale pacotes em um local isolado do restante do seu sistema. Isso ajuda a evitar a desorganização em todo o sistema e conflitos entre diferentes versões do Python e pacotes. Para saber mais, confira nossa postagem no blog sobre ambientes virtuais.
No diretório do seu projeto, execute os seguintes comandos para criar um ambiente virtual e ativá-lo:
python3 -m venv venv && source venv/bin/activateAgora você deve ver o prompt do terminal precedido por (venv). Para desativar seu ambiente virtual, execute o deactivate comando.
Para instalar as dependências necessárias para este tutorial, execute o seguinte:
pip install vonage flask python-dotenv Jinja2 flask-socketio
No painel do desenvolvedor Applications ,, clique no aplicativo que você criou para este tutorial e, em seguida, clique em Editar. Assim que a janela de edição abrir, clique no botão que diz “Gerar chave pública e privada”. Isso iniciará o download da sua chave privada como um arquivo com a extensão .key. Mantenha esse arquivo em sigilo e não o compartilhe em nenhum lugar onde possa ser comprometido. Se você planeja enviar esse código para algum repositório público, certifique-se de adicionar o arquivo da sua chave privada ao seu .gitignore arquivo.
Clique no botão “Salvar alterações” e anote também o ID do seu aplicativo.
A screenshot of the application Edit menu in the Vonage developer dashboard showing where to generate a public and private key.
A screenshot of the Messages application in the Vonage developer dashboard indicating where you can find the application ID.Mova o arquivo da sua chave privada para o diretório do seu projeto. No mesmo diretório, crie um arquivo chamado .env e adicione as seguintes variáveis:
APPLICATION_ID=replace-this-with-your-application-ID
PRIVATE_KEY=replace-this-with-the-name-of-your-private-key-file
VONAGE_VIRTUAL_NUMBER=replace-this-with-your-virtual-numberVocê também pode encontrar o modelo no GitHub. Para saber mais, confira nossa postagem no blog sobre variáveis de ambiente.
Neste tutorial, vamos criar um aplicativo Flask minimalista que utiliza a Messages API para enviar um SMS por meio de um formulário da web. Para criar esse formulário, precisaremos de:
O código do aplicativo em Python.
E um modelo HTML a ser exibido em um navegador.
No diretório do seu projeto, crie um arquivo chamado app.py que inclua o seguinte código:
import os
from dotenv import load_dotenv
from flask import Flask, redirect, render_template, request, url_for
from flask_socketio import SocketIO
from vonage import Auth, Vonage
from vonage_messages import Sms
load_dotenv()
APPLICATION_ID = os.getenv("APPLICATION_ID")
PRIVATE_KEY = os.getenv("PRIVATE_KEY")
VONAGE_VIRTUAL_NUMBER = os.getenv("VONAGE_VIRTUAL_NUMBER")
if not APPLICATION_ID or not PRIVATE_KEY or not VONAGE_VIRTUAL_NUMBER:
raise RuntimeError("Missing APPLICATION_ID, PRIVATE_KEY, or VONAGE_VIRTUAL_NUMBER env vars")
client = Vonage(Auth(application_id=APPLICATION_ID, private_key=PRIVATE_KEY))
app = Flask(__name__)
socketio = SocketIO(app)
@app.route('/')
def index():
return render_template('index.html')
@app.route("/delivery_receipt/<message_uuid>")
def delivery_receipt(message_uuid):
return render_template("delivery_receipt.html", message_uuid=message_uuid)
@app.route("/webhooks/message-status", methods=["POST"])
def message_status():
data = request.get_json(silent=True) or {}
message_uuid = data.get("message_uuid")
status = data.get("status")
if not message_uuid or not status:
return {"error": "missing message_uuid/status"}, 400
payload = {"message_uuid": message_uuid, "status": status}
err = data.get("error")
if isinstance(err, dict):
payload["info"] = f"{err.get('title', 'Error')} : {err.get('detail', '')}"
print(f"Status update uuid={message_uuid} status={status}")
socketio.emit("status_update", payload)
return "200", 200
@app.route("/send_sms", methods=["POST"])
def send_sms():
to_number = (request.form.get("to_number") or "").strip()
message = (request.form.get("message") or "").strip()
print(f"To number is ===> {to_number}")
if not to_number or not message:
return {"error": "to_number and message are required"}, 400
response = client.messages.send(
Sms(
from_=VONAGE_VIRTUAL_NUMBER,
to=to_number,
text=message,
)
)
message_uuid = response.message_uuid
print(f"Message UUID is ===> {message_uuid}")
return redirect(url_for('delivery_receipt', message_uuid=message_uuid))
if __name__ == '__main__':
socketio.run(app)Vamos analisar o que está acontecendo aqui.
A parte mais importante do código é a send_sms route e a função. É aqui que usamos a Messages API para enviar um SMS. Neste exemplo específico, estamos usando um formulário on-line para fornecer os detalhes da nossa mensagem e acionar uma solicitação à Messages API. Assim que o formulário é enviado, o aplicativo redireciona para uma delivery_receipt página.
O próximo bloco ao qual devemos prestar atenção é a message_status roteiro e função. Este é o webhook que configuramos para a URL de status em nosso aplicativo Messages no painel do desenvolvedor. É para lá que a Vonage enviará atualizações sobre o status da mensagem enviada pelo aplicativo.
Normalmente, a atualização do status de uma mensagem pode ser feita por meio de um banco de dados ou de polling, mas, como este é um aplicativo de demonstração simples, vamos usar o WebSocket. O WebSocket é um protocolo que permite a comunicação entre o servidor e o navegador. Ele apresenta uma vantagem em relação ao HTTP RESTful, pois as comunicações são bidirecionais e em tempo real. Isso permite que o servidor notifique o cliente a qualquer momento, em vez de o cliente ter que fazer polling em intervalos regulares para verificar se há atualizações.
Este exemplo específico utiliza a socketio biblioteca para estabelecer um canal de comunicação. Essas atualizações de status serão refletidas na página “Confirmação de Entrega” – dessa forma, mesmo que a mensagem falhe devido a regulamentações ou por qualquer outro motivo, você poderá ver o status e quaisquer informações adicionais em tempo real.
No diretório do seu projeto, crie um diretório chamado templates. Um templates diretório é uma convenção do Flask: o Flask está configurado para procurar um templates diretório ao renderizar HTML para o front-end de um aplicativo web.
No templates diretório, crie dois arquivos: index.html e delivery_receipt.html. Copie e cole o código respectivo do repositório do GitHub.
Agora você tem tudo o que precisa para executar o código. Para implantar seu aplicativo web localmente, execute o seguinte comando a partir do diretório raiz do projeto:
flask runIsso iniciará um servidor em http://127.0.0.1:5000. Acesse esse endereço em um navegador da web e você deverá ver algo assim:
A screenshot of the web app created for the tutorial with a form to send an SMS.5. Experimente!
Preencha o formulário com o número de telefone (com o código do país) no qual você deseja receber uma mensagem de texto, juntamente com a mensagem a ser enviada.
Dependendo das regulamentações de SMS da sua região, você receberá uma mensagem de texto do seu número virtual da Vonage com as informações que você forneceu no formulário. No entanto, como as regulamentações de diferentes países podem restringir o envio de SMS a partir de um número virtual da Vonage, independentemente de a mensagem ter sido entregue com sucesso ou não, o aplicativo Flask gerará um comprovante de entrega em tempo real da Vonage.
A screenshot of the web app created for the tutorial showing a message delivery receipt.Observação: Devido às diferentes regulamentações de SMS em todo o mundo, você pode receber um código de erro da Vonage ao tentar enviar uma mensagem SMS a partir de um número virtual da Vonage. Você pode visualizar os registros no painel do desenvolvedor selecionando “Registros” na barra de navegação à esquerda. Para saber mais sobre as regulamentações de SMS – especialmente se você estiver usando um número de 10 dígitos dos EUA –, consulte esta postagem do blog sobre o que você precisa saber sobre o 10DLC.
Este tutorial orientou você pelo processo de envio de mensagens SMS usando Python, Flask e a Messages API do Vonage. O SMS continua desempenhando um papel crucial em diversas aplicações, desde alertas até autenticação, e este guia oferece uma abordagem prática para a criação de um aplicativo web com funcionalidade de SMS.
Você aprendeu a configurar um aplicativo Flask, integrar a API da Vonage e utilizar o ngrok para expor seu servidor local à internet, possibilitando recursos de mensagens em tempo real. O tutorial abordou componentes essenciais, como configurações da API, tratamento de webhooks para atualizações de status de mensagens e a criação de um formulário web intuitivo para o envio de SMS.
Além disso, foi enfatizada a importância de compreender as regulamentações relativas a SMS e suas implicações, a fim de garantir práticas de envio de mensagens em conformidade e explicar por que a Vonage pode não conseguir enviar uma mensagem. Embora essa restrição possa significar que seu aplicativo não esteja totalmente funcional, você tem, pelo menos, uma base sobre a qual construir, bem como uma compreensão fundamental da Messages API. A partir daqui, você pode explorar mais a fundo a API e outros canais de mensagens para aproveitar a comunicação por texto de acordo com as necessidades da sua empresa.
Tem alguma dúvida ou quer compartilhar o que está criando?
Inscreva-se no Boletim Informativo para Desenvolvedores
Siga-nos no X (antigo Twitter) para ficar por dentro das novidades
Assista aos tutoriais no nosso canal do YouTube
Conecte-se conosco na página de desenvolvedores da Vonage no LinkedIn
Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.
Compartilhar:
Liz Acosta é Developer Advocate na Vonage. Embora sua trajetória profissional — de estudante de cinema a profissional de marketing, de engenheira a Developer Advocate — possa parecer pouco convencional, ela é bastante comum na área de Relações com Desenvolvedores! Liz adora pizza, plantas, pugs e Python.