Resumen: Configure un endpoint HTTPS público, regístrelo como su webhook de Whapi.Cloud, y su servidor recibirá cada evento de WhatsApp como un POST JSON. Verifique el campo type para enrutar la lógica, luego llame a POST /messages/text con to y body para responder. Ese bucle de dos pasos — recibir evento, enviar reacción — es toda integración en esta guía. Comience con el enrutamiento de mensajes de texto; agregue ramas condicionales según crezca su caso de uso.
El Principio Central: Evento → Reacción
La integración de la API de WhatsApp es impulsada por eventos, no es un SDK de mensajería. Algo ocurre en WhatsApp, Whapi.Cloud notifica a su servidor vía webhook, su código decide la reacción y la API la ejecuta.
La secuencia es fija. Un usuario envía un mensaje a su número de WhatsApp. Whapi.Cloud captura ese evento e inmediatamente dispara un HTTP POST a la URL de su webhook con un payload JSON — quién lo envió, qué tipo de mensaje, el contenido. Su servidor lee el payload, aplica lógica de negocio y llama a la REST API de Whapi.Cloud para enviar una respuesta, actualizar un registro de CRM o desencadenar una acción posterior. El bucle se repite con cada evento siguiente.
Su código nunca consulta activamente — Whapi.Cloud envía cada evento de WhatsApp a su webhook en el momento en que ocurre. La única pregunta que responde su lógica de negocio: dado este evento, ¿qué sucede a continuación?
Los acuses de entrega, reacciones con emoji, pulsaciones de botones, cambios de membresía en grupos y eventos de llamadas todos disparan webhooks — el texto entrante es uno de ocho tipos de eventos. Mapear la taxonomía completa a decisiones de negocio es lo que separa una integración funcional de una a medias. Los desarrolladores familiarizados con los webhooks de Stripe o los callbacks de Twilio reconocerán el patrón de inmediato.
¿Por Qué Usar un Gateway en Lugar de la API Oficial?
Whapi.Cloud se conecta mediante sockets de sesión web. Escanee un código QR y envíe su primer mensaje en minutos — sin verificación de Meta ni aprobación de plantillas.
La plataforma oficial de WhatsApp Business requiere verificación empresarial, incorporación BSP y plantillas de mensajes preaprobadas antes de poder enviar un solo mensaje proactivo. Whapi.Cloud cobra una suscripción fija sin tarifas por conversación. Más de 3.300 equipos de desarrollo lo utilizan en producción en múltiples países.
Una desventaja real: Whapi.Cloud no está oficialmente sancionado por Meta, lo que importa para industrias reguladas que requieren documentación formal de cumplimiento. Para e-commerce, bots de soporte, herramientas de RRHH y sincronización de CRM — no es una restricción bloqueante. La guía de inicio cubre lo que necesita antes de su primera llamada a la API.
La Taxonomía Completa de Eventos de WhatsApp
Cada categoría de eventos se corresponde con una clase distinta de decisiones de negocio que su lógica de enrutamiento debe manejar — y la taxonomía completa es más amplia de lo que la mayoría de desarrolladores esperan antes de su primera integración.
Cada evento que Whapi.Cloud entrega comparte la misma estructura externa: un POST JSON a su webhook con un campo type que identifica la categoría del evento. Su manejador ramifica primero por type, luego extrae los subcampos específicos de esa categoría.
| Categoría de Evento | Tipos de Eventos Específicos | Reacción de Negocio Típica |
|---|---|---|
| Mensaje entrante | text, image, audio, video, document, sticker, location, contact card | Enrutar al manejador IA, reenviar al CRM, respuesta automática, etiquetar conversación |
| Interacción interactiva | button reply, quick reply, list selection, template response | Avanzar la máquina de estados de conversación, confirmar pedido, activar acción de backend |
| Reacción con emoji | reaction added, reaction removed | Registrar puntuación de sentimiento, activar seguimiento, actualizar métrica de satisfacción |
| Estado del mensaje | sent, delivered, read, played (voice note) | Actualizar campo de entrega en CRM, cancelar temporizador de reenganche, activar secuencia de seguimiento |
| Evento de llamada | incoming call initiated, call missed, call rejected | Registrar llamada perdida, enviar mensaje de solicitud de devolución de llamada automatizado |
| Evento de grupo | participant joined, participant left, admin changed, group created/archived | Actualizar lista de miembros, enviar mensaje de bienvenida, sincronizar con sistema de RRHH |
| Evento de etiqueta | label applied to chat, label removed | Segmentar contacto en CRM, activar campaña, actualizar etapa del pipeline |
| Evento de canal | follower joined channel, channel update published | Enviar confirmación al suscriptor, sincronizar analíticas, activar flujo de trabajo de notificaciones |
La regla de enrutamiento es consistente en cada fila: leer el campo type, ramificar al manejador correspondiente, extraer los subcampos relevantes para ese tipo. Un mensaje "image" necesita un manejador diferente que una interacción "button_reply" — ambos llegan como solicitudes POST a la misma URL de webhook, pero la estructura del payload y su lógica de negocio difieren completamente.
Caminos hacia la Integración
Ya sea que escriba código de servidor o configure una herramienta de flujo de trabajo visual, toda integración sigue el mismo bucle evento→reacción — solo cambia la herramienta.
| Enfoque | Requisito Técnico | Tiempo hasta el Primer Mensaje | Ideal Para |
|---|---|---|---|
| REST API (Python / Node.js / PHP) | Cliente HTTP, cualquier backend con URL pública | ~30 minutos | Lógica de negocio personalizada, chatbots IA, conectores CRM |
| Make (módulo nativo de Whapi.Cloud) | Solo cuenta de Make | ~10 minutos | No desarrolladores, equipos de automatización de marketing |
| n8n (autoalojado o en la nube) | Instancia de n8n (Docker o nube) | ~15 minutos | Equipos técnicos que desean control de flujo de trabajo autoalojado |
| cURL / Postman | Ninguno más allá de la herramienta | ~5 minutos | Probar endpoints, prueba de concepto |
Los usuarios de Make y n8n configuran un nodo disparador de webhook que recibe el mismo payload JSON que recibiría un backend personalizado. Los nodos luego leen los campos del evento y llaman al endpoint de envío de Whapi.Cloud como reacción. El modelo evento→reacción no cambia; la lógica de negocio vive en un lienzo visual en lugar de código.
Configuración del Webhook: El Extremo Receptor
La configuración del webhook en Whapi.Cloud requiere tres entradas: la URL de su endpoint, los tipos de eventos que desea recibir y un secreto opcional para verificación de solicitudes. El endpoint debe ser accesible públicamente a través de HTTPS.
Configure el webhook en los ajustes de su canal de Whapi.Cloud. Una vez guardado, Whapi.Cloud comienza a reenviar los eventos de WhatsApp a su URL como solicitudes HTTP POST con un cuerpo JSON. Los eventos llegan en tiempo real — típicamente en pocos cientos de milisegundos tras la acción en WhatsApp. No hay intervalo de consulta que configurar ni conexión persistente que mantener de su parte. La referencia completa del formato de payload del webhook documenta todos los campos que su manejador necesitará parsear.
Durante el desarrollo, ngrok expone un puerto local a una URL HTTPS pública. Establezca esa URL como su webhook temporal, ejecute su manejador localmente e inspeccione los payloads en tiempo real antes de comprometerse con un despliegue en servidor.
Devuelva HTTP 200 antes de procesar. Esto no es opcional. Whapi.Cloud reintenta la entrega si su endpoint no responde dentro del período de espera. Acuse recibo de la solicitud inmediatamente, envíe el payload a un hilo en segundo plano o cola de tareas, y procese de forma asíncrona. Mezclar el acuse de recibo y el procesamiento en la misma ruta síncrona causa eventos duplicados cuando su lógica es lenta.
Del Webhook a la Respuesta: Un Ejemplo de Código Funcional
Cualquier lenguaje con un cliente HTTP — Python, Node.js, PHP, Go — se integra de la misma manera. Sin SDK propietario, sin wrapper que instalar. El manejador a continuación enruta mensajes entrantes y envía respuestas vía POST /messages/text.
from flask import Flask, request, jsonify
import requests
import threading
app = Flask(__name__)
WHAPI_TOKEN = "your_channel_token" # from panel.whapi.cloud/dashboard
WHAPI_URL = "https://gate.whapi.cloud/messages/text"
def send_reply(to: str, body: str) -> None:
# Calls sendMessageText — required: to (chat ID), body (message text)
requests.post(
WHAPI_URL,
headers={"Authorization": f"Bearer {WHAPI_TOKEN}"},
json={"to": to, "body": body}
)
def process_event(data: dict) -> None:
for msg in data.get("messages", []):
if msg.get("from_me"):
continue # skip outbound confirmations
sender = msg.get("chat_id") # e.g. "[email protected]"
msg_type = msg.get("type", "")
if msg_type == "text":
text = msg.get("text", {}).get("body", "").lower()
if any(w in text for w in ["hello", "hi", "hey"]):
send_reply(sender, "Hey! How can I help you today?")
elif "price" in text or "pricing" in text:
send_reply(sender, "Check our pricing: https://whapi.cloud/price")
elif "order" in text:
send_reply(sender, "Please share your order number and we'll check its status.")
else:
send_reply(sender, "Thanks! Our team will get back to you shortly.")
elif msg_type == "image":
send_reply(sender, "Got your image — our team will review it.")
elif msg_type == "button_reply":
btn_id = msg.get("button_reply", {}).get("id", "")
send_reply(sender, f"You selected: {btn_id}. Processing your request...")
elif msg_type == "reaction":
# Reactions carry sentiment data — log them, don't reply by default
emoji = msg.get("reaction", {}).get("text", "")
msg_id = msg.get("reaction", {}).get("msg_id", "")
print(f"Reaction {emoji} on message {msg_id} from {sender}")
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.get_json()
# Acknowledge immediately — never block on processing
threading.Thread(target=process_event, args=(data,)).start()
return jsonify({"status": "ok"}), 200
if __name__ == "__main__":
app.run(port=5000)Se ven cuatro ramas de enrutamiento: saludar con palabras clave de salutación, ofrecer precios ante intención de compra, solicitar aclaración en consultas de pedidos, registrar reacciones para análisis de sentimiento. La misma estructura condicional escala a cientos de ramas — o reemplace toda la cadena if/elif con una llamada a un LLM. El manejador del webhook en sí permanece igual. Para los pasos de despliegue en producción con colas Celery, consulte la guía del bot de WhatsApp en Python.
En un despliegue real, reemplace el hilo en segundo plano con una cola de tareas (Celery, RQ, o un servicio de cola en la nube) para garantías de reintento y escalado horizontal. El acuse de recibo del webhook y la lógica de negocio deben permanecer separados — esa frontera es la decisión arquitectónica fundamental en toda integración a escala.
Tipos de Mensajes Interactivos como Entradas de Eventos Distintos
Las respuestas de botones, selecciones de listas y respuestas rápidas son tipos de eventos distintos con estructuras de payload separadas. Cada uno requiere su propia rama de enrutamiento en su código.
Cuando un usuario toca un botón en un mensaje interactivo de WhatsApp, Whapi.Cloud entrega un evento button_reply. El payload contiene el ID del botón que asignó al construir el mensaje, no el texto de la etiqueta visible. Su lógica de enrutamiento verifica el ID, haciendo que los flujos interactivos sean deterministas — ninguna formulación del usuario activa accidentalmente la rama incorrecta.
Consideraciones típicas:
-
button_reply: Extraiga
button_reply.id— el ID programático que estableció al construir el mensaje de botón. Enrute al manejador correspondiente sin ningún análisis de texto. -
list_reply: Extraiga tanto
list_reply.idcomolist_reply.title— el ID impulsa la lógica, el título es útil en los mensajes de confirmación enviados de vuelta al usuario. -
reaction: Extraiga
reaction.text(el carácter emoji) yreaction.msg_id(a qué mensaje se reaccionó). Mapee al registro de sentimiento o use como señal ligera de satisfacción sin interrumpir la conversación. -
Actualizaciones de estado: Cada evento de estado lleva
statuses[].statuscomo"sent","delivered"o"read". Actualice su campo de CRM, cancele un temporizador de reenganche o inicie una secuencia de seguimiento según las transiciones de estado.
Los acuses de lectura son datos de comportamiento, no solo confirmaciones de entrega. Un prospecto que lee su mensaje de precios a las 9 PM pero no responde le está diciendo algo a su CRM. Enrute los eventos de estado a su capa de datos — son señales sobre las que actuar, no ruido a filtrar.
Arquitectura de Chatbot IA en WhatsApp
Un LLM entre el webhook y la respuesta de la API convierte un número de WhatsApp en un agente IA. La arquitectura tiene tres capas. La capa intermedia es donde la mayoría de los equipos toman la decisión que determina si el chatbot se siente coherente o defectuoso.
Capa uno: Whapi.Cloud entrega el mensaje entrante a su webhook. Capa dos: su servidor recupera el historial de conversación del almacenamiento persistente, agrega el nuevo mensaje, llama a la API del LLM con el contexto completo de la conversación y envía la respuesta de vuelta vía Whapi.Cloud. Capa tres: el proveedor de LLM — OpenAI, Anthropic o Gemini — recibe una ventana de contexto preparada, no el payload raw del webhook.
La capa que la mayoría de los equipos subestima es el almacenamiento. Las conversaciones son con estado — persista el historial con clave chat_id, limite a las últimas 15-20 réplicas antes de cada llamada al LLM. Sin almacenamiento persistente, su IA lee cada mensaje como si la conversación acabara de comenzar.
La transferencia a un agente humano es el segundo patrón crítico: ninguna IA resuelve el 100% de las conversaciones correctamente. Construya un disparador de escalada explícito — una coincidencia de palabras clave, un umbral de puntuación de confianza o un límite de turnos de conversación — que enrute el chat a un agente humano. Marque la conversación en su CRM, notifique al agente y opcionalmente envíe al usuario un mensaje de confirmación. Su webhook continúa entregando mensajes durante la transferencia; la lógica de enrutamiento simplemente cambia el manejador de IA a cola humana.
El repositorio de GitHub de Whapi.Cloud incluye plantillas de bot en Python y Node.js que implementan este patrón de tres capas con almacenamiento, enrutamiento y lógica de llamadas a la API ya escritos. Clone, configure su token y credenciales de LLM, y ejecute.
Casos de Uso Empresariales en Diversas Industrias
El bucle evento→reacción se aplica de manera idéntica en todas las industrias donde WhatsApp es un canal de comunicación activo — solo cambia la lógica de negocio interna.
-
E-commerce: Pedido confirmado en evento de compra, recordatorio de carrito abandonado ante tiempo de inactividad, seguimiento de acuses de lectura para medir la tasa de entrega-a-respuesta.
-
Las clínicas de salud usan menús de respuesta de botones para formularios de admisión, activan recordatorios de citas 24h y 2h antes del horario, y envían un seguimiento de no presentación cuando llega un acuse de lectura sin respuesta.
-
Bienes raíces: Una consulta entrante activa una lista corta de opciones por presupuesto y ubicación vía respuestas de botones, los leads calificados se enrutan a la cola del agente con una entrada de CRM creada automáticamente en el mismo evento.
-
Para RRHH y operaciones internas, los horarios de turnos se envían como mensajes de grupo, la confirmación de empleados se rastrea mediante el estado de lectura, y los documentos de incorporación se entregan automáticamente desde los eventos de activación del sistema de RRHH.
Consideraciones para Producción
Cuatro decisiones determinan si una integración resiste el tráfico real. Acuse recibo antes de procesar y deduplique por ID de mensaje — omita cualquiera y procesará algunos eventos dos veces.
-
Acusar recibo antes de procesar. Devuelva HTTP 200 inmediatamente. Mueva la lógica de negocio a un hilo en segundo plano o cola de tareas. Whapi.Cloud reintenta en caso de tiempo de espera — mezclar el acuse de recibo y el procesamiento en la misma ruta síncrona produce eventos duplicados.
-
Los ID de mensajes son su clave de deduplicación. Almacene cada ID procesado con un TTL corto (Redis funciona bien) y omita el reprocesamiento cuando el mismo evento llega dos veces. Las condiciones de red ocasionalmente entregan duplicados incluso desde infraestructura confiable.
-
Regule los envíos salientes en números nuevos. Los canales de producción de Whapi.Cloud no tienen límites estrictos de tasa de API. El riesgo es la detección de spam del lado del servidor de WhatsApp — picos repentinos de volumen en números recientemente activados atraen sanciones. Implemente una cola de envío con modestos retrasos entre mensajes al hacer broadcast a listas grandes desde un número nuevo.
-
Las sesiones de chatbot IA necesitan tres configuraciones desde el primer día: historial con clave
chat_id, limitar el contexto a las últimas 15-20 réplicas antes de cada llamada al LLM, y limpiar las sesiones expiradas tras una ventana de inactividad configurable. Omita cualquiera y depurará errores de desbordamiento de contexto o estado obsoleto en producción.
La infraestructura de Whapi.Cloud gestiona las actualizaciones del protocolo de WhatsApp automáticamente — su integración no se rompe cuando WhatsApp lanza una nueva versión del cliente. Para orientación sobre el calentamiento de números y patrones de envío seguros, la guía de mensajería segura cubre los comportamientos que realmente activan las sanciones de WhatsApp.
Lo Que Dicen los Equipos que Construyen con Whapi.Cloud
«Whapi.Cloud se convirtió en una parte clave de nuestra comunicación con los clientes. Automatizamos actualizaciones de productos, notificaciones de pedidos y mensajes de soporte sin necesitar plantillas ni aprobaciones de Meta.»
— Oscar T., CTO
«Conectamos WhatsApp a nuestros flujos de trabajo usando n8n en solo unos minutos. Sin código, sin complicaciones — todo funcionó al primer intento.»
— Martin P., Desarrollador
«Todo es simple, intuitivo y fácil de navegar. La documentación es clara y toda la información que necesito está justo en la pantalla.»
— Roberto K., Desarrollador Web
Los desarrolladores escriben la lógica de negocio; Whapi.Cloud gestiona la entrega por WhatsApp. Esa separación es lo que hace la arquitectura escalable — su código de enrutamiento se ejecuta de manera idéntica en un VPS de $5 o en un clúster contenedorizado, porque la complejidad del protocolo permanece en el lado del gateway. Mapee cada evento de negocio a una reacción de WhatsApp: esa es la arquitectura completa.
