Por Antonio José Soler Morillas · Imorillas · Junio 2026

Hace unos meses monté un chatbot con inteligencia artificial para la web de una peluquería cliente. Funcionaba bien: la clienta preguntaba por servicios, precios u horarios y el bot respondía en segundos. Pero faltaba algo. La mayoría de las clientas no preguntaban por la web. Preguntaban por WhatsApp.

Este artículo documenta el proceso completo de conectar ese chatbot —construido en PHP con la API de Gemini de Google— a WhatsApp Business. Incluye los errores que cometí, cómo los resolví, y todo lo que necesitas saber si quieres hacer lo mismo para tu negocio o el de un cliente.

El punto de partida: qué teníamos

El chatbot web existente funcionaba así:

La usuaria escribe un mensaje en la web
El frontend lo envía a un archivo PHP (chat-server.php)
El PHP llama a la API de Gemini con un system prompt personalizado y el historial de conversación
Gemini responde y el PHP devuelve el texto al frontend

El bot tenía comportamientos especiales definidos mediante etiquetas ([OPEN_BOOKING], [ESCALADO_HUMANO]) que el PHP detectaba para ejecutar acciones: abrir un enlace, derivar al equipo humano, etc.

El objetivo era que este mismo bot respondiera en WhatsApp cuando una clienta escribiera al número de la peluquería.

Qué es la WhatsApp Cloud API (y qué no es)

Antes de empezar, lo más importante: la WhatsApp Cloud API no tiene nada que ver con la app de WhatsApp que usas en el móvil.

Existen tres productos distintos:

Producto	Para qué sirve	Límite
WhatsApp Messenger	Uso personal	No permite uso comercial
WhatsApp Business App	Pequeños negocios	Manual, sin automatización real
WhatsApp Business Platform (Cloud API)	Automatización, bots, envío masivo	Sin límite práctico

La Cloud API es la que necesitas si quieres automatizar mensajes. Funciona así: tú haces peticiones HTTP a los servidores de Meta, y ellos se encargan de entregar los mensajes. No necesitas infraestructura propia.

Importante: desde octubre de 2025, la versión “on-premise” fue descontinuada. La Cloud API es la única opción para nuevas integraciones.

Arquitectura final del sistema

Antes de entrar en los pasos, aquí está la arquitectura completa:

Cliente (WhatsApp) 
    → escribe mensaje
Meta Cloud API 
    → webhook POST
whatsapp-webhook.php
    → procesa mensaje
Gemini API (IA)
    → genera respuesta
whatsapp-webhook.php
    → envía respuesta
Meta Cloud API
    → entrega mensaje
Cliente (WhatsApp)

En paralelo, cuando la clienta pide cita:

whatsapp-webhook.php → plantilla aprobada → WhatsApp del equipo humano

Paso 1: Configurar Meta Business y crear la app

Necesitas tres cosas en Meta:

1. Cuenta de Meta Business verificada Si ya gestionas páginas de Facebook o campañas en Meta Ads, probablemente la tienes. Está en business.facebook.com.

La verificación de negocio requiere subir documentación oficial (CIF, escrituras o factura de suministros) y esperar entre 2 y 10 días. Sin ella, estás limitado a 250 conversaciones diarias.

2. Cuenta de desarrollador en Meta En developers.facebook.com, registro gratuito con tu cuenta de Facebook.

3. Una app de tipo “Business” En el panel de desarrolladores: Mis Apps → Crear App → Business. Dentro de la app, añades el producto WhatsApp.

Paso 2: Registrar el número de teléfono

Este fue el primer obstáculo. El número que quieras usar para el bot no puede estar activo en ninguna app de WhatsApp (ni personal ni Business App). Si lo está, tienes dos opciones:

Migrar el número: elimina la cuenta de WhatsApp de ese número. Tardarás unos minutos y perderás el historial de chats.
Usar un número nuevo: lo más limpio para producción. Una SIM barata o un número virtual.

Una vez que el número está libre, lo registras en el panel de Meta y recibes un código de verificación por SMS o llamada. Cuidado: si fallas varias veces seguidas, Meta te bloquea temporalmente (“You have requested a verification code too many times”). Hay que esperar horas antes de intentarlo de nuevo.

