Integración con n8n

Resumen

El nodo de Whaapy para n8n te permite integrar WhatsApp en flujos externos. Puedes enviar mensajes, gestionar conversaciones, controlar la IA y recibir eventos por webhook.

Si el flujo puede vivir completo dentro de Whaapy, empieza con Automatizaciones. Usa n8n cuando necesites coordinar apps externas, pasos largos o lógica de negocio fuera de Whaapy.

Instalación

Desde npm

Abre tu instancia de n8n.
Ve a Settings -> Community Nodes.
Haz click en Install a community node.
Ingresa n8n-nodes-whaapy.
Haz click en Install.

Instalación manual

# Ve al directorio de nodos custom de n8n
cd ~/.n8n/custom

# Instala el paquete
npm install n8n-nodes-whaapy

# Reinicia n8n

Autenticación

Ve a app.whaapy.com -> Settings -> API Keys.
Crea una API key nueva.
En n8n, ve a Credentials -> New Credential.
Busca Whaapy API.
Ingresa tu API key. Debe empezar con wha_.

Operaciones disponibles

Mensajes

Operación	Descripción
Send	Envía un mensaje de WhatsApp: texto, imagen, video, audio, documento, template, interactivo, ubicación, contacto, sticker o reacción
Retry	Reintenta un mensaje fallido

Media

Operación	Descripción
Upload	Sube media al CDN de WhatsApp

Conversaciones

Operación	Descripción
List	Obtiene todas las conversaciones
Get	Obtiene una conversación específica
Get by Phone	Busca una conversación por teléfono
Get Messages	Obtiene el historial de mensajes
Close	Cierra una conversación
Archive	Archiva una conversación
Mark Read	Marca la conversación como leída
Set AI	Activa o desactiva la IA para una conversación
Pause AI	Pausa la IA temporalmente
AI Suggest	Obtiene una sugerencia de IA sin enviarla

Agente

Operación	Descripción
Toggle	Activa o desactiva la IA globalmente
Pause	Pausa la IA globalmente durante X minutos

Templates

Operación	Descripción
List	Obtiene todos los templates de WhatsApp
Get	Obtiene un template específico
Get Variables	Obtiene las variables disponibles del template
Sync	Sincroniza templates desde Meta

Contactos

Operación	Descripción
List	Obtiene todos los contactos
Get	Obtiene un contacto específico
Create	Crea un contacto nuevo
Update	Actualiza un contacto
Delete	Elimina un contacto
Search	Busca contactos con filtros avanzados
Bulk	Ejecuta operaciones en lote
Merge	Fusiona dos contactos
Get Tags	Obtiene todas las etiquetas
Get Fields	Obtiene campos personalizados

Funnels

Operación	Descripción
List Stages	Obtiene todas las etapas del funnel
Get Stage	Obtiene una etapa específica
Create Stage	Crea una etapa nueva
Update Stage	Actualiza una etapa
Delete Stage	Elimina una etapa
Reorder Stages	Reordena etapas
Move Contact	Mueve un contacto a una etapa

Nodo trigger

El nodo Whaapy Trigger escucha eventos de webhook:

Evento	Descripción
`message.received`	Mensaje entrante
`message.sent`	Mensaje enviado
`message.delivered`	Mensaje entregado
`message.read`	Mensaje leído
`message.failed`	Mensaje fallido
`conversation.created`	Conversación nueva
`conversation.updated`	Conversación actualizada
`conversation.handoff`	Handoff a humano
`*`	Todos los eventos

Este evento solo se dispara cuando se crea una conversación nueva: cuando un contacto escribe por primera vez o cuando envías el primer mensaje a un número nuevo desde la API. Para probarlo, usa un número de WhatsApp que nunca haya iniciado una conversación con tu negocio. Si el contacto ya tiene historial, no verás este evento; usa message.received para flujos por mensaje.

Flujos de ejemplo

Enviar mensaje de bienvenida

