---
title: API de WhatsApp: Guía Completa para Desarrolladores (2026)
description: Todo sobre la API de WhatsApp en 2026: Cloud API vs Business API vs no oficial, precios, requisitos y ejemplos en Python, Node.js y cURL.
date: 2026-05-17
author: Victor Villalobos
locale: es
source: https://www.zavu.dev/es/blog/api-whatsapp-desarrolladores
tags: WhatsApp, API, Desarrolladores, Tutorial
---

# 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](https://www.zavu.dev/es), 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](https://www.zavu.dev/es). 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:

1. Dashboard Zavu → **Templates** → **Create**
2. Categoría: Utility, Marketing, Authentication
3. Enviar a aprobación de Meta (24-48h)
4. 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

1. **Meta Business Manager** verificado (gratis)
2. **Número de teléfono** que no esté en otro WhatsApp
3. **Sitio web** verificado para el negocio
4. **Templates** aprobados (para iniciar conversaciones)
5. **Política de privacidad** publicada
6. **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](/es/blog/whatsapp-cloud-api-tutorial)
- [Cómo crear un chatbot en WhatsApp](/es/blog/como-crear-chatbot-whatsapp)
- [Documentación técnica completa](https://docs.zavu.dev/quickstart)
- [Agentes de IA para WhatsApp](/es/ai-agents)
- [Zavu vs Twilio para WhatsApp](/es/vs/twilio)

## 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](/es/whatsapp-business-api): 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.