n8n-nodes-iiu-agent

n8n community nodes for the IIU Agent WhatsApp API Gateway

Installation • Credentials • Nodes • Examples • Compatibility

---

✨ Overview

Two n8n nodes that connect your workflows to a self-hosted IIU Agent WhatsApp API Gateway — send and receive WhatsApp messages, manage contacts, and react to events in real time.

Node	Type	Purpose
IIU Agent	Action	Send messages, check contacts, manage sessions and webhooks
IIU Agent Trigger	Trigger	Start workflows on incoming messages and session events

---

📦 Installation

Community Nodes (recommended)

1. In n8n, open Settings → Community Nodes
2. Select Install
3. Enter @toojo.nariv/n8n-nodes-iiu-agent (or n8n-nodes-iiu-agent) and accept the prompt
4. Restart n8n

Manual

cd ~/.n8n/nodes
npm install @toojo.nariv/n8n-nodes-iiu-agent

---

🔑 Credentials

Create an IIU Agent API credential:

Field	Description
Server URL	IIU Agent server URL, without a trailing slash or /api. Defaults to http://localhost:2785 for a local server (e.g. https://wa.example.com behind a reverse proxy). Use HTTPS in production.
API Key	API key from your IIU Agent dashboard. Sent as the X-API-Key header.

The credential is validated with an authenticated GET /api/sessions request, so an invalid API key fails the test.

API key role: send-message and webhook operations require an OPERATOR-role key (the default). A read-only VIEWER key passes the credential test but returns 403 when sending or managing webhooks. VIEWER-safe operations: Session → Get Status / List All, and Contact → Check Exists / Get Info. An ADMIN key also works for every operation.

---

🧩 Nodes

IIU Agent (action)

Resource	Operation	Description
Session	Create	Create a new session (returns its UUID)
Session	Start	Start a session and connect to WhatsApp
Session	Stop	Stop a session and disconnect
Session	Force Kill	Force-kill a stuck session's engine
Session	Delete	Delete a session
Session	Get QR	Get the QR code for scanning authentication
Session	Request Pairing Code	Get an 8-char phone linking code
Session	Get Status	Get the status of a session
Session	List All	List all sessions
Message	Send Text	Send a text message
Message	Send Image	Send an image (binary, URL, or Base64)
Message	Send Video	Send a video (binary, URL, or Base64)
Message	Send Document	Send a document / file
Message	Send Audio	Send an audio file or a voice note (PTT)
Message	Send Sticker	Send a sticker (WebP)
Message	Send Location	Send a location pin
Message	Send Contact	Send a contact card (vCard)
Message	Reply	Reply to a message, quoting it
Message	React	Add or remove an emoji reaction
Message	Delete	Delete / revoke a message
Message	Send Bulk	Send up to 100 messages as a throttled batch
Message	Get Batch Status	Poll a bulk batch's progress
Message	Cancel Batch	Cancel a running bulk batch
Contact	Check Exists	Check whether a number is on WhatsApp
Contact	Get Info	Get contact information
Contact	Get Profile Picture	Get a contact's profile-photo URL
Contact	Get Phone	Resolve a contact's phone number
Contact	Block	Block a contact
Contact	Unblock	Unblock a contact
Webhook	Create	Register a webhook (optional signing secret)
Webhook	Update	Update a webhook (partial — only changed fields)
Webhook	Test	Send a test delivery to a webhook
Webhook	Delete	Remove a webhook

Example — send a text message

1. Add an IIU Agent node
2. Select the Message resource and Send Text operation
3. Configure Session ID (default), Chat ID (628123456789@c.us), and Message

IIU Agent Trigger

Starts a workflow when the selected events arrive on your session.

Event	Description
message.received	New incoming message
message.sent	Message successfully sent
message.ack	Message delivery / read acknowledgement
message.failed	Message failed to send
message.revoked	Message deleted for everyone
message.reaction	Reaction added to or removed from a message
session.status	Session status changed
session.qr	QR code generated for scanning
session.authenticated	Session authenticated
session.disconnected	Session lost connection

🔐 Signature verification

The Trigger has an optional Webhook Secret. When set, the secret is registered with IIU Agent at webhook creation, and IIU Agent signs every delivery with HMAC-SHA256 in the X-OpenWA-Signature: sha256=<hex> header. The node verifies each delivery against the raw request body and rejects (HTTP 401) any that fail. Leave it empty to skip verification.

Trigger output

{
  "event": "message.received",
  "timestamp": "2026-07-28T10:30:00Z",
  "sessionId": "default",
  "idempotencyKey": "a1b2c3d4-...",
  "deliveryId": "e5f6a7b8-...",
  "data": {
    "id": "3EB0F5A2B4C...",
    "chatId": "628123456789@c.us",
    "from": "628123456789@c.us",
    "body": "Hello!",
    "type": "text",
    "timestamp": 1705312200
  }
}

---

📡 Example Workflows

Pattern	Flow
Auto-reply	[IIU Agent Trigger] → [IF: keyword] → [IIU Agent: Send Text]
Session monitor	[IIU Agent Trigger: session.disconnected] → [Slack: Alert]
Lead capture	[IIU Agent Trigger] → [Google Sheets: Append] → [IIU Agent: Send Text]

---

🛠 Development

npm install      # install dependencies
npm run build    # compile TypeScript + copy icons
npm run dev      # watch mode
npm run lint     # ESLint
npm test         # build + unit tests

---

📄 License

MIT — free for personal and commercial use.