Ir al contenido

Enviar WhatsApp desde Python ​

ZAPPIO es una API HTTP + JSON: en Python basta requests. Envías el mensaje con un POST y recibes las respuestas de tus clientes por webhook, aquí con Flask (en Django o FastAPI es igual: lee el cuerpo crudo y verifica la firma).

Antes de empezar necesitas una cuenta, una instancia conectada y una API key: sigue el Quickstart (pasos 1 a 7). Al terminar tendrás estas variables:

bash
export ZAPPIO_API_URL="https://zappio.cloud"
export ZAPPIO_API_KEY="zp_..."
export ZAPPIO_INSTANCE="ins_..."

Enviar un mensaje ​

python
# zappio.py
import os

import requests

API = os.environ["ZAPPIO_API_URL"] + "/api/v1"


def send_whatsapp(to, text, idempotency_key=None):
    """Queues a WhatsApp text and returns the message (id msg_..., status "queued")."""
    headers = {"Authorization": "Bearer " + os.environ["ZAPPIO_API_KEY"]}
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    res = requests.post(
        API + "/messages",
        headers=headers,
        json={"instance": os.environ["ZAPPIO_INSTANCE"], "to": to, "type": "text", "text": text},
        timeout=15,
    )
    body = res.json()
    if not res.ok:
        raise RuntimeError(body["error"]["code"] + ": " + body["error"]["message"])
    return body["data"]
python
from zappio import send_whatsapp

msg = send_whatsapp("5215500000000", "Hola desde Python 👋", "saludo-1")
print(msg["id"], msg["status"])  # msg_... queued
  • to es el número con código de país (en México, 52 y el número; los espacios y el + se ignoran).
  • La API responde 202 Accepted con status: "queued": el envío ocurre en segundo plano. Sigue el estado con los webhooks o con GET /api/v1/messages/{id}.
  • Idempotency-Key hace seguros los reintentos (Idempotencia); los errores están en Errores.

Recibir respuestas con Flask ​

Registra en el panel un webhook con la URL de tu servidor y el evento message.received. Cada petición viene firmada; la función de verificación (sin dependencias, probada contra el vector de prueba):

py
import hashlib
import hmac
import json
import sys
import time


def verify_zappio_webhook(secret, timestamp, signature_header, raw_body, now=None, tolerance=300):
    """Verifies a ZAPPIO webhook. raw_body must be the exact bytes received (bytes or str). No dependencies."""
    now = int(time.time()) if now is None else now
    # Reject stale or future timestamps: a captured request cannot be replayed later.
    if not timestamp.isascii() or not timestamp.isdigit() or abs(now - int(timestamp)) > tolerance:
        return False

    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
    expected = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)  # constant-time comparison


# --- Self-check against the shared test vector: python verify_webhook.py webhook-signature-vector.json
if __name__ == "__main__" and len(sys.argv) > 1:
    with open(sys.argv[1], encoding="utf-8") as handle:
        vector = json.load(handle)
    failed = 0
    for case in vector["cases"]:
        ok = verify_zappio_webhook(case["secret"], case["timestamp"], case["signature"], case["body"], case["now"], vector["tolerance_seconds"])
        if ok != case["valid"]:
            print("FAIL python: " + case["name"], file=sys.stderr)
            failed += 1
    if failed == 0:
        print("python: %d cases OK" % len(vector["cases"]))
    sys.exit(0 if failed == 0 else 1)
python
# app.py
import json
import os

from flask import Flask, request

from verify_webhook import verify_zappio_webhook
from zappio import send_whatsapp

app = Flask(__name__)


@app.post("/webhooks/zappio")
def zappio_webhook():
    ok = verify_zappio_webhook(
        os.environ["ZAPPIO_WEBHOOK_SECRET"],  # el secreto zpwh_... de tu endpoint
        request.headers.get("X-Zappio-Timestamp", ""),
        request.headers.get("X-Zappio-Signature", ""),
        request.get_data(),  # el cuerpo crudo, tal como llegó
    )
    if not ok:
        return "", 401

    event = json.loads(request.get_data())
    if event["type"] == "message.received":
        msg = event["data"]["message"]
        if msg["group_id"] is None and msg["type"] == "text":
            # En producción, mándalo a una cola (Celery, RQ...) y responde de inmediato.
            send_whatsapp(msg["from"], "Recibimos tu mensaje, te respondemos pronto.")
    return "", 204
  • Responde un 2xx en menos de 10 segundos (reintentos y duplicados).
  • Un mismo evento puede llegar más de una vez: deduplica por event["id"].

Siguientes pasos ​

Pruébalo gratis

Crea tu cuenta: 50 mensajes de prueba, sin tarjeta y sin límite de días.