Description
@zapi-omni/n8n-nodes-hubmessage
Community node for using the Z-API Omni API in n8n.
It creates and connects WhatsApp channels, sends nine message types, and manages Meta
message templates.
Upgrading from 0.2.x
This release renames the node and its credential internally, and moves to the
api.omni.z-api.io host. Neither is migrated automatically:
- Re-create the Z-API Omni API credential and enter the Secret Key again. The
- Re-add the node in existing workflows and reconnect it. Workflows saved with 0.2.x
new default Base URL is already correct.
will show the old node as unrecognized.
The npm package name is unchanged, so the install string below still applies.
Installation
In a self-hosted n8n instance, open Settings → Community Nodes, select
Install, and enter:
@zapi-omni/n8n-nodes-hubmessage
Restart n8n after installing or updating the package. This package is developed and
tested against n8n 2.x.
Credentials
Create a Z-API Omni API credential with:
https://api.omni.z-api.io;The node sends the key as a Bearer token. Credential validation uses the official,
read-only GET /whatsapp/businesses endpoint.
Resources and operations
Channel
META_WHATSAPP channel with POST /v1/channels. POST /v1/channels/{channelId}/connect using the values returned by the
Z-API Omni Connect SDK.
Message
All message operations send through POST /v1/channels/{channelId}/messages:
Enter the Z-API Omni Channel ID manually. Expressions are supported. Free-form
messages require an open WhatsApp 24-hour conversation window; outside that window,
send an approved template first.
Interactive buttons use reorderable visual editors by default. Reply messages accept
one to three buttons with unique IDs. Action buttons provide URL and Call types with
conditional fields. Both operations also provide a JSON mode for dynamic arrays and
advanced expressions.
Contact phone numbers can be entered with a visual list or as a comma-separated list.
Common formatting characters such as +, spaces, parentheses, dots, and hyphens are
removed before the number is sent. The node requires digits after normalization and
enforces only the E.164 maximum of 15 digits; Z-API Omni remains responsible for
validating whether the complete DDI + DDD + number is routable.
Thumbnail media type provides the documented JPEG and MP4 suggestions plus a Custom
option for other MIME types accepted by Z-API Omni. When a Thumbnail URL is added,
Thumbnail MIME Type must also be added. Custom values must use the type/subtype
format, for example image/png. Template components remain JSON because Meta’s
component schema varies by template type.
Development builds that predate the Options collections stored caption,
interactiveHeader, interactiveFooter, thumbnailUrl, and thumbnailMimeType at
the node root. These fields remain recognized as hidden compatibility parameters and
are used only when their replacement inside Options was not explicitly configured.
New workflows should use Options.
Template
Get Many returns one n8n item per template. An empty API list produces no output
items; enable n8n’s Always Output Data setting when the following branch must run
for an empty list. Sync returns the complete synchronization response as one item.
During integration testing, GET /whatsapp/businesses returned an empty list even
with a connected Meta channel. Z-API Omni confirmed that it was investigating the
backend behavior. Until a production fix is confirmed, an empty Get Many WABAs
result may reflect this known limitation rather than a credential permission issue.
Development
npm install
npm run lint
npm test
Methods, paths, and payloads are validated against the official documentation at
developer.omni.z-api.io.
