Sandbox Quickstart: Enviar y recibir mensajes de WhatsApp con Python

Introducción

¿Quieres enviar y recibir mensajes de WhatsApp con Python superrápido? Ya sea que estés probando un chatbot, construyendo un prototipo de mensajería o simplemente explorando la API de Messages de Vonageel Vonage WhatsApp Sandbox te permite comenzar en pocos minutos.

En este tutorial, veremos cómo enviar y recibir mensajes de WhatsApp en Python utilizando Flask, un framework web ligero ideal para experimentos rápidos con API. En no tendrás que configurar una aplicación completa de Vonage ni preocuparte por una WhatsApp Business Account (WABA). Esta es la forma más rápida de probar la API Messages API de Vonage con WhatsApp en Python.

Requisitos previos

Necesitarás las siguientes herramientas y Account para seguirnos:

• Python 3.9+

• Cuenta API de Vonage

• ngrok (para pruebas de webhooks)

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Configurar el Sandbox de WhatsApp

1. Inicie sesión en el Panel de la API de Vonage.

2. Vaya a Mensajería > Mensajes Sandbox.

3. Escanea el código QR con WhatsApp para unirte al sandbox.

4. Añade tu número de teléfono a la lista de permitidos enviando el mensaje rellenado previamente.

   1. Recibirá una respuesta en la que se le informará de que su número se ha incluido en la lista de números permitidos, algo así como "Gracias. Tu número ya está configurado en el Sandbox de la API de Messages API".

5. Tenga a mano su número de caja de arena (normalmente algo como 14157386102).

A continuación, tendremos que configurar los webhooks para que el sandbox se conecte a nuestra app Flask. Para ello, tenemos ngrok. Así que abre tu terminal de línea de comandos y ejecuta:

ngrok http 3000

Ahora tienes tu URL ngrok que se parece a:

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

Así que ahora puedes actualizar los webhooks:

• Para Inbound: https://YOUR_NGROK_URL/inbound

• Por el estado: https://YOUR_NGROK_URL/status

A continuación, haga clic en el botón "Guardar webhooks". Para obtener más ayuda, consulte Pruebas con ngrok.

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

Inicialice su proyecto Python Flask

Ahora, abre una nueva pestaña en tu terminal, mientras sigues dejando correr tu túnel ngrok. En la segunda pestaña, puedes pegar los siguientes comandos para crear tu proyecto:

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

Instalación de las dependencias necesarias

• Frasco: Un framework web ligero de Python utilizado para crear tu servidor de webhooks de WhatsApp con una configuración mínima.

• Python-dotenv: Carga variables de entorno de su archivo .env en os.environ, manteniendo información sensible como claves API fuera de su código fuente.

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

Añada sus variables de entorno

Dentro de .env tendrá que añadir el número de teléfono del Sandbox del paso anterior, así como la API_KEY y la API_SECRET que se encuentran en la página Configuración de la 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 nuestra Variables de entorno de Python para más información

Configure su entorno

Antes de comenzar a enviar mensajes, debemos cargar nuestras variables de entorno y preparar el encabezado de autenticación para la API Messages API de Vonage.

En el archivo config.py añada lo siguiente:

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 su lógica de WhatsApp

Ahora que tu proyecto está conectado con credenciales, es hora de dar vida a tu aplicación Flask. En este archivo, definirás la lógica central para enviar y recibir mensajes de WhatsApp utilizando Vonage Sandbox.

Empezarás configurando dos puntos finales: uno para gestionar los mensajes entrantes (/entrada) y otro para actualizar el estado de los mensajes (/estado). Cuando alguien envía un mensaje de WhatsApp a tu número sandbox, Vonage lo reenvía a tu servidor Flask. Tu aplicación registrará el contenido del mensaje en el terminal y, para divertirse un poco, invertirá el texto y lo enviará de vuelta como respuesta. Esto le da a tu aplicación un bucle completo de WhatsApp → Flask → WhatsApp.

Añada lo siguiente a su archivo app.py para recibir webhooks y enviar mensajes:

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)

Pruebe su aplicación

Inicie su servidor Flask en la pestaña de su terminal que no sea Angrok:

export FLASK_ENV=development
python3 app.py

Una vez finalizada la configuración:

1. Envía un mensaje desde tu número de WhatsApp permitido al número del sandbox.

2. Tu aplicación Flask recibirá el webhook y lo mostrará en el terminal.

3. Te devuelve un mensaje de WhatsApp a tu número.

Deberías ver una respuesta como la siguiente. Puedes adivinar cuál era el mensaje original?

Example WhatsApp message showing reversed text output

Nota: Vonage Messages Sandbox es sólo para desarrollo. Para pasar a producción, deberás crear una aplicación de Vonage y usar una cuenta de WhatsApp Business (WABA) verificada. cuenta verificada de WhatsApp Business Account (WABA).

Conclusión

Acabas de crear un gestor de mensajes de WhatsApp en tiempo real en Python utilizando Flask; sin WABA, sin JWT, solo mensajería bidireccional instantánea con Vonage Sandbox. Esta configuración es ideal para validar flujos de webhooks o probar rápidamente alguna lógica de mensajes. Pero, ¿y si quieres ir más allá?

• Echa un vistazo a nuestro post sobre cómo conectar WhatsApp a ChatGPT mediante Python. Aprenderás a añadir respuestas basadas en OpenAI a tu aplicación Flask y a crear un sencillo asistente conversacional con solo unas líneas de código adicionales.

• WhatsApp es potente, pero ¿has oído hablar de la mensajería RCS? Si tus usuarios están en Android, RCS te permite enviar contenido enriquecido como carruseles, botones y mensajes con imágenes de marca. Nuestra guía Python RCS te muestra cómo empezar.