OpenClaw con WhatsApp: integración completa con la API de WhatsApp Business

Requisitos previos en Meta for Developers

La API Cloud de WhatsApp de Meta requiere los siguientes elementos antes de poder configurar el canal en OpenClaw:

1. Cuenta de Meta for Developers — Una cuenta en developers.facebook.com asociada a un perfil de Facebook real.
2. App de tipo Business — Crea una aplicación de tipo «Business» en el panel de desarrolladores. Las apps de tipo «Consumer» no tienen acceso a la WhatsApp Business API.
3. Cuenta de WhatsApp Business — Un número de teléfono válido que no esté ya registrado en WhatsApp personal ni en otra cuenta Business. Puede ser un número virtual (VoIP) siempre que reciba SMS o llamadas de voz para verificación.
4. Verificación de empresa — Para enviar mensajes fuera de la ventana de 24 horas (mensajes de marketing o utilidad iniciados por la empresa), Meta requiere verificación del negocio. Para desarrollo y pruebas puedes empezar sin verificar.
5. Token de acceso permanente — Genera un token de larga duración desde el panel de la app. Los tokens de prueba de 24 horas no son aptos para un gateway OpenClaw que debe mantenerse activo continuamente.

Obtener las credenciales necesarias

Una vez creada la app de Business en Meta, dirígete a la sección WhatsApp > API Setup. Allí encontrarás los tres valores que necesita OpenClaw para el canal:

Paso 1 — Añadir el canal en openclaw.json

Edita el archivo de configuración de tu gateway OpenClaw (openclaw.json o el archivo que tengas en OPENCLAW_CONFIG_PATH) y añade el bloque de WhatsApp bajo la clave channels:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "phoneNumberId": "TU_PHONE_NUMBER_ID",
      "wabaId": "TU_WHATSAPP_BUSINESS_ACCOUNT_ID",
      "accessToken": "TU_ACCESS_TOKEN_PERMANENTE",
      "webhookVerifyToken": "CADENA_ALEATORIA_SEGURA",
      "agents": {
        "default": "mi-agente"
      }
    }
  }
}

El campo agents.default indica qué perfil de agente responde a los mensajes entrantes de este número. Puedes enrutar mensajes a agentes distintos según el número del remitente o con lógica personalizada en una skill.

Paso 2 — Exponer el gateway públicamente

Meta necesita poder enviar eventos a tu gateway mediante webhook. El gateway de OpenClaw escucha por defecto en el puerto 18789. Necesitas una URL pública HTTPS para registrar el webhook. Las opciones más comunes son:

