API de WhatsApp: Guía Completa para Desarrolladores (2026)

Si eres developer buscando "API de WhatsApp" en español, hay tres caminos: la WhatsApp Cloud API oficial de Meta, la WhatsApp Business API vía BSP (proveedor oficial) y las APIs no oficiales (que deberías evitar). Esta guía explica cada una y muestra código real para el camino recomendado.

Los 3 caminos para usar la API de WhatsApp en 2026

1. WhatsApp Cloud API directa (Meta)

• Hospedada por Meta
• Acceso directo vía Graph API
• Tú manejas tokens, templates, webhooks
• Buena para: equipos con DevOps fuerte

2. WhatsApp Business API vía BSP (recomendado)

• Proveedores oficiales como Zavu, Twilio, MessageBird
• Abstraen complejidad (tokens, retries, templates)
• SDK oficial en varios lenguajes
• Buena para: 99% de los casos

3. APIs no oficiales (no uses)

• Librerías que hacen reverse engineering de WhatsApp Web
• Funcionan hasta que Meta las bloquea
• Sin soporte, sin garantía, sin sello verde
• Pueden banear tu número permanentemente

Empezar con la API de WhatsApp en 5 minutos

El camino más rápido es vía BSP oficial. Aquí con Zavu:

1. Cuenta gratis

Crea en zavu.dev. Sin tarjeta de crédito.

2. Conectar Meta Business

En el dashboard, Add WhatsApp Sender → OAuth con Meta → autoriza Zavu como BSP. ~5 minutos.

3. Instalar SDK

bash
# Node.js / TypeScript
npm install @zavudev/sdk

# Python
pip install zavudev

4. Primer mensaje

Node.js:

typescript
import Zavu from "@zavudev/sdk"
const zavu = new Zavu({ apiKey: process.env.ZAVU_API_KEY })

const result = await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  text: "¡Hola! Primera mensaje vía API."
})

console.log(result.message.id, result.message.status)

Python:

python
from zavudev import Zavu
import os

zavu = Zavu(api_key=os.environ["ZAVU_API_KEY"])

result = zavu.messages.send(
    to="+525511223344",
    channel="whatsapp",
    text="¡Hola! Primer mensaje vía API."
)

print(result.message.id, result.message.status)

cURL:

bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+525511223344",
    "channel": "whatsapp",
    "text": "¡Hola!"
  }'

Tipos de mensajes que acepta la API

Texto plano

typescript
await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  text: "Tu pedido #12345 fue confirmado."
})

Media (imagen, video, documento)

typescript
// Imagen
await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  messageType: "image",
  text: "Vista del producto",
  content: { mediaUrl: "https://ejemplo.com/img.jpg" }
})

// PDF
await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  messageType: "document",
  content: {
    mediaUrl: "https://ejemplo.com/factura.pdf",
    filename: "factura.pdf"
  }
})

Botones interactivos

typescript
await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  messageType: "buttons",
  text: "¿Cómo podemos ayudarte?",
  content: {
    buttons: [
      { id: "rastreo", title: "Rastrear pedido" },
      { id: "soporte", title: "Hablar con humano" },
      { id: "compras", title: "Ver catálogo" }
    ]
  }
})

Lista (hasta 10 opciones)

typescript
await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  messageType: "list",
  text: "Elige una opción:",
  content: {
    listButton: "Ver",
    sections: [{
      title: "Más vendidos",
      rows: [
        { id: "p1", title: "Producto A", description: "$99" },
        { id: "p2", title: "Producto B", description: "$149" }
      ]
    }]
  }
})

Template (fuera de la ventana de 24h)

typescript
await zavu.messages.send({
  to: "+525511223344",
  channel: "whatsapp",
  messageType: "template",
  content: {
    templateId: "tpl_pedido_confirmado",
    templateVariables: { "1": "Juan", "2": "12345" }
  }
})

La regla de la ventana de 24 horas

Meta tiene una regla estricta:

• Dentro de 24h después que el cliente te respondió: puedes mandar cualquier tipo de mensaje libre.
• Fuera de 24h: solo templates aprobados.

Por eso es crítico crear templates antes de necesitarlos:

