Package Information
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 contraGET /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
En n8n abre Settings → Community nodes → Install a community node.
Escribe el nombre del paquete:
n8n-nodes-zapwhatAcepta el aviso de nodo no verificado e instala.
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, devuelveexists. - Listar Instancias:
GET /api/instances, devuelveinstance_id,statusycreated_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.
Añade el nodo ZapWhat Trigger al workflow y elige los Eventos.
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).En ZapWhat entra en Dashboard → Instancia → Webhook y pega esa URL.
Envía un mensaje de WhatsApp a la instancia para comprobar la recepción.
Filtros
- Eventos:
Mensaje Entrante,Mensaje Saliente,Estado de EntregauOtros 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 unSwitchsobreinstanceIdo sobrecategory. - 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-cliarrastraisolated-vm, que necesita Visual Studio
Build Tools. Si no las tienes, instala connpm 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
- Documentación de la API: https://zapwhat.com/docs.php
- Soporte: https://zapwhat.com
Licencia MIT.