Paso 3: El webhook — el corazón de todo

El webhook es el archivo PHP de tu servidor al que Meta envía los mensajes entrantes. Es la pieza más importante de la integración.

Cómo funciona la verificación del webhook

Cuando registras tu webhook en Meta, lo primero que hace es enviarte una petición GET con tres parámetros:

hub.mode = subscribe
hub.verify_token = [el token que tú definiste]
hub.challenge = [un número aleatorio]

Tu servidor debe responder con ese número aleatorio. Si lo hace correctamente, Meta confirma el webhook.

Aquí encontré un error que nos tuvo un buen rato: el .htaccess de un sitio Astro estático no pasaba los parámetros GET al PHP. La solución fue añadir esta línea en el .htaccess antes del bloque de enrutamiento de Astro:

RewriteRule ^whatsapp-webhook\.php$ - [L]

Esto le dice a Apache que deje pasar las peticiones a ese archivo sin reescribir la URL.

Otro error habitual: el .env

El webhook carga las credenciales desde un archivo .env ubicado fuera del webroot. Si el servidor tiene el document root en httpdocs/dist/, el .env va en httpdocs/ (un nivel por encima). El código para leerlo:

$envFile = dirname(__DIR__) . '/.env';

El problema que tuvimos: los valores del .env tenían comillas y espacios innecesarios:

# MAL — las comillas forman parte del valor
WA_VERIFY_TOKEN='mi_token_secreto'
GOOGLE_API_KEY= "AIzaSy..."

# BIEN
WA_VERIFY_TOKEN=mi_token_secreto
GOOGLE_API_KEY=AIzaSy...

Este tipo de error es difícil de detectar porque el archivo existe y se lee correctamente —simplemente el valor incluye caracteres extra que hacen que las comparaciones fallen.

Paso 4: El token de acceso permanente

Meta genera tokens de acceso temporales que caducan en 24 horas. Para producción necesitas un token permanente, que se genera desde un usuario del sistema (System User) en Business Manager.

El proceso:

Configuración del negocio → Usuarios del sistema → Crear usuario (Admin)
Asignar la app de WhatsApp como activo
Generar token con el permiso whatsapp_business_messaging
Guardar en el .env como WA_ACCESS_TOKEN

Si al generar el token no aparece el permiso de WhatsApp, el motivo habitual es que la app no está asignada como activo a ese usuario del sistema.

Paso 5: La lógica del webhook

El archivo whatsapp-webhook.php hace varias cosas:

Deduplicación: WhatsApp puede reenviar el mismo evento varias veces. Se guarda un registro de los IDs de mensajes procesados para no responder dos veces.

Doble check azul: Se marca el mensaje como leído inmediatamente, antes de procesarlo.

Historial por número: Para que la conversación tenga contexto, se guarda el historial de cada número de teléfono en un archivo JSON (whatsapp-history/34XXXXXXXXX.json). Se recupera en cada mensaje y se envía a Gemini.

System prompt adaptado: El mismo instrucciones.txt que usa el chatbot web, pero con reglas adicionales para WhatsApp: sin Markdown de enlaces, respuestas más cortas, formato adaptado a móvil.

Respuesta inmediata: Meta exige que el webhook responda con HTTP 200 en menos de 20 segundos. Si el procesamiento (llamada a Gemini, etc.) tarda más, hay que responder primero y procesar después:

http_response_code(200);
if (function_exists('fastcgi_finish_request')) {
    echo 'OK';
    fastcgi_finish_request(); // Cierra la conexión con Meta
}
set_time_limit(120); // El script sigue corriendo en segundo plano

Paso 6: Flujo de derivación al equipo humano

Este fue el diseño más interesante del proyecto. Cuando una clienta quiere pedir cita, el bot no la puede gestionar directamente (la peluquería no tiene sistema de reservas online). El flujo diseñado fue:

