neogo

n8n community node for NeoGo WhatsApp API

Package Information

Released: 4 mo ago
Downloads: 22 weekly / 145 monthly
Latest Version: 0.1.0
Author: NeoGo

Available Nodes

NeoGo icon
NeoGo
Send WhatsApp messages and manage instances via the NeoGo API
NeoGo Trigger icon
NeoGo Trigger
Starts a workflow when NeoGo pushes a WhatsApp event via webhook

Documentation

n8n-nodes-neogo

n8n community node for the NeoGo WhatsApp API.

It lets you send WhatsApp messages, manage instances, and trigger workflows from incoming WhatsApp events (messages, calls, connection changes, …) — all without writing code.

Status: v0.1.0 (MVP). Send Text / Media / Location, basic instance management, and a webhook Trigger. More operations are planned (see Roadmap).

Installation

In n8n (Community Nodes)

  1. Go to Settings → Community Nodes.
  2. Select Install.
  3. Enter n8n-nodes-neogo and confirm.

Manually (self-hosted)

npm install n8n-nodes-neogo

Then restart n8n. The NeoGo and NeoGo Trigger nodes will appear in the node panel.

Credentials

Both nodes use a single NeoGo API credential:

Field Description
Base URL Your NeoGo server URL, e.g. http://localhost:4000 or https://api.example.com
API Key Either an instance token or the Global API Key — see below

The key is sent on every request as the apikey header.

Which key do I need?

NeoGo uses two auth levels, and the right one depends on what you do:

Action Required key
Send Text / Media / Location (/send/*) Instance token
Instance: Get Many / Get Info / Create Global API Key
Trigger auto-registering its webhook Global API Key

The Global API Key is your NeoGo server's GLOBAL_API_KEY. The two key types are not interchangeable: /send/* accepts only an instance token, while Instance operations and the Trigger's webhook registration accept only the Global API Key.

Two-credential workflows. A workflow that both triggers on events (Global key) and sends messages (instance token) needs two NeoGo API credentials — one with the Global key for the Trigger, one with the instance token for the Send node. The example templates are wired with a single placeholder credential; split them before going live.

Actions node — NeoGo

Resource: Message

Operation Endpoint Notes
Send Text POST /send/text Plain text message
Send Media POST /send/media Image / Video / Audio / Document, via URL or base64
Send Location POST /send/location Latitude / Longitude + optional name & address

The Phone Number field accepts a number with country code (e.g. 5511999999999) or a full JID. NeoGo normalizes it server-side.

Resource: Instance

Operation Endpoint Notes
Get Many GET /instance/all List all instances (Global key)
Get Info GET /instance/info/{id} Single instance details (Global key)
Create POST /instance/create Create instance, optionally with a webhook URL and auto-connect (Global key)

Trigger node — NeoGo Trigger

Starts a workflow whenever NeoGo pushes a WhatsApp event to a webhook.

How it works

NeoGo supports up to 3 webhook slots per instance. When you activate a workflow containing this node, it registers n8n's generated webhook URL into the chosen slot via PUT /instance/{instanceId}/webhooks/{slot}. When you deactivate the workflow, it removes that slot again.

Fields

Field Description
Instance ID The NeoGo instance to receive events from
Events Which event types start the workflow: Message, Send Message, Connection, QR Code, Presence, Read Receipt, Call, Group
Webhook Slot Which of the 3 slots to use (default 1) — pick an unused one so you don't overwrite an existing webhook
Auto-Register Webhook When on (default), registers/unregisters the webhook automatically (needs the Global API Key)

Event filtering

The selected Events are filtered inside the node on the incoming payload's top-level event field. The node registers the slot with an empty server-side event list (= all events) on purpose: NeoGo's per-slot filter matches lowercased raw event names, so client-side filtering is the reliable path. Pick exactly the events you want and the node drops the rest.

Webhook payload shape

Each delivered event is a JSON body with these top-level fields:

{
  "event": "Message",          // event type (raw whatsmeow name, e.g. Message, Receipt, Connected, CallOffer; CONNECTION is uppercase)
  "data": { /* raw whatsmeow event — e.g. Info.Sender, Info.Chat, Message.conversation */ },
  "instanceId": "your-instance-id",
  "instanceName": "your-instance-name"
}

For an incoming message the sender JID is at data.Info.Sender and the text at data.Message.conversation (or data.Message.extendedTextMessage.text for replies/links). Inspect a real event in n8n before building expressions — protobuf message fields are JSON-encoded in lowerCamelCase.

NeoGo also sends these delivery headers (handled automatically by n8n):

  • X-Webhook-Request-Id — stable across retries (dedupe)
  • X-Webhook-Timestamp, X-Webhook-Attempt
  • X-Hub-Signature-256 — sha256=<HMAC-SHA256(body, secret)> when a slot secret is set

Manual webhook setup (fallback)

If you can't give n8n the Global API Key, turn Auto-Register Webhook off and register the webhook yourself, pointing it at the node's Production Webhook URL (copy it from the node):

curl -X PUT "https://YOUR_NEOGO/instance/INSTANCE_ID/webhooks/1" \
  -H "apikey: GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://YOUR_N8N/webhook/.../webhook", "events": [], "enabled": true }'

Leave events empty (all events) — the node filters by type on its own.

Example workflows

Importable templates live in templates/:

  • auto-reply.json — auto-reply to any incoming WhatsApp message.
  • lead-capture.json — turn incoming messages into structured leads and acknowledge them.

Import via Workflows → Import from File, then replace YOUR_INSTANCE_ID and select your NeoGo credential.

Roadmap

Planned for future releases (not in v0.1.0):

  • More send operations: Button, List, Template, Contact, Sticker, Poll
  • Group management, contact lookup, media download
  • Operation generation from the NeoGo OpenAPI/Swagger spec

Resources

License

MIT

Discussion