baileys-instance

n8n community node for the wa-instance API built on top of Baileys 7.

Package Information

Released: 3 mo ago
Downloads: 370 weekly / 1,165 monthly
Latest Version: 0.1.9
Author: Miki Guillamon

Available Nodes

Baileys Instance icon
Baileys Instance
Use the wa-instance API built on Baileys 7
Baileys Trigger icon
Baileys Trigger
Poll wa-instance events and emit only new ones

Documentation

n8n-nodes-baileys-instance

Community node de n8n para consumir una instancia wa-instance basada en Baileys 7 con una UI guiada, operativa y preparada para agentes.

Qué incluye

  • Recurso Instance para health, status, pairing, logout, colas y webhook test
  • Recurso History Sync para estado y fetch on-demand
  • Recurso Event para inspección de eventos persistidos
  • Recurso Chat para snapshots, archive, mute y read state
  • Recurso Contact para snapshots persistidos
  • Recurso Group para snapshots y gestión operativa real
  • Recurso Message para texto, media, previews y operaciones avanzadas
  • Recurso Batch para envíos y previews batch
  • Recurso Consent para alta, revocación y consulta
  • Recurso Recipient para límites operativos por JID
  • Recurso Privacy para settings, blocklist y updates de visibilidad
  • Recurso Webhook Delivery para inspección y retry
  • Recurso Custom API Request como escape hatch
  • usableAsTool: true para reutilizar el nodo como tool dentro de flujos/agentes de n8n
  • Nodo Baileys Trigger para polling de eventos persistidos en /events

Requisitos

  • n8n self-hosted con soporte para community nodes
  • una instancia wa-instance accesible por HTTP/HTTPS
  • API key válida del backend

Credenciales

El credential Baileys Instance API pide:

  • Base URL
  • API Key
  • Timeout (ms)
  • Allow Self-Signed TLS Certificates

Timeout (ms) es el primer mitigador cuando Send Text o Send Media fallan con aborts o timeouts. Si el backend encola, resuelve destinatarios o atraviesa un proxy con latencia, súbelo antes de asumir que la API está caída.

La comprobación de credenciales usa GET /status.

Notas importantes sobre onboarding y readiness:

  • una instancia con API key válida puede responder bien a GET /status aunque todavía no esté pairada
  • GET /health/deps sigue disponible como check operativo estricto
  • mientras WhatsApp no tenga connection: open, GET /health/deps puede devolver 503 sin que eso signifique credenciales inválidas
  • para distinguir entre onboarding pendiente y readiness estricta, usa Get Status junto con Get Pairing QR o Request Pairing Code
  • un credential test = OK solo confirma reachability y autenticación básica del backend; no garantiza que la sesión esté lista para enviar mensajes

Recursos y operaciones

Instance

  • Get Health
  • Get Dependencies Health
  • Get Status
  • Get Queue Status
  • Get Pairing QR
  • Request Pairing Code
  • Logout Session
  • Send Webhook Test

History Sync

  • Get Status
  • Fetch

Event

  • Get Many
  • Get

Chat

  • Get Many
  • Get Recent Messages
  • Archive
  • Mute
  • Set Read State

Contact

  • Get Many

Group

  • Get Many
  • Get
  • Create
  • Join
  • Update Subject
  • Update Description
  • Update Participants
  • Update Participant Requests
  • Get Invite Code
  • Revoke Invite Code
  • Update Settings
  • Update Ephemeral

Message

  • Send Text
  • Send Media
  • Preview Send
  • Get
  • Get Many
  • Get Inbound Message
  • Reply
  • Forward
  • Delete
  • Edit
  • React
  • Mark Read
  • Send Receipts
  • Refresh Media

Message -> Get Many

  • Usa GET /sends para auditoría outbound.
  • Mantiene los filtros existentes: status, to_jid, client_ref, from, to, limit.
  • Añade soporte para los filtros nuevos: to_phone, text_contains, cursor.
  • Limit ahora admite hasta 1000.
  • La salida del nodo conserva el comportamiento histórico: devuelve el JSON completo del backend en un único item, incluyendo items, count, has_more y next_cursor cuando estén presentes.

Batch

  • Send Text Batch
  • Send Media Batch
  • Preview Batch
  • Get

