0) ¿Qué es la WhatsApp Cloud API?

Es la versión en la nube (hosteada por Meta) de la API oficial de WhatsApp Business.
Ventajas: sin servidores propios, mayor estabilidad, cumplimiento legal y escalabilidad.

1) Requisitos previos (checklist rápido)

Cuentas y verificaciones

Cuenta de Facebook/Meta personal.
Acceso a Meta Business Manager y crear tu Empresa.
Verificación de empresa iniciada o hecha (recomendado para producción).
Nombre visible de WhatsApp (Display Name) que coincida con tu marca/negocio.
Dominio web propio (para verificación si aplica).

Líneas y configuración

Número de teléfono exclusivo para WhatsApp API (no puede usarse en WhatsApp normal al mismo tiempo).
Posibilidad de recibir SMS o llamada a ese número para verificarlo.
Plantillas (templates) para mensajes proactivos creadas y aprobadas.
Webhook (URL pública + verify token) si vas a recibir mensajes/eventos en tu sistema.
Token de acceso (temporal para pruebas, permanente para producción).

2) Crear y preparar tu empresa en Meta Business Manager

Ingresa a business.facebook.com → “Crear cuenta de empresa”.
Completa datos legales reales (nombre, dirección, teléfono, sitio web).
En Configuración del negocio → Centro de seguridad → inicia Verificación de Empresa.
- Sube documentos y verifica el dominio (opcional pero recomendado).
- Nota: para pruebas básicas puedes comenzar sin verificación, pero para producción y plantillas te lo pedirán.

3) Crear la App en Meta for Developers y añadir WhatsApp

Ve a developers.facebook.com → “Mis Apps” → Crear app.
Tipo de app: Business (recomendado para Cloud API).
Dentro del panel de la app, en Agregar productos, selecciona WhatsApp y haz clic en Configurar.
Te aparecerá un número de prueba de Meta y un token temporal para empezar a probar de inmediato.

Con ese número + token temporal puedes enviar mensajes de prueba a números verificados (opt-in) desde el mismo panel. Sirve para validar la integración antes de usar tu número real.

4) Vincular tu número propio a la WhatsApp Business Account (WABA)

En el panel de WhatsApp (WhatsApp Manager) → Phone Numbers → Add Phone Number.
Completa:
- Nombre visible (Display Name) coherente con tu empresa.
- Categoría del negocio.
- Descripción breve.
Verifica el número:
- Elige SMS o llamada para recibir el código.
- Importante: ese número NO debe estar activo en WhatsApp normal. Si lo está, desvincúlalo de WhatsApp/WA Business antes.

Al aprobarse, tu número queda asociado a la WABA y pueden gestionarse plantillas, límites, métricas, etc.

5) Generar token permanente (producción)

El token temporal expira. Para producción, crea un System User y un Token de larga duración:

En Business Manager → Configuración del negocio → Usuarios del sistema → “Agregar”.
Crea un usuario del sistema → Asigna activos: tu App y tu WABA.
Otorga permisos: whatsapp_business_messaging, whatsapp_business_management.
Genera token para ese System User (elige la App) → Token permanente.
Guarda el token en un lugar seguro (usa variables de entorno en tu backend).

6) Configurar Webhook (recibir mensajes y eventos)

Si quieres que tu sistema reciba eventos (mensajes entrantes, estados, etc.):

En el Dashboard de tu App → WhatsApp → Configuration:
- Callback URL: tu endpoint público (HTTPS).
- Verify token: una cadena secreta que defines en tu servidor.
Desde tu backend, responde al challenge de verificación (GET hub.mode, hub.verify_token, hub.challenge).
Suscríbete a los campos: messages, message_template_status_update, message_status, etc.

Con el webhook activo, podrás ver mensajes entrantes, delivery receipts, estados, etc.

7) Crear plantillas (templates) para mensajes proactivos

Para escribirle a un usuario sin que te haya escrito primero o cuando la 24h ya pasó, debes usar plantillas aprobadas:

WhatsApp Manager → Message Templates → “Create”.
Elige categoría: Marketing, Utility (notificaciones), Authentication (OTP).
Escribe el contenido con variables si necesitas (ej: {{1}}).
Envía a revisión (suele demorar minutos/horas).
Una vez aprobada, puedes usar esa plantilla desde la API.

Dentro de 24h desde el último mensaje del cliente puedes enviar mensajes de sesión (libres). Fuera de 24h, solo con plantillas aprobadas.

8) Probar envíos (cURL / Postman / código)

a) Enviar mensaje de texto (sesión dentro de 24h)

b) Enviar plantilla aprobada

curl -X POST "https://graph.facebook.com/v20.0/<PHONE_NUMBER_ID>/messages" \

  -H "Authorization: Bearer <ACCESS_TOKEN>" \

  -H "Content-Type: application/json" \

  -d '{

    "messaging_product": "whatsapp",

    "to": "<NUMERO_DESTINO_EJ_573001112233>",

    "type": "template",

    "template": {

      "name": "bienvenida_2025",

      "language": { "code": "es" },

      "components": [

        {

          "type": "body",

          "parameters": [

            { "type": "text", "text": "Kenis" },

            { "type": "text", "text": "AutoSend Pro" }

          ]

        }

      ]

    }

  }'

Variables: en el ejemplo, si tu plantilla tiene Hola {{1}}, bienvenido a {{2}}, pasas "Kenis" y "AutoSend Pro".

c) Nota sobre identificadores

<PHONE_NUMBER_ID>: lo ves en tu WhatsApp Manager → Phone Numbers.
<ACCESS_TOKEN>: usa el permanente en producción.
<WABA_ID>: ID de tu cuenta de WhatsApp Business.

9) Límites, reputación y buenas prácticas

Ventana de 24 horas: si el cliente te escribe, tienes 24h para responder sin plantilla.
Plantillas: Úsalas para iniciar conversación o retomar fuera de 24h.
Opt-in: Asegúrate de tener consentimiento (evita reportes).
Reputación: Mensajes útiles, no spam. Contenidos claros y coherentes con la plantilla.
Verificación de empresa: mejora límites y acceso a features.
No reciclar el número en WhatsApp personal: úsalo solo para la API.

10) Integración con AutoSend Pro

Si vas a operar con AutoSend:

Puedes usar dos modos:
1. API Propia de AutoSend (flexible, útil para flujos mixtos).
2. API oficial de Meta (Cloud API) para entregabilidad estable y cumplimiento.
AutoSend gestiona plantillas, segmentación, reportes y soporte remoto integrado.
Nosotros cuidamos la entregabilidad, límites y buenas prácticas para que no sufras bloqueos.

11) Errores comunes y solución rápida

No llega el SMS de verificación → verifica que el número no esté activo en WhatsApp/WA Business. Prueba llamada.
403 / permisos → revisa permisos del System User y que el token sea el correcto.
400 / template invalid → el nombre, idioma o variables no coinciden exactamente con la plantilla aprobada.
Webhook no verifica → devuelve hub.challenge tal cual y usa el verify_token exacto.
Envío fuera de 24h sin plantilla → usa template aprobado.

12) Checklist final de producción

Empresa verificada (recomendado).
Número vinculado y verificado a la WABA.
Token permanente activo.
Webhook configurado y suscrito a eventos.
Plantillas aprobadas para casos fuera de 24h.
Lógica de opt-in y gestión de bajas (cumplimiento).
Monitoreo de reputación y métricas.

Whatsapp Marketing