Webhooks y N8N

Los webhooks permiten que Funnel+ envíe notificaciones en tiempo real a sistemas externos cada vez que ocurre un evento.

---

Concepto: Webhook vs API

	Webhook	API
Dirección	Funnel+ → Tu sistema	Tu sistema → Funnel+
Cuándo	Automático, cuando ocurre un evento	Bajo demanda, cuando vos lo pedís
Para qué	Notificaciones en tiempo real	Enviar mensajes, crear tickets, etc.

---

Configuración de Webhooks

Método 1: Por Canal (recomendado para empezar)

1. Ingresá a Configuraciones > Canales > Configuración del Canal
2. Activá la opción Webhook
3. Ingresá la URL POST de tu destino (ej: URL de N8N)
4. Seleccioná los eventos que querés enviar
5. Opcionalmente agregá una API Key de N8N para seguridad

Método 2: Por Cola/Integración

1. Ingresá a Registros > Colas > Integraciones
2. Creá una integración tipo N8N/Webhook
3. Configurá: Nombre, URL POST y API Key opcional
4. Vinculá la integración a una cola
5. Opción "Iniciar integración al transferir": activa el webhook inmediatamente al transferir un ticket a esa cola

---

Eventos Disponibles

Evento	Tipo	Cuándo se dispara
Nuevo ticket (usuario)	NewTicketUserCreate	Un usuario crea un ticket manualmente
Nuevo ticket	NewTicket	Se abre un ticket nuevo (mensaje entrante)
Ticket transferido	TransferTicket	Se transfiere a otra cola o usuario
Ticket cerrado	ClosedTicket	Se cierra la conversación
Mensaje recibido/enviado	(mensaje)	Cada mensaje nuevo

---

Estructura del Payload

Cada evento envía un JSON con esta estructura:

Datos del Mensaje

Campo	Descripción
messageId	Identificador único del mensaje
messageBody	Texto del mensaje
timestamp	Marca de tiempo UNIX
fromMe	true si fue enviado, false si fue recibido
mediaType	Tipo: image, video, audio, document
mediaUrl	URL de descarga del archivo adjunto
sendType	Origen: "manual", "bot", "API"
status	Estado de entrega: delivered, read

Datos del Ticket

Campo	Descripción
id	ID del ticket
status	Estado: pending, open, closed
protocol	Número de protocolo
queueId	ID de la cola
apiConfig	Clave externa (externalKey)
isGroup	Si es un grupo de WhatsApp
closingReasonId	Motivo de cierre (solo en ClosedTicket)

Datos del Contacto

Campo	Descripción
id	ID del contacto
name	Nombre completo
phoneNumber	Número de teléfono
email	Email
kanbanId	Lista del CRM
followupId	Follow-up activo

Datos del Usuario (solo en envíos manuales)

Campo	Descripción
id	ID del usuario/agente
name	Nombre del agente
email	Email del agente

---

Configuración Importante: Filtro de Estado

Controlá qué tickets generan webhooks de mensajes:

Configuración	Resultado
Tickets abiertos: ON	Recibe webhooks de tickets en estado "Abierto"
Tickets pendientes: ON	Recibe webhooks de tickets en estado "Pendiente"
Ambos OFF	No se envían webhooks de mensajes

Cuidado: Si activás eventos de mensajes pero desactivás ambos filtros de estado, no vas a recibir ningún webhook.

---

Ejemplos Prácticos con N8N

Ejemplo 1: Registrar ventas en Google Sheets

Webhook Trigger (ClosedTicket)
  → IF: closingReasonId = "Venta concretada"
  → Google Sheets: Agregar fila
    - Fecha, Nombre del contacto, Teléfono, Agente, Protocolo

Ejemplo 2: Alerta de insatisfacción por Slack

Webhook Trigger (Mensaje recibido)
  → IF: evaluación ≤ 2
  → Slack: Enviar mensaje al canal #alertas
    - "⚠ Evaluación baja: [contacto] calificó [nota] al agente [usuario]"

Ejemplo 3: Sincronizar contactos con Mailchimp

Webhook Trigger (NewTicket)
  → Mailchimp: Buscar suscriptor por email
  → IF: no existe → Crear suscriptor
  → IF: existe → Actualizar tags

Ejemplo 4: Notificar despacho desde sistema de logística

Sistema de logística → API Funnel+: Enviar mensaje
  POST /api/messages/send
  {
    "number": "5491155551234",
    "body": "¡Tu pedido #12345 fue despachado! Seguimiento: [link]"
  }

Ejemplo 5: Crear tarea en Trello al transferir ticket

Webhook Trigger (TransferTicket)
  → IF: queueId = cola "Soporte Técnico"
  → Trello: Crear tarjeta
    - Lista: "Por hacer"
    - Título: "Soporte: [nombre contacto] - Protocolo [protocol]"
    - Descripción: último mensaje del cliente