• Servidor VPS con dominio propio — La opción recomendada para producción. Apunta un dominio o subdominio a la IP del servidor y configura un certificado SSL (Let's Encrypt).
• Cloudflare Tunnel — Crea un túnel sin exponer la IP del servidor. Ideal si OpenClaw corre en una máquina sin IP pública fija.
• ngrok — Para desarrollo y pruebas locales. La URL cambia en cada sesión a menos que uses un dominio fijo de pago.

Paso 3 — Registrar el webhook en Meta

En el panel de Meta for Developers, ve a WhatsApp > Configuration y en la sección Webhook introduce:

• Callback URL: https://tu-dominio.com/channels/whatsapp/webhook
• Verify token: el valor que pusiste en webhookVerifyToken

Haz clic en «Verify and save». Si el gateway está corriendo y los valores coinciden, Meta verificará el endpoint y comenzará a enviar eventos. Suscríbete al menos a los campos messages y message_status.

Paso 4 — Verificar la conexión

# Ver logs del gateway en tiempo real
openclaw gateway logs --follow

# Enviar un mensaje de prueba desde tu móvil al número registrado
# Deberías ver en los logs algo como:
# [whatsapp] Mensaje recibido de +34612345678: "hola"
# [mi-agente] Respondiendo...

# Comprobar el estado de los canales activos
openclaw channels status

Ventana de servicio de 24 horas

La norma más importante de WhatsApp Business API es la ventana de servicio de 24 horas: cuando un usuario envía un mensaje, se abre una ventana de 24 horas durante la cual la empresa puede responder con cualquier tipo de mensaje de texto libre. Fuera de esa ventana, solo se pueden enviar mensajes usando plantillas aprobadas por Meta.

OpenClaw gestiona esto automáticamente: si el agente intenta enviar un mensaje fuera de la ventana de 24 horas sin usar una plantilla, el canal devuelve un error y el gateway lo registra en los logs. El agente no bloquea, simplemente el mensaje no se entrega.

Tipos de mensaje que puede enviar el agente

Creación de plantillas de mensajes

Las plantillas se crean en el panel de Meta for Developers (WhatsApp > Message Templates) y pueden tardar entre unos minutos y 24 horas en aprobarse. Una vez aprobadas, el agente puede usarlas en sus respuestas. En OpenClaw puedes definir el uso de plantillas directamente en el SOUL.md del agente o en una skill específica:

# Ejemplo de skill que envía una plantilla de bienvenida
# ~/.openclaw/agents/mi-agente/skills/bienvenida.md

---
name: bienvenida-whatsapp
description: Envía la plantilla de bienvenida cuando es el primer mensaje del usuario
---

Cuando el usuario envíe su primer mensaje y no haya historial previo,
usa la herramienta send_template con los siguientes parámetros:
- template_name: "bienvenida_cliente"
- language: "es_ES"
- components: [{ type: "body", parameters: [{ type: "text", text: "{{nombre_usuario}}" }] }]

Mensajes proactivos programados

OpenClaw integra un sistema de cron que permite programar tareas periódicas. Puedes configurar el agente para que envíe mensajes de WhatsApp en momentos específicos: recordatorios, resúmenes diarios, alertas de sistema o notificaciones de negocio:

# openclaw.json — configurar tarea programada
{
  "agents": {
    "asistente": {
      "scheduled": [
        {
          "cron": "0 9 * * 1-5",
          "task": "Envía por WhatsApp al número +34612345678 el resumen de tareas pendientes del día",
          "channel": "whatsapp"
        }
      ]
    }
  }
}

Enrutamiento por número de remitente

Si conectas varios números o quieres tratar de forma distinta a diferentes usuarios, puedes crear una skill de enrutamiento que asigne el agente adecuado según el número del remitente o palabras clave en el primer mensaje:

# Skill de enrutamiento — router.md
---
name: enrutador-whatsapp
description: Decide qué agente responde según el número del remitente
---

Analiza el número de teléfono del mensaje entrante (disponible en {{sender_phone}}):
- Si empieza por +34: usa el agente "soporte-espana"
- Si empieza por +52 o +56: usa el agente "soporte-latam"
- En cualquier otro caso: usa el agente por defecto

Integración con herramientas externas

El agente de WhatsApp puede usar cualquier herramienta configurada en OpenClaw: búsqueda web, terminal, acceso a APIs externas, lectura de archivos y más. Un caso de uso habitual es el de un agente de soporte que puede consultar el estado de un pedido en tiempo real y responder directamente por WhatsApp:

Restricciones de contenido de Meta

Meta aplica su política de contenido tanto a los mensajes del agente como a las plantillas aprobadas. Están prohibidos:

• Mensajes de contenido adulto, violento o discriminatorio
• Plantillas de marketing que no incluyan opt-out claro para el receptor
• Mensajes masivos a usuarios que no hayan iniciado conversación o dado consentimiento explícito
• Contenido que infrinja derechos de autor o marcas registradas

Meta puede suspender el número de WhatsApp Business si detecta violaciones repetidas. Un número suspendido no puede recuperarse inmediatamente y el proceso de apelación puede tardar semanas.

Tipos de conversación y su coste

Meta clasifica las conversaciones en cuatro categorías, cada una con un precio diferente. El coste se cobra por conversación de 24 horas, independientemente del número de mensajes intercambiados dentro de esa ventana:

Variación por país

Los precios anteriores son orientativos para España y mercados europeos. Meta ajusta sus tarifas por país de destino del usuario (no del número Business). Los mercados latinoamericanos como México, Argentina o Colombia tienen tarifas generalmente inferiores a Europa. La tabla de precios oficial de Meta se actualiza periódicamente y está disponible en developers.facebook.com/docs/whatsapp/pricing .

Coste total estimado

Para un asistente de soporte con 2.000 conversaciones mensuales (1.000 gratuitas de servicio + 500 de utilidad + 500 de marketing en España):

• Conversaciones de servicio (1.000 gratuitas + 0 exceso en este ejemplo): 0 €
• Conversaciones de utilidad (500 × 0,04 €): 20 €
• Conversaciones de marketing (500 × 0,08 €): 40 €
• Coste de la API de OpenClaw: 0 € (MIT, autoalojado)
• Coste del LLM (aparte): depende del modelo y proveedor elegido
• Total mensual estimado del canal WhatsApp: ~60 €/mes