zapwhat

Nodos de n8n para ZapWhat: envía y recibe mensajes de WhatsApp con la API de zapwhat.com

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: ZapWhat

Documentation

n8n-nodes-zapwhat

Nodos de n8n para ZapWhat: envía mensajes de WhatsApp, gestiona contactos y grupos y recibe mensajes en tus workflows usando la API REST de zapwhat.com.

El paquete incluye:

  • ZapWhat (nodo de acción): mensajes, archivos, ubicaciones, contactos, grupos, verificación de números e instancias.
  • ZapWhat Trigger (nodo de disparador): inicia el workflow cuando ZapWhat reenvía un mensaje o un estado de entrega.
  • ZapWhat API (credencial): Base URL + API Token, con test de conexión contra GET /api/instances.

Requisitos

  • n8n autoalojado (Docker, VPS, Neubox, etc.) con la opción Community nodes habilitada.
  • Una cuenta de ZapWhat con al menos una instancia de WhatsApp conectada.
  • El token de API de tu cuenta (Dashboard de ZapWhat → sección API).

En n8n Cloud solo se pueden instalar nodos comunitarios verificados. Este paquete está pensado para instalaciones autoalojadas.

Instalación

  1. En n8n abre Settings → Community nodes → Install a community node.

  2. Escribe el nombre del paquete:

    n8n-nodes-zapwhat
    
  3. Acepta el aviso de nodo no verificado e instala.

  4. Reinicia n8n si la versión lo requiere y recarga el editor.

También puedes instalarlo por consola dentro de tu contenedor o servidor:

npm install -g n8n-nodes-zapwhat

Credenciales

Crea una credencial ZapWhat API con:

Campo Valor
Base URL https://zapwhat.com (sin barra final)
API Token El token de API de tu cuenta ZapWhat

Pulsa Test para comprobar la conexión: el nodo llama a GET /api/instances y muestra tus instancias. El campo Instancia del nodo se carga automáticamente desde esa misma llamada.

Nodo de acción: ZapWhat

Elige un Recurso y una Operación.

Mensaje

Operación Endpoint Notas
Enviar Texto POST /api/send Admite Responder A para citar un mensaje
Enviar Archivo POST /api/send-media Imagen, video, audio, documento, sticker o tarjeta de contacto
Enviar Ubicación POST /api/send-location Latitud, longitud, nombre y dirección
Consultar Mensaje GET /api/messages Requiere ID del mensaje o ID de registro
Editar Mensaje PUT /api/messages Solo mensajes de texto enviados hace menos de 15 minutos
Eliminar Mensaje POST /api/messages action: delete, elimina para todos

Contacto

Listar Contactos, Consultar Contacto, Obtener Foto de Perfil, Bloquear Contacto, Desbloquear Contacto y Sincronizar Contacto (nombre + teléfono).

Grupo

Listar Grupos, Crear Grupo, Obtener Información del Grupo, Obtener Participantes, Agregar Participantes, Quitar Participantes, Actualizar Ajustes del Grupo (asunto, descripción, solo administradores), Obtener Enlace de Invitación y Salir del Grupo.

En los campos de participantes puedes pegar varios números separados por coma, punto y coma o salto de línea.

Número e Instancia

  • Verificar Número: POST /api/check-number, devuelve exists.
  • Listar Instancias: GET /api/instances, devuelve instance_id, status y created_at.

Salida

El nodo devuelve el JSON de ZapWhat sin modificar (success, message_id, message_log_id, response, data, ...) y conserva el pairedItem de cada elemento de entrada. Si activas Continue On Fail, los errores se devuelven como { "error": "..." }.

Errores

Los errores se muestran como NodeApiError con el mensaje de ZapWhat y una pista en español según el código (invalid_token, instance_forbidden, instance_not_ready, message_not_editable, edit_window_closed, message_not_found, network_error, ...).

Nodo disparador: ZapWhat Trigger