Dashboard Zavu → Templates → Create

Categoría: Utility, Marketing, Authentication

Enviar a aprobación de Meta (24-48h)

Usar el templateId en código

Recibiendo mensajes (webhooks)

Configura URL de webhook en el dashboard:

typescript
// Endpoint Next.js
export async function POST(req: Request) {
  const event = await req.json()

  if (event.type === "message.inbound") {
    console.log("Cliente:", event.message.from)
    console.log("Texto:", event.message.text)

    await zavu.messages.send({
      to: event.message.from,
      channel: "whatsapp",
      text: "¡Recibí tu mensaje! Pronto respondo."
    })
  }

  return new Response("ok")
}

Eventos disponibles:

• message.inbound — cliente envió mensaje
• message.delivered — mensaje entregado
• message.read — cliente leyó
• message.failed — falló (con razón)
• conversation.new — primera conversación
• template.status_changed — template aprobado/rechazado

Precios de la API de WhatsApp por país

Meta cobra por conversación de 24h, no por mensaje. Precios para LATAM:

País	Marketing	Utility	Authentication	Service

🇲🇽 México	$3.20 MXN	$0.60 MXN	$0.40 MXN	Gratis
🇦🇷 Argentina	ARS variable	bajo	bajo	Gratis
🇨🇱 Chile	$190 CLP	$80 CLP	$60 CLP	Gratis
🇨🇴 Colombia	$750 COP	$300 COP	$200 COP	Gratis
🇵🇪 Perú	S/0.70	S/0.30	S/0.20	Gratis
🇪🇸 España	€0.18	€0.07	€0.04	Gratis
🇺🇸 USA	$0.025	$0.015	$0.005	Gratis

Markup de proveedores:

• Zavu: 0%
• Twilio: 5-20%
• MessageBird: $600+ setup fee + plataforma

Requisitos para usar la API

Meta Business Manager verificado (gratis)

Número de teléfono que no esté en otro WhatsApp

Sitio web verificado para el negocio

Templates aprobados (para iniciar conversaciones)

Política de privacidad publicada

RFC (México) o equivalente fiscal por país

Errores comunes y soluciones

Error 131005 - Access denied: token inválido o expirado. En producción, usa System User token (permanente).Error 131056 - Number not registered: número no habilitado en WhatsApp Business. Verifica en Meta Business Suite.Error 132000 - Template not approved: template en revisión todavía. Espera o usa texto libre en ventana de 24h.Error 470 - Re-engagement required: pasaste la ventana de 24h. Usa template para reabrir.Webhook no responde: tu endpoint debe ser HTTPS válido y responder 200 en < 2s. Usa Cloudflare Workers o Vercel.Mensaje "queued" y no llega: el cliente puede no tener WhatsApp, haberte bloqueado o el número es inválido. Verifica con webhook message.failed.

Comparativo: Cloud API directa vs BSP

Cloud API directa	Vía Zavu (BSP)

Tiempo de setup	1-2 semanas	30 minutos
Verificación business	Lo haces tú	Te guían
Renovación de tokens	Tú manejas	Automática
Aprobación de templates	Manual en Business Suite	API + dashboard
Webhooks firmados	Lo implementas tú	SDK valida
Multi-canal (SMS + WhatsApp)	Solo WhatsApp	Todo unificado
Retries automáticos	Lo implementas tú	Incluido
SDK oficial	No (solo REST)	Sí (TS, Py, Go, Ruby, PHP)

Para 99% de los casos, ir vía BSP ahorra semanas de trabajo.

Recursos relacionados

• WhatsApp Cloud API tutorial
• Cómo crear un chatbot en WhatsApp
• Documentación técnica completa
• Agentes de IA para WhatsApp
• Zavu vs Twilio para WhatsApp

Conclusión

La API de WhatsApp en 2026 te da control total sobre la comunicación con clientes — desde notificaciones automáticas hasta agentes de IA que atienden 24h. El camino más rápido y seguro es usar un BSP oficial como Zavu: 5 minutos para empezar, SDK en tu lenguaje, precio sin markup y soporte real. Empieza con el plan gratuito de 2.000 mensajes y escala cuando crezcas.