Guia rápido do Sandbox: como enviar e receber mensagens do WhatsApp com Python

Introdução

Quer enviar e receber mensagens do WhatsApp usando Python de forma super rápida? Seja para testar um chatbot, criar um protótipo de mensagens ou simplesmente explorar a Messages API for Vonage, o Vonage WhatsApp Sandbox permite que você comece em poucos minutos.

Neste tutorial, vamos explicar como enviar e receber mensagens do WhatsApp em Python usando o Flask, um framework web leve, ideal para experimentos rápidos com APIs. Você não precisar configurar uma aplicação completa da Vonage nem se preocupar com uma Conta do WhatsApp Business (WABA). Essa é a maneira mais rápida de testar a Messages API da Vonage com o WhatsApp em Python!

Pré-requisitos

Você precisará das seguintes ferramentas e Accounts para acompanhar o passo a passo:

• Python 3.9 ou superior

• Account da API da Vonage

• ngrok (para testes de webhooks)

Configurar o WhatsApp Sandbox

1. Faça login no Painel da API da Vonage.

2. Acesse Mensagens > Área de teste de mensagens.

3. Digitalize o código QR com o WhatsApp para participar do ambiente de testes.

4. Adicione seu número de telefone à lista de contatos autorizados enviando a mensagem já preenchida.

   1. Você receberá uma resposta informando que seu número foi adicionado à lista de permissões, algo como “Obrigado! Seu número já está configurado no Sandbox da Messages API do Skid Froze.”

5. Tenha o número da sua sandbox à mão (geralmente é algo como 14157386102).

Em seguida, você precisará configurar os webhooks para que o ambiente de teste se conecte ao nosso aplicativo Flask. Para isso, temos o ngrok. Então, abra o terminal de linha de comando e execute:

ngrok http 3000

Agora você tem sua URL do ngrok, que deve ser algo como:

Forwarding
https://59bd32ee0a4e.ngrok-free.app -> http://localhost:3000     

Então, agora você pode atualizar os webhooks:

• Para o Inbound: https://YOUR_NGROK_URL/inbound

• Para o status: https://YOUR_NGROK_URL/status

Em seguida, clique no botão “Salvar webhooks”. Para obter mais ajuda, consulte Testando com o ngrok.

Example of configured webhooks for inbound messages and status updates using ngrok URLs

Inicialize seu projeto Flask em Python

Agora, abra uma nova aba no seu terminal, mantendo o túnel do ngrok em execução. Na segunda aba, você pode colar os seguintes comandos para criar seu projeto:

mkdir quickstart-whatsapp-python
cd quickstart-whatsapp-python
python3 -m venv venv
source venv/bin/activate
touch app.py config.py .env

Instalar as dependências necessárias

• Flask: Um framework web leve em Python usado para criar seu servidor de webhooks do WhatsApp com configuração mínima.

• Python-dotenv: Carrega variáveis de ambiente do seu arquivo .env no os.environ, mantendo informações confidenciais, como chaves de API, fora do seu código-fonte.

pip install python-dotenv flask
pip install requests
pip freeze > requirements.txt

Adicione suas variáveis de ambiente

Dentro de .env , você precisará adicionar o número de telefone do Sandbox da etapa anterior, bem como sua API_KEY e API_SECRET, que podem ser encontradas na sua página de configurações da API.

VONAGE_API_KEY=your-vonage-api-key
VONAGE_API_SECRET=your-vonage-api-secret
VONAGE_SANDBOX_NUMBER=your-vonage-sandbox-number
PORT=3000

Consulte nosso guia sobre variáveis de ambiente do Python para obter mais informações

Configure seu ambiente

Antes de começarmos a enviar mensagens, precisamos carregar nossas variáveis de ambiente e preparar o cabeçalho de autenticação para a Messages API do Vonage.

No seu arquivo arquivo config.py , adicione o seguinte:

import os
import base64
from dotenv import load_dotenv

load_dotenv()

VONAGE_API_KEY = os.getenv("VONAGE_API_KEY")
VONAGE_API_SECRET = os.getenv("VONAGE_API_SECRET")
VONAGE_SANDBOX_NUMBER = os.getenv("VONAGE_SANDBOX_NUMBER")
VONAGE_URL = "https://messages-sandbox.nexmo.com/v1/messages"

