--- title: WhatsApp Cloud API: Tutorial Completo para Desarrolladores (2026) description: Tutorial paso a paso de WhatsApp Cloud API: setup, autenticación, envío de mensajes, templates, webhooks y código en Python y Node.js. date: 2026-05-17 author: Victor Villalobos locale: es source: https://www.zavu.dev/es/blog/whatsapp-cloud-api-tutorial tags: WhatsApp, API, Tutorial, Desarrolladores --- # WhatsApp Cloud API: Tutorial Completo para Desarrolladores (2026) > **Nota (noviembre 2026):** Este artículo usa paquetes del SDK de Zavu para Python, Ruby, Go o PHP que ya no se mantienen, así que algunos ejemplos pueden no funcionar tal como se muestran. El SDK mantenido es el de TypeScript (`@zavudev/sdk`). Desde cualquier otro lenguaje, llama a la API REST directamente o genera un cliente desde la especificación OpenAPI. Consulta [SDKs y alternativas](https://www.zavu.dev/docs/sdks/overview). La **WhatsApp Cloud API** es la API oficial de Meta para enviar y recibir mensajes en WhatsApp Business, alojada por la propia Meta (no requiere hospedar nada por tu cuenta). Este tutorial muestra cómo empezar de cero hasta el primer mensaje enviado, con código real en Python y Node.js. ## Qué es la WhatsApp Cloud API La Cloud API reemplazó a la antigua "On-Premises API" en 2022. Diferencias: | Cloud API (actual) | On-Premises (legacy) | |---|---| | Hospedada por Meta | Tú la hospedas | | Setup en horas | Setup en semanas | | Sin servidor que mantener | VPS + Docker + mantenimiento | | Misma performance | Más compleja | | Recomendada para 99% de casos | Solo casos enterprise específicos | **No necesitas lidiar directamente con la Cloud API.** Proveedores oficiales (BSPs) como [Zavu](https://www.zavu.dev/es) abstraen la complejidad. Pero es importante entender qué hay debajo. ## Prerrequisitos Antes de empezar: 1. Cuenta **Meta Business Manager** (gratuita, crear en [business.facebook.com](https://business.facebook.com)) 2. Un **número de teléfono** que **NO** esté activo en WhatsApp normal ni WhatsApp Business app 3. Un **website** verificado para el negocio 4. Un servidor con HTTPS para webhooks (Vercel, AWS, Cloudflare Workers) ## Camino 1: Directo por Meta (complejo) Si quieres ir directo por Meta sin BSP: 1. Registra tu **App** en developers.facebook.com 2. Agrega el producto **WhatsApp** 3. Activa cuenta WhatsApp Business y agrega el número 4. Genera un **token temporal** (24h) para pruebas o uno permanente vía System User 5. Primer request: ```bash curl -X POST \ "https://graph.facebook.com/v18.0//messages" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "525511223344", "type": "template", "template": { "name": "hello_world", "language": { "code": "en_US" } } }' ``` Este camino **funciona**, pero todavía necesitas: - Aprobar templates manualmente en Meta Business Suite - Renovar tokens - Implementar webhooks con verificación de firma - Manejar errores y retries - Migrar de número si Meta te limita ## Camino 2: Vía BSP oficial (recomendado) Los BSPs oficiales resuelven el 90% de la complejidad. Así con Zavu: ### 1. Cuenta gratis [zavu.dev/es](https://dashboard.zavu.dev) — sin tarjeta de crédito. ### 2. Conectar Meta Business En el dashboard, **Add WhatsApp Sender** → flujo OAuth con Meta. Autorizas a Zavu como BSP. 5 minutos. ### 3. Instalar SDK ```bash # Node.js npm install @zavudev/sdk ``` ```bash # Python: no hay SDK de Zavu; llama a la API REST con requests pip install requests ``` ### 4. Primer mensaje **Node.js:** ```typescript import Zavu from "@zavudev/sdk" const zavu = new Zavu({ apiKey: process.env.ZAVUDEV_API_KEY }) const result = await zavu.messages.send({ to: "+525511223344", channel: "whatsapp", text: "¡Hola! Primer mensaje vía Zavu 🎉" }) console.log(result.message.id, result.message.status) ``` **Python (API REST con requests):** ```python import os import requests response = requests.post( "https://api.zavu.dev/v1/messages", headers={"Authorization": f"Bearer {os.environ['ZAVUDEV_API_KEY']}"}, json={ "to": "+525511223344", "channel": "whatsapp", "text": "¡Hola! Primer mensaje vía Zavu", }, timeout=10, ) response.raise_for_status() message = response.json()["message"] print(message["id"], message["status"]) ``` ## Mensajes libres vs templates La **ventana de 24 horas** es central: - **Dentro de 24h** después que el cliente te respondió: cualquier mensaje (texto, mídia, botones) - **Fuera de 24h**: solo templates aprobados ### Enviar template ```typescript await zavu.messages.send({ to: "+525511223344", channel: "whatsapp", messageType: "template", content: { templateId: "tpl_pedido_confirmado", templateVariables: { "1": "Juan", "2": "12345", "3": "$89.90 MXN" } } }) ``` Categorías de templates: - **Utility** (transaccional) — confirmaciones, recordatorios — $0.60 MXN - **Authentication** (OTP) — códigos — $0.40 MXN - **Marketing** (promocional) — ofertas — $3.20 MXN ## Media rica ```typescript // Imagen await zavu.messages.send({ to: "+525511223344", channel: "whatsapp", messageType: "image", text: "¡Mira nuestro nuevo producto!", content: { mediaUrl: "https://ejemplo.com/producto.jpg" } }) // Documento PDF await zavu.messages.send({ to: "+525511223344", channel: "whatsapp", messageType: "document", content: { mediaUrl: "https://ejemplo.com/factura.pdf", filename: "factura.pdf" } }) // Botones interactivos await zavu.messages.send({ to: "+525511223344", channel: "whatsapp", messageType: "buttons", text: "¿Cómo podemos ayudarte?", content: { buttons: [ { id: "comprar", title: "Quiero comprar" }, { id: "dudas", title: "Resolver dudas" }, { id: "rastreo", title: "Rastrear pedido" } ] } }) ``` ## Recibiendo mensajes (webhooks) Configura endpoint HTTPS en Zavu Dashboard. Cada mensaje recibido genera un POST: ```typescript // app/api/whatsapp-webhook/route.ts (Next.js) import crypto from "node:crypto" // X-Zavu-Signature: t=,v2= (v1= on older webhooks) // v2 = HMAC_SHA256(secret, "{t}.{body}"), v1 = HMAC_SHA256(secret, body) function verifySignature(rawBody: string, header: string | null): boolean { const secret = process.env.ZAVU_WEBHOOK_SECRET if (!header || !secret) return false const parts: Record = {} for (const piece of header.split(",")) { const i = piece.indexOf("=") if (i > 0) parts[piece.slice(0, i)] = piece.slice(i + 1) } const t = Number(parts.t) if (!Number.isFinite(t)) return false const age = Math.floor(Date.now() / 1000) - t if (age > 300 || age < -60) return false const received = parts.v2 ?? parts.v1 if (!received) return false const signed = parts.v2 ? `${t}.${rawBody}` : rawBody const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex") return expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)) } export async function POST(req: Request) { // Verifica la firma sobre el cuerpo crudo, antes de parsearlo const rawBody = await req.text() if (!verifySignature(rawBody, req.headers.get("x-zavu-signature"))) { return new Response("Unauthorized", { status: 401 }) } const event = JSON.parse(rawBody) switch (event.type) { case "message.inbound": console.log(`Cliente ${event.data.from}: ${event.data.text}`) break case "message.delivered": console.log(`Mensaje ${event.data.messageId} entregado`) break case "message.read": console.log(`Mensaje ${event.data.messageId} leído`) break } return new Response("ok") } ``` ## Errores comunes **`131056` - Number not registered**: el número no está habilitado en WhatsApp Business. Verifica en Meta Business Suite. **`131005` - Access denied**: token incorrecto o expirado. Usa System User token (permanente) en producción. **`132000` - Template not approved**: template en revisión todavía. Espera o usa texto libre en ventana de 24h. **Mensaje no llega**: el destinatario puede no tener WhatsApp o bloqueó tu número. Verifica con webhook `message.failed`. **Webhook no responde en 2s**: Meta reintenta hasta 3 veces. Estructura tu endpoint para responder rápido y procesar async. ## Costos de WhatsApp Cloud API (México) Meta cobra **por conversación de 24h iniciada**, no por mensaje. Precios MX 2026: | Categoría | Costo Meta | |---|---| | Utility (transaccional) | ~$0.60 MXN | | Authentication (OTP) | ~$0.40 MXN | | Marketing | ~$3.20 MXN | | Service (cliente inicia) | Gratis | Los BSPs agregan costo de plataforma. Zavu pasa el costo de Meta **sin markup** — [precios completos](/es/pricing). ## Recursos relacionados - [API de WhatsApp: guía para desarrolladores](/es/blog/api-whatsapp-desarrolladores) - [Cómo crear un chatbot en WhatsApp](/es/blog/como-crear-chatbot-whatsapp) - [Construye un agente de IA para WhatsApp con FastAPI](/es/blog/whatsapp-ai-agents-fastapi) - [Documentación técnica](https://www.zavu.dev/docs/guides/whatsapp/overview) - [Zavu vs Twilio](/es/vs/twilio) ## Conclusión La WhatsApp Cloud API reemplaza el app de celular por un endpoint REST programable. Puedes ir directo por Meta (más trabajo, más control) o usar un BSP oficial como Zavu (más simple, sin gestionar tokens, templates ni migraciones). La API te da todo lo que el app no tiene: múltiples agentes, integración CRM, automatización de templates, webhooks y media rica. Empieza con este tutorial — en 30 minutos envías tu primer mensaje.