Webhook (recibe lead) -> Whaapy (envía template) -> Slack (notifica al equipo)

Auto-respuesta con control de IA

Whaapy Trigger (message.received) -> IF (contiene "humano") -> Whaapy (pausa IA) -> Slack (asigna agente)

Integración con CRM

Whaapy Trigger (message.received) -> HTTP Request (CRM API) -> Whaapy (actualiza etiquetas del contacto)

Automatización de funnel

Whaapy Trigger (conversation.created) -> Whaapy (mueve contacto a etapa) -> Whaapy (envía template de bienvenida)

Automatización del dashboard + n8n

Automatización de Whaapy (coincide disparador) -> acción HTTP Request -> Webhook de n8n -> CRM/Slack/Sheets

Revisa Automatizaciones, webhooks y n8n para decidir cuándo usar cada enfoque.

Recomendaciones

Pausar la IA para intervención manual

Cuando envíes un mensaje manual, usa la opción Pause AI para evitar que la IA responda encima:

{
  "to": "+5215512345678",
  "type": "text",
  "content": "Yo me encargo personalmente",
  "additionalFields": {
    "pauseAi": true,
    "pauseDuration": 30
  }
}

Usar templates

Los templates son necesarios para escribir fuera de la ventana de 24 horas. Primero consulta tus templates:

Usa Template -> List para ver los templates disponibles.
Usa el nombre del template en Message -> Send.

{
  "to": "+5215512345678",
  "messageType": "template",
  "templateName": "welcome_message",
  "templateParameters": ["John", "Acme Corp"]
}

Por defecto, Whaapy usa los IDs de quick-reply configurados en el template de tu negocio. En el nodo de n8n puedes activar Allow Button Payload Override y enviar un mapa JSON en Quick Reply Payload Overrides (por ejemplo { "0": "confirm_order", "1": "talk_to_agent" }) solo cuando necesites sobrescribirlos para un flujo específico.

Para headers de templates con media, usa Template Options:

Header Media Source = URL + Header Media URL para archivos públicos.
Header Media Source = Media ID + Header Media ID cuando ya subiste el archivo a Meta.

Si recibes MEDIA_PERMISSION_DENIED, el media_id fue subido con otro token, WABA o número distinto al remitente.

Manejar media

Sube el archivo primero con Media -> Upload.
Usa el media_id devuelto en tu mensaje.

Empezar

Conceptos

Guías del Agente

Automatizaciones

Integraciones

Integración con n8n

Resumen

Instalación

Desde npm

Instalación manual

Autenticación

Operaciones disponibles

Mensajes

Media

Conversaciones

Agente

Templates

Contactos

Funnels

Nodo trigger

Flujos de ejemplo

Enviar mensaje de bienvenida

Auto-respuesta con control de IA

Integración con CRM

Automatización de funnel

Automatización del dashboard + n8n

Recomendaciones

Pausar la IA para intervención manual

Usar templates

Manejar media

Recursos

​Resumen

​Instalación

​Desde npm

​Instalación manual

​Autenticación

​Operaciones disponibles

​Mensajes

​Media

​Conversaciones

​Agente

​Templates

​Contactos

​Funnels

​Nodo trigger

​Flujos de ejemplo

​Enviar mensaje de bienvenida

​Auto-respuesta con control de IA

​Integración con CRM

​Automatización de funnel

​Automatización del dashboard + n8n

​Recomendaciones

​Pausar la IA para intervención manual

​Usar templates

​Manejar media

​Recursos

Resumen

Instalación

Desde npm

Instalación manual

Autenticación

Operaciones disponibles

Mensajes

Media

Conversaciones

Agente

Templates

Contactos

Funnels

Nodo trigger

Flujos de ejemplo

Enviar mensaje de bienvenida

Auto-respuesta con control de IA

Integración con CRM

Automatización de funnel

Automatización del dashboard + n8n

Recomendaciones

Pausar la IA para intervención manual

Usar templates

Manejar media

Recursos