n8n-nodes-wappe

n8n community nodes for Wappe, the WhatsApp CRM and automation platform.
Send WhatsApp messages, manage groups, and start workflows when a contact writes to you.

Installation · Credentials · Operations ·
Trigger · Usage examples · Compatibility · Resources

Installation

Follow the community nodes installation guide
and install the package n8n-nodes-wappe.

Credentials

Each Wappe customer has their own instance, so the credential asks for two values:

n8n checks the credential with GET /api/me. The key is sent in the X-Api-Key header.
An API key only opens the permissions chosen when it was created (the same as OAuth2, below); the
historical key of the instance keeps full access. An operation outside them fails with 403 insufficient_scope.

OAuth2

To give n8n limited permissions instead, choose Authentication → OAuth2 in the node and create a
Wappe OAuth2 API credential:

1. In Wappe → Developers → OAuth applications, create an application. The n8n Cloud redirect URL
   (https://oauth.n8n.cloud/oauth2/callback) is pre-filled; for self-hosted n8n, add the
   OAuth Redirect URL shown in the n8n credential.
2. Copy the Client ID and Client Secret (shown once) into the credential, with your Instance URL.
3. Pick the Permissions (all by default): send messages, read conversations, read / update contacts,
   lists, WhatsApp groups, webhooks (Trigger), usage.
4. Connect my account: a Wappe administrator approves the permissions on the consent screen.

An operation outside the granted permissions fails with 403 insufficient_scope. Access can be revoked
anytime in Wappe → Developers → Connected applications (the Trigger's subscriptions go with it).
The Trigger needs Webhooks, plus Read conversations for message and call events and Read contacts
for contact events.

Operations

Text, template and media sends can quote a message (Options → Reply To Message ID).

Opening a conversation needs consent. Sending to a WhatsApp contact you never exchanged a
message with is refused unless you turn on Options → Contact Has Consented (you attest they
agreed to be contacted), or their consent is already on their Wappe profile. Replying in an existing
conversation needs nothing. Refusals come back with Wappe's message and code:

The node adds an English hint to each of these errors.

Read operations have a
Simplify switch (on by default) that keeps only the useful fields — smaller items, fewer tokens
for AI steps.

Account, chat, contact, template, group and list fields are resource locators: pick from a
searchable list read from your instance, or set an ID, or a name (account label, template name,
list name) - handy in expressions.
The chat can be an international phone number (33612345678), a WhatsApp ID (…@c.us),
a group (…@g.us) or an Instagram recipient (ig:…).
Group operations work on WhatsApp Web accounts. Accounts on the official Meta API don't have groups.

Sending pace, limits and bulk sends

Wappe spaces the automatic sends of each WhatsApp account (API, campaigns and automations share the
same pace: 8 per minute by default, 60 on the official Meta API, with a pause between batches).

• A normal send waits up to 15 seconds for the account's next slot. Beyond that, or when the API
  plan's limits are reached, Wappe answers 429 with a Retry-After header (send_rate,
  rate_limited or daily_quota).
• For bulk sends, turn on Options → Queue Sending: each item returns a jobId at once and Wappe
  sends at the account's pace. Follow them with Get Send Status, or with the Trigger's
  Message Sent / Message Failed events (both carry the jobId).
• To retry a 429 in a normal send, use the node's Settings → Retry On Fail. With Queue Sending,
  retries are safe: the idempotency key returns the same job.
• Starting a new conversation requires Options → Contact Has Consented (Wappe refuses cold outreach).

Trigger

Wappe Trigger starts the workflow on one or more events:

Filters are applied by Wappe before sending, so a filtered-out event never runs the workflow:
accounts, lists (any / all / none, picked from the list, by ID or by name), groups (exclude / include /
only), text (contains / starts with / regex), message type, where a message was sent from, and
reaction emojis (👍, ❤️: skin tone ignored, a removed reaction never matches).
A list set by name is resolved when the workflow is activated: renaming it later changes nothing, and
activation fails with a clear message if it does not exist.

Transcribe Voice Notes: Wappe transcribes the voice note before triggering, the text is in
transcription (text, lang, seconds, remainingSeconds). The minutes are counted once, even if
several workflows ask. If transcription fails, the event is still sent with
transcription.error (quota, disabled or failed).

• When the workflow is activated, n8n subscribes its webhook URL on your instance
  (POST /api/webhooks/subscriptions). When it is deactivated, n8n removes the subscription.
• Every delivery is signed (X-Wappe-Signature: sha256=…, HMAC of the body with a per-subscription
  secret). The node rejects anything unsigned or badly signed.
• Every event has session, chatId, isGroup, from, name; message events add msgId, text,
  type, fromMe, ts, reply, media. With Download Media on, the attachment (photo, voice
  note, video, document) is in the binary property data.
• WhatsApp sometimes delivers the same event twice. Wappe sends it to n8n only once.
• Workflows created before 0.4.0 (node version 1: Message Received, Include Group Messages) keep working.

Wappe only calls public addresses: n8n must be reachable from the internet (SSRF protection).

Usage examples

Import these workflows in n8n (Workflows → Import from File), then pick your Wappe credential in
each node:

The Trigger output feeds the next node directly: use {{ $json.session }} as the account (By ID),
{{ $json.chatId }} as the chat and {{ $json.msgId }} as Reply To Message ID.

More ideas:

• CRM sync: Contact Stage Changed → update the deal in your CRM (after is the new stage).
• Voice notes to text: Message Received with Message Types → Voice and Transcribe Voice
  Notes → append transcription.text to a Google Sheet.
• AI agent: the Wappe node is usable as a tool (AI Agent → Tools → Wappe), so an agent can read
  the conversation history (Message → Get Many) and answer (Message → Send Text).
• Failed sends alert: Message Failed → notify your team on Slack or by email.

Compatibility

Tested with n8n 2.x. No runtime dependencies.

Resources

• n8n community nodes documentation
• Wappe API reference: the Developers page of your instance, or its OpenAPI spec at
  <instance>/api/openapi.client.json

License

MIT

Maintainers

This repository is a read-only mirror of packages/n8n-nodes-wappe in the Wappe monorepo.
To release: bump version in package.json (and CHANGELOG.md) on dev, then tag that commit
n8n-nodes-wappe@X.Y.Z in the monorepo. The mirror job pushes tag X.Y.Z here, and publish.yml
publishes to npm with provenance.