# Create Base64 encoded auth header
credentials = f"{VONAGE_API_KEY}:{VONAGE_API_SECRET}"
encoded_credentials = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')
VONAGE_AUTH_HEADER = f"Basic {encoded_credentials}"

Implemente sua lógica do WhatsApp

Agora que seu projeto já está configurado com as credenciais, é hora de dar vida ao seu aplicativo Flask. Neste arquivo, você definirá a lógica central para enviar e receber mensagens do WhatsApp usando o Vonage Sandbox.

Você começará configurando dois endpoints: um para lidar com as mensagens recebidas (/inbound) e outro para atualizações de status das mensagens (/status). Quando alguém enviar uma mensagem pelo WhatsApp para o seu número de sandbox, a Vonage a encaminhará para o seu servidor Flask. Seu aplicativo registrará o conteúdo da mensagem no terminal; só por diversão, ele inverterá o texto e o enviará de volta como resposta. Isso proporciona ao seu aplicativo um ciclo completo: WhatsApp → Flask → WhatsApp.

Adicione o seguinte ao seu arquivo app.py para receber webhooks e enviar mensagens:

import os
import json
import logging
import requests
from flask import Flask, request, Response
from config import *

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

def send_whatsapp_reply(to, message_text):
    payload = {
        "from": VONAGE_SANDBOX_NUMBER,
        "to": to,
        "channel": "whatsapp",
        "message_type": "text",
        "text": message_text,
    }

    headers = {
        "Content-Type": "application/json",
        "Authorization": VONAGE_AUTH_HEADER,
    }

    response = requests.post(VONAGE_URL, headers=headers, data=json.dumps(payload))
    response.raise_for_status()

@app.route("/inbound", methods=["POST"])
def inbound():
    data = request.get_json()
    sender = data.get("from")
    text = data.get("text", "").strip()

    logging.info(f"\n📩 Received message from {sender}:\n{text}\n")

    if sender and text:
        reversed_text = text[::-1]
        reply = f"Thank you for your message! Here's what it looks like in reverse:\n\n{reversed_text}"
        try:
            send_whatsapp_reply(sender, reply)
        except Exception as e:
            logging.error(f"Failed to send message: {e}", exc_info=True)
            return Response("Failed to send message", status=500)

    return Response(status=200)

@app.route("/status", methods=["POST"])
def status():
    data = request.get_json()
    logging.info(f"📬 Status webhook received:\n{json.dumps(data, indent=2)}\n")
    return Response(status=200)

if __name__ == "__main__":
    port = int(os.getenv("PORT", 3000))
    app.run(port=port)

Teste seu aplicativo

Inicie seu servidor Flask na aba do terminal que não está usando o ngrok:

export FLASK_ENV=development
python3 app.py

Assim que a configuração estiver concluída:

1. Envie uma mensagem do seu número do WhatsApp incluído na lista de permissões para o número da sandbox.

2. Seu aplicativo Flask receberá o webhook e o exibirá no terminal.

3. Ele envia uma mensagem do WhatsApp de volta para o seu número.

Você deve ver uma resposta como a que está abaixo. Você consegue adivinhar qual era a mensagem original?

Example WhatsApp message showing reversed text output

Observação: O Sandbox do Vonage Messages destina-se exclusivamente ao desenvolvimento. Para passar para a produção, você precisará criar uma Application do Vonage e usar uma verified WhatsApp Business Account (WABA).

Conclusão

Você acabou de criar um processador de mensagens do WhatsApp em tempo real em Python usando o Flask; sem WABA, sem JWTs, apenas mensagens bidirecionais instantâneas com o Vonage Sandbox. Essa configuração é ótima para validar fluxos de webhooks ou testar rapidamente alguma lógica de mensagens. Mas e se você quiser ir além?

• Confira nossa postagem sobre como conectar o WhatsApp ao ChatGPT usando Python. Você aprenderá como adicionar respostas geradas pela OpenAI ao seu aplicativo Flask e criar um assistente conversacional simples com apenas algumas linhas extras de código.

• O WhatsApp é poderoso, mas você já ouviu falar das mensagens RCS? Se seus usuários usam Android, o RCS permite enviar conteúdos avançados, como carrosséis, botões e mensagens com imagens da marca. Nosso guia de RCS em Python mostra como começar.