n8n-nodes-zapi

Community node for n8n that integrates with Z-API (WhatsApp messaging).

This package adds Z-API nodes to n8n, enabling WhatsApp messaging automation and related features.

---

n8n Cloud note (Verified Community Node)

To be installable in n8n Cloud, this package must be approved as a Verified Community Node.
Non-verified community nodes can only be installed in self-hosted n8n.

---

What this node does

With this node you can:

- Send WhatsApp messages (text, media, lists/buttons, location, PIX button)
- Manage chats (pin, archive, delete, list)
- Manage contacts (metadata, profile picture, list, phone existence check)
- Manage groups (members/admins, settings, metadata, invite links)
- Manage instance utilities (disconnect, QR code, device data, phone code)
- Manage message queue (list and delete)
- Manage products linked to a phone (upsert, delete, get, list)
- Post status updates (text/image)
- Make direct API calls (advanced)

---

Requirements

- n8n (self-hosted) or n8n Cloud (Verified required to install)
- A Z-API account with an active instance
- Z-API credentials:
- Instance ID
- Instance Token
- Client Token (Account Security Token)

---

Installation

$3

Install as a community node and restart n8n.

$3

Only Verified Community Nodes are installable in n8n Cloud.
After approval, the package appears in the Cloud UI under Community Nodes.

---

Credentials (Z-API API)

This package provides the credential type:

Z-API API (zapiApi)

$3

#### Instance ID
Your Z-API instance identifier.

#### Instance Token
Token for the selected instance.

#### Client Token
Z-API Account Security Token. This is sent as an HTTP header:

- Client-Token:

$3

The credential test checks the instance status endpoint:

- GET https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/status

(plus the Client-Token header)

---

Resources & Operations

Below is the full list of operations in this package (grouped by resource).

$3

- Make an API call

$3

- Archive chat
- Delete chat
- List chats
- Pin chat

$3

- Check phone exists
- Get contact metadata
- Get profile picture
- List contacts

$3

- Create group
- Add participant
- Remove participant
- Promote to admin
- Demote admin
- Leave group
- Update description
- Update photo
- Update name
- Update settings
- Get invitation metadata
- Get group metadata
- Send invite link

$3

- Disconnect phone
- Get device data
- Get QRCode bytes
- Get QRCode image
- Get phone code

$3

- Send text message
- Delete message
- Read a message
- Reply to a message
- Send an audio
- Send a button list
- Send a contact
- Send a document
- Send a link
- Send a location
- Send an image
- Send an option list
- Send a PIX button
- Send a sticker
- Send a video

$3

- Delete queue message
- Get queue messages

$3

- Upsert product
- Delete product
- Get product
- Get products by phone
- List products

$3

- Post image to status
- Post text to status

---

Data formats & validation rules

$3

- Must be digits only and include country code + area code + number
- Example (Brazil): 5511999999999

$3

- Z-API recommends values between 1 and 15 seconds
- If set to 0, API default behavior is used (depending on operation)

$3

Some operations require a groupId (example: 120363019502650977-group).
You can usually obtain it via group metadata endpoints or webhook payloads.

$3

Many operations accept media as:

- URL: https://...
- Data URI: data:;base64,
- Raw Base64 (no prefix): the node may normalize it into a Data URI automatically

Examples:
- URL: https://example.com/image.png
- Data URI: data:image/png;base64,iVBORw0K...
- Raw Base64: iVBORw0KGgoAAAANSUhEUg...

For documents, providing a filename with extension (example: invoice.pdf) is recommended.

---

Quick usage examples

$3

Resource: Messages → Send text message

- Phone Number: 5511999999999
- Message: Hello from n8n!
- Delay (seconds): 2

$3

Resource: Messages → Send an image

- Phone Number: 5511999999999
- Image (URL or Base64):
- https://example.com/image.png
- or data:image/png;base64,iVBORw0K...

$3

Resource: Messages → Send a document

- Phone Number: 5511999999999
- Document: https://example.com/invoice.pdf (or Base64/Data URI)
- File Name: invoice.pdf (recommended)
- Caption: Invoice attached

$3

Resource: Messages → Reply to a message

- Phone Number: 5511999999999 (or group ID)
- Message ID:
- Message: Got it!

$3

Resource: Groups → Create group

- Group Name: My Group
- Participants: add at least one phone
- Auto invite: enable if you want to invite participants who cannot be added directly

$3

Resource: Instance → Get QRCode image

Use this to display a scannable QR when connecting an instance.

---

Troubleshooting

$3

For Verified Community Nodes, avoid any:
- use unknown and type guards
- define small interfaces for API responses you depend on
- avoid (value as any) whenever possible

$3

- Confirm Client Token is the Z-API Account Security Token
- Confirm Instance ID and Instance Token belong to the same instance
- Confirm the instance is active and allowed to call the endpoint

$3

- Verify the instance is connected/online
- Verify phone format (digits only)
- For media: ensure URL is public/reachable or Base64 is valid
- Try a delay of 1–3 seconds

$3

- Run npm run build
- Restart n8n
- Clear browser cache / hard refresh

---

Development

``bash
npm install
npm run dev
npm run lint
npm run build
`

Publishing notes (n8n Cloud / Verified)

To be installable in n8n Cloud, this package must be approved as a Verified Community Node. In practice, that means it must:

- Follow the package naming convention: n8n-nodes- or @scope/n8n-nodes-
- Include the keyword: n8n-community-node-package
- Define the n8n section in package.json`, listing the built node and credential entrypoints
- Avoid unsafe runtime behavior (for example: filesystem access, environment secrets, etc.)
- Pass the community package scanner before submission

License

MIT