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 |
| 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 |
| 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
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.
- Sube el archivo primero con Media -> Upload.
- Usa el
media_id devuelto en tu mensaje.
Recursos