Gemini detecta que la clienta quiere cita
El bot pide nombre y teléfono de forma conversacional
Cuando tiene ambos datos, confirma y añade la etiqueta [OPEN_BOOKING]
El webhook detecta la etiqueta y envía una plantilla aprobada por Meta al número del equipo con los datos de la clienta y un resumen de la conversación
El equipo contacta a la clienta desde su propio número

Esta arquitectura tiene una ventaja importante: el número del bot y el número del equipo son diferentes. El bot nunca tiene que “callarse” — sigue respondiendo aunque el equipo ya esté gestionando la cita.

Paso 7: Las plantillas de mensaje

Para enviar mensajes a un número que no te ha escrito en las últimas 24 horas, necesitas plantillas aprobadas por Meta. Son mensajes predefinidos con variables.

Ejemplo de plantilla para notificar al equipo:

📋 Nueva solicitud de cita
📱 Clienta: {{1}}

Conversación:
{{2}}

Las variables {{1}} y {{2}} se rellenan en el momento del envío con el nombre/teléfono de la clienta y el resumen de la conversación.

Cosas a tener en cuenta:

Las plantillas tardan entre 1 y 3 días en aprobarse
El nombre debe ser exactamente igual al usar desde el código
El código de idioma también debe coincidir exactamente (es vs es_ES son distintos)
Las variables tienen un límite de 1.024 caracteres — el resumen de conversación hay que truncarlo

Paso 8: Publicar la app y verificación de acceso

Mientras la app está en modo desarrollo, solo pueden interactuar con el bot los números añadidos como testers. Para que cualquier persona pueda usarlo, hay que publicar la app.

Meta también pide una verificación de acceso periódica para confirmar que eres un proveedor de tecnología legítimo. El proceso incluye:

Descripción de cómo usas los datos de la plataforma
Confirmación de los portfolios empresariales que gestionas
Descripción del permiso whatsapp_business_messaging y cómo lo usas
Un vídeo demostrando el funcionamiento del bot
Instrucciones para que los revisores puedan probar la app

Errores y lecciones aprendidas

Resumiendo los problemas que encontramos en el camino:

Error	Causa	Solución
403 al acceder al webhook	Comportamiento esperado (GET sin parámetros)	No es un error real
GET params vacíos (`$_GET = []`)	`.htaccess` de Astro reescribía la URL	Añadir `RewriteRule ^whatsapp-webhook\.php$ - [L]`
Token no coincide	`.env` tenía comillas en los valores	Eliminar comillas y espacios en el `.env`
Error de autenticación API	Token temporal caducado	Generar token permanente con System User
Permiso no disponible	App no asignada al System User	Asignar app como activo antes de generar token
Plantilla no existe	Idioma incorrecto (`es_ES` vs `es`)	Verificar código de idioma exacto en Meta

Arquitectura de archivos final

httpdocs/
├── .env                          → credenciales (nunca en Git)
└── dist/
    ├── whatsapp-webhook.php      → punto de entrada WhatsApp
    ├── asistente/
    │   ├── chat-server.php       → punto de entrada web
    │   ├── contact-notify.php    → envío de notificación al equipo
    │   └── instrucciones.txt     → system prompt compartido
    ├── whatsapp-history/
    │   ├── 34XXXXXXXXX.json      → historial por número
    │   └── escalados.txt         → log de derivaciones
    └── chat-log/
        └── whatsapp_chat.txt     → log general

Conclusiones

La integración de WhatsApp con un chatbot de IA es perfectamente viable para negocios locales, incluso sin grandes infraestructuras. Con PHP, la API de Gemini y la WhatsApp Cloud API, se puede montar un sistema funcional en pocos días.

Los puntos que más tiempo consumen no son técnicos: son los procesos de Meta (verificación de negocio, aprobación de plantillas, revisión de la app). Vale la pena empezarlos en paralelo con el desarrollo técnico.

El resultado es un bot que atiende consultas las 24 horas, recoge datos de contacto de forma conversacional y notifica al equipo humano cuando hay una solicitud de cita — todo sin intervención manual y con un coste de infraestructura prácticamente cero.

¿Quieres implementar algo similar para tu negocio? En Imorillas ayudamos a empresas locales a integrar IA y automatización en sus procesos de comunicación. Contacta con nosotros.