ZapWhat no expone un endpoint para registrar webhooks automáticamente, así que el trigger no intenta crearlos: n8n registra la ruta y tú pegas la URL en el Dashboard de ZapWhat.

  1. Añade el nodo ZapWhat Trigger al workflow y elige los Eventos.

  2. Activa el workflow. La URL de producción es:

    https://TU-N8N/webhook/zapwhat
    

    (durante las pruebas, con Listen for test event, la URL es https://TU-N8N/webhook-test/zapwhat).

  3. En ZapWhat entra en Dashboard → Instancia → Webhook y pega esa URL.

  4. Envía un mensaje de WhatsApp a la instancia para comprobar la recepción.

Filtros

  • Eventos: Mensaje Entrante, Mensaje Saliente, Estado de Entrega u Otros Eventos.
  • ID de Instancia: si tu cuenta tiene varias instancias, filtra para que el workflow solo se dispare con una. Vacío = todas.

Salida

Campo Descripción
event Evento original reenviado por ZapWhat
category incoming, outgoing, status o unknown
instanceId Instancia que recibió o envió el mensaje
from Remitente (número, sin @s.whatsapp.net)
fromMe true si el mensaje salió del WhatsApp de la instancia
isGroup / groupId Grupo y su JID cuando el mensaje viene de un grupo
messageId ID del mensaje en WhatsApp
text Texto o pie de foto del mensaje
messageType text, image, video, audio, document, sticker, location o contact
pushName Nombre del contacto que envía
timestamp Marca de tiempo del evento
status Estado recibido en eventos de entrega
raw Payload original (solo si activas Incluir Cuerpo Original)

Limitaciones del trigger

  • La ruta es fija (/webhook/zapwhat), por lo que solo un workflow puede escuchar esa ruta a la vez. Si necesitas varios flujos, usa un Switch sobre instanceId o sobre category.
  • La URL del webhook es pública: protégela con tu proxy inverso, VPN o restricciones de red si tu n8n está expuesto a internet.

Cómo funciona la autenticación

Todas las peticiones envían Authorization: Bearer <API Token> y se dirigen a Base URL + /api/.... La credencial usa IAuthenticateGeneric, así que el token nunca aparece en los parámetros del nodo ni en los logs de ejecución.

Desarrollo local

npm install                     # en Windows: npm install --ignore-scripts
npm run build                   # compila TypeScript y copia los iconos a dist/
npm run lint                    # reglas de la comunidad n8n (@n8n/node-cli)
npm run test:smoke              # valida descripciones y el webhook del trigger
npm run dev                     # n8n local con recarga en caliente
npm pack                        # genera el .tgz para probar la instalación

En Windows, @n8n/node-cli arrastra isolated-vm, que necesita Visual Studio
Build Tools. Si no las tienes, instala con npm install --ignore-scripts: el
build y el lint siguen funcionando. En Linux/macOS no hace falta.

Para probar el .tgz en un n8n autoalojado:

docker cp n8n-nodes-zapwhat-0.1.0.tgz n8n:/tmp/
docker exec -it n8n sh -c "cd /home/node/.n8n && npm install /tmp/n8n-nodes-zapwhat-0.1.0.tgz"
docker restart n8n

La instalación desde la interfaz (Settings → Community nodes) solo acepta el nombre del paquete publicado en npm, no un archivo .tgz.

Plantillas incluidas

En examples/ hay tres workflows listos para importar (Workflows → Import from file):

Archivo Qué hace
01-enviar-texto.json Trigger manual → enviar un mensaje de texto
02-enviar-archivo.json Trigger manual → enviar un documento con pie de foto
03-respuesta-automatica.json ZapWhat Trigger → IF (contiene "precio") → respuesta automática

Sustituye TU_INSTANCE_ID y asigna tu credencial ZapWhat API después de importar.

Publicación

npm login
npm publish --access public
npm view n8n-nodes-zapwhat version

Antes de publicar una versión nueva sube version en package.json y ejecuta npm run build && npm run lint.

Limitaciones conocidas

  • El puerto/URL de tu n8n debe ser accesible desde internet para que ZapWhat pueda entregar los webhooks.
  • La edición de mensajes solo aplica a mensajes de texto enviados desde ZapWhat y dentro de los primeros 15 minutos.
  • Los archivos enviados con Enviar Archivo deben estar accesibles por URL pública (WhatsApp los descarga desde esa URL).

Soporte

Licencia MIT.

Discussion