Consent

  • Upsert
  • Revoke
  • Get

Recipient

  • Get Limits

Privacy

  • Get Settings
  • Get Blocklist
  • Update Block Status
  • Update Last Seen
  • Update Online
  • Update Profile Photo
  • Update Status
  • Update Groups Add
  • Update Read Receipts
  • Update Default Disappearing Mode

Webhook Delivery

  • Get Many
  • Retry

Custom API Request

  • Execute

Notas de uso

  • Los endpoints de envío añaden X-Idempotency-Key automáticamente si no se informa una clave manual.
  • Send Text, Send Media, Send Text Batch y Send Media Batch pueden ejecutar un Preflight Readiness Check opcional antes del envío. Está desactivado por defecto para mantener compatibilidad.
  • El modo Dependencies Health del preflight es el check más estricto. El modo Status intenta bloquear envíos cuando el payload de /status indica pairing pendiente o socket no abierto.
  • Preview Send y Preview Batch validan policy, normalización y destinatario antes de enviar, y no envían X-Idempotency-Key.
  • Custom API Request reutiliza el mismo host y autenticación del credential, sin permitir cambiar de servidor.
  • Algunas operaciones pueden devolver 409 cuando la capacidad no está disponible en el estado actual del socket/backend.
  • Para tareas habituales usa los recursos modelados; Custom API Request queda como escape hatch para endpoints nuevos o no modelados.

Chat snapshots y mensajes recientes

Chat -> Get Many

  • Usa GET /chats.
  • El filtro Limit ahora admite hasta 1000, alineado con el backend actual.
  • Ejemplo: usa Limit = 500 para recuperar un lote grande de snapshots persistidos.

Chat -> Get Recent Messages

  • Usa GET /chats/:jid/messages.
  • Parámetros:
    • Chat JID obligatorio
    • Limit opcional, por defecto 10, mínimo 1, máximo 100
  • La salida principal del nodo devuelve directamente el array items de la respuesta del backend, para que cada mensaje quede disponible como item de n8n.
  • Ejemplo: Chat JID = 123456789@s.whatsapp.net y Limit = 20 para traer los 20 mensajes persistidos más recientes de ese chat.

Runbook de diagnóstico para ECONNABORTED

Cuando Message -> Send Text o Send Media fallen con ECONNABORTED, ETIMEDOUT o cierres de socket:

  1. Ejecuta Instance -> Get Status.
  2. Ejecuta Instance -> Get Dependencies Health.
  3. Ejecuta Instance -> Get Queue Status.
  4. Reproduce el envío con Custom API Request usando POST /send/text o POST /send/media para aislar si el corte ocurre fuera de la UI modelada.

Interpretación rápida:

  • Si Get Status responde pero Get Dependencies Health devuelve 503, la instancia está autenticada pero no lista para enviar todavía.
  • Si ambos responden bien y /send/text sigue abortando, revisa logs de wa-instance, timeout del proxy reverso y salud de colas internas.
  • Si subir Timeout (ms) evita el fallo, el problema era latencia o tiempo de proceso y no autenticación.

Trigger y webhooks

El paquete incluye Baileys Trigger en modo polling sobre /events.

Esto significa:

  • el trigger integrado sirve para consumir eventos persistidos desde el backend mediante polling
  • no registra ni gestiona webhooks dinámicos en wa-instance
  • no sustituye la ingesta realtime vía webhook del backend

Para eventos inbound realtime, la vía recomendada es:

  1. configurar WEBHOOK_URL en wa-instance
  2. recibir los eventos con el nodo nativo Webhook de n8n
  3. enrutar por event_type, instance_id o reglas de negocio dentro del workflow

Documentación relacionada:

Desarrollo local

npm install
npm run build
npm run dev

Publicación en npm

Este paquete está preparado para publicarse como paquete público de npm y seguir el flujo recomendado por n8n con GitHub Actions + provenance.

Flujo recomendado

  1. Configura el Trusted Publisher del paquete en npm para este repositorio y el workflow publish.yml.
  2. Haz un release con:
npm run release
  1. El tag v* disparará GitHub Actions y publicará el paquete en npm.

Publicación manual

npm login
npm publish --access public

Para verificación en n8n, la publicación recomendada es desde GitHub Actions con provenance.

Discussion