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

terminal
# 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:

terminal
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:

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:

Markup de proveedores:

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

Requisitos para usar la API

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

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.