Apariencia
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_... queuedtoes el número con código de país (en México,52y el número; los espacios y el+se ignoran).- La API responde
202 Acceptedconstatus: "queued": el envío ocurre en segundo plano. Sigue el estado con los webhooks o conGET /api/v1/messages/{id}. Idempotency-Keyhace 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
2xxen menos de 10 segundos (reintentos y duplicados). - Un mismo evento puede llegar más de una vez: deduplica por
event["id"].
Siguientes pasos
- Multimedia: con
requests.post(..., files={"file": ...})envías imágenes y documentos. - Encuestas: recordatorios de citas con confirmación.
- Notificaciones de pedidos y bot de respuestas.
Pruébalo gratis
Crea tu cuenta: 50 mensajes de prueba, sin tarjeta y sin límite de días.