n8n-nodes-wavonyx

An n8n community node for Wavonyx, a
self-hosted WhatsApp gateway. Send WhatsApp messages and media from a workflow, and start workflows
when messages arrive.

Installation · Credentials · Operations ·
Wavonyx Trigger · Compatibility

[!IMPORTANT]
This node talks to a Wavonyx server that you run yourself — it is not a hosted service. Wavonyx
drives WhatsApp through an unofficial protocol, so the linked account can be banned if its traffic
looks automated. Use a number you can afford to lose, and don't send bulk messages.

Installation

Follow the community node installation guide,
then enter n8n-nodes-wavonyx as the npm package name.

You also need a running Wavonyx server. It builds from
source — Docker compiles it for you, so no Go toolchain is needed:

git clone https://github.com/phalconyx/Wavonyx.git
cd Wavonyx
docker compose up -d

Then link a WhatsApp account. The same binary is also its own CLI, so run it inside the container and
scan the QR code it draws in your terminal:

docker compose exec wavonyx /usr/local/bin/wavonyx connect support

Keep the server's data volume: it holds the WhatsApp credentials, and losing it means pairing again.

Credentials

Create a Wavonyx API credential:

Use Test connection to confirm the server is reachable — it calls /health.

[!TIP]
localhost means different things in different places. When n8n runs in a container, localhost
there is that container — not your machine. Use an address that resolves from inside it, such as
the Wavonyx service name when both containers share a Docker network.

Operations

Message

Recipients are international numbers without a leading + or 0 (for example 628123456789), or
an explicit JID such as 628123456789@s.whatsapp.net. Groups use …@g.us.

Session

Wavonyx Trigger

Starts a workflow when a message arrives. Activating the workflow registers the webhook for you:
n8n points that session at its own URL, and deactivating clears it again. There is nothing to
configure on the server.

Events you can subscribe to:

• Message Received — a new inbound message
• Message Edited — a sender changed a message they had sent (edited_id names the original)
• Message Deleted — a message was deleted for everyone

Under Options you can restrict the trigger to direct messages or to groups.

When Wavonyx can't reach n8n

The trigger registers whatever URL n8n advertises, by default
http://localhost:5678/…. That is right only while Wavonyx runs alongside n8n
on the same host. Once they are separate containers, localhost inside the
Wavonyx container is Wavonyx itself, so deliveries fail and the trigger never
fires — with the message still arriving at Wavonyx, which makes it look like the
node is at fault. Wavonyx logs the real reason:

webhook delivery gave up  url=http://localhost:5678/webhook/…  err="connection refused"

Point n8n at an address Wavonyx can dial, using n8n's own
N8N_WEBHOOK_URL
setting — it controls webhook addresses independently of the editor URL, so
browser access is unaffected:

N8N_WEBHOOK_URL=http://n8n:5678/

That form works when both containers share a Docker network, which is the most
portable arrangement. Otherwise use whatever address resolves from wherever
Wavonyx runs: a published host address, or the host-gateway alias your Docker
runtime provides.

When a Webhook Secret is set on the credential, every delivery's X-Wavonyx-Signature header is
verified with HMAC-SHA256 and anything that fails is rejected with 401. Leaving the secret empty
skips verification — fine on a trusted network, not on the public internet.

Each item looks like this — the message fields sit at the top level, alongside the event metadata,
so expressions read the same as they do after a Get Many:

{
  "event": "message",
  "session_id": "support",
  "ts": "2026-08-09T10:00:00Z",
  "message_id": "3EB0…",
  "chat": "628987654321@s.whatsapp.net",
  "sender_phone": "628987654321",
  "push_name": "Jane Cooper",
  "is_group": false,
  "kind": "image",
  "text": "look at this",
  "media": { "mimetype": "image/jpeg", "file_size": 183422, "token": "eyJrIjoi…" }
}

To fetch an attachment, chain a Wavonyx → Message → Download Media node and leave the Media
Reference field at its default, {{ $json.media.token }}.

[!NOTE]
Several photos sent at once arrive as separate messages, one trigger execution each, since
WhatsApp only groups them visually. Each carries its own token, so every item downloads
independently. There is no album identifier to correlate them by.

[!NOTE]
A session delivers to one webhook at a time, so pointing two active workflows at the same session
means the last one activated wins. Give each workflow its own session.

Compatibility

Built against n8n's node API version 1 and tested on n8n 2.x. It also needs a Wavonyx server new
enough to expose PATCH /sessions/{id}, which the trigger uses to register its own webhook.

Resources

• Wavonyx — the gateway this node drives
• n8n community nodes documentation

License

MIT