> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integración con n8n

> Usa Whaapy con n8n para automatizar flujos que conectan WhatsApp con otras apps

## 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.

<Info>
  Si el flujo puede vivir completo dentro de Whaapy, empieza con [Automatizaciones](/concepts/automations). Usa n8n cuando necesites coordinar apps externas, pasos largos o lógica de negocio fuera de Whaapy.
</Info>

## Instalación

### Desde npm

1. Abre tu instancia de n8n.
2. Ve a **Settings** -> **Community Nodes**.
3. Haz click en **Install a community node**.
4. Ingresa `n8n-nodes-whaapy`.
5. Haz click en **Install**.

### Instalación manual

```bash theme={null}
# Ve al directorio de nodos custom de n8n
cd ~/.n8n/custom

# Instala el paquete
npm install n8n-nodes-whaapy

# Reinicia n8n
```

## Autenticación

1. Ve a [app.whaapy.com](https://app.whaapy.com) -> **Settings** -> **API Keys**.
2. Crea una API key nueva.
3. En n8n, ve a **Credentials** -> **New Credential**.
4. Busca **Whaapy API**.
5. 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        |

<Tip title="Comportamiento de conversation.created">
  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.
</Tip>

## 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](/guides/automations/webhooks-and-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:

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "to": "+5215512345678",
  "messageType": "template",
  "templateName": "welcome_message",
  "templateParameters": ["John", "Acme Corp"]
}
```

<Tip title="IDs de quick-reply en templates">
  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.
</Tip>

<Tip title="Media en headers de templates">
  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.
</Tip>

### Manejar media

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

## Recursos

* [Documentación de la API de Whaapy](/api-reference/overview)
* [Documentación de Community Nodes de n8n](https://docs.n8n.io/integrations/community-nodes/)
* [Repositorio en GitHub](https://github.com/saymetristan/whaapy-n8n)