Description

@kapso/n8n-nodes-kapso

This is an n8n community node package for Kapso WhatsApp automations.

It includes a trigger for inbound Kapso/WhatsApp webhook events and an action node for sending outbound WhatsApp messages through Kapso.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Example workflows
Local testing
Resources
Version history

Installation

Follow the installation guide in the n8n community nodes documentation.

Package name: @kapso/n8n-nodes-kapso.

Operations

Kapso Trigger

Starts workflows from Kapso webhooks:

• Phone-number events such as whatsapp.message.received, delivery statuses, and conversation lifecycle events.
• Project events such as whatsapp.phone_number.created and workflow execution events.

Kapso

Actions available in workflows:

• List connected WhatsApp phone numbers.
• List WhatsApp messages stored by Kapso.
• Send WhatsApp text messages.
• Send WhatsApp template messages.
• Send raw WhatsApp Cloud API message payloads.
• Mark WhatsApp messages as read, optionally with a typing indicator.

Credentials

Create a Kapso API credential with:

• API Key: your Kapso API key. The node sends it as X-API-Key.
• Base URL: defaults to https://api.kapso.ai.
• Meta Graph Version: defaults to v24.0.

Compatibility

Generated with the official @n8n/create-node scaffold and tested against the installed n8n node tooling in this repository.

Usage

For inbound WhatsApp messages, use Kapso Trigger with scope Phone Number, enter the Meta phonenumberid, and subscribe to whatsapp.message.received.

Inbound WhatsApp identity is not always phone-based. A normalized Kapso payload can contain message.fromuserid, message.username, conversation.businessscopeduserid, and conversation.parentbusinessscopeduserid while message.from or conversation.phonenumber is absent. Keep the BSUID fields in downstream storage and match by BSUID before phone number.

For outbound messages, use Kapso with the Send Text, Send Template, or Send Raw Payload operations. The raw payload operation mirrors the WhatsApp Cloud API payload sent to /{phonenumberid}/messages.

Example workflows

Inbound WhatsApp message to n8n workflow

1. Add Kapso Trigger as the first node.
2. Set Scope to Phone Number.
3. Enter the Meta phonenumberid for the WhatsApp sender managed in Kapso.
4. Keep Events set to whatsapp.message.received.
5. Leave Verify Signature enabled in production.
6. Connect any downstream n8n nodes that should process the inbound message payload.

This workflow starts whenever Kapso delivers a WhatsApp inbound message webhook to n8n.

Send a WhatsApp reply through Kapso

1. Add a Kapso node after any trigger or workflow step.
2. Set Resource to WhatsApp Message.
3. Set Operation to Send Text.
4. Enter the sender Phone Number ID.
5. Choose Recipient Mode:
– Phone Number when the inbound payload includes a phone number.
– Business-Scoped User ID (BSUID) when only a BSUID is available.
– Phone Number and BSUID when both are available. WhatsApp gives the phone number precedence.
6. Enter the corresponding recipient identifiers. BSUIDs must be kept whole, for example US.13491208655302741918.
7. Set Message to a static value or an n8n expression from an earlier node.

Use Send Template instead when sending approved WhatsApp template messages outside the customer service window.
Authentication templates cannot be sent to BSUID recipients.

To react when Meta changes a contact’s BSUID, subscribe the trigger to whatsapp.contact.identity_changed. Its payload contains the updated contact plus the previous BSUID values so downstream records can be re-keyed safely.

Local testing

Run the package in a local n8n instance with:

npm run dev

This compiles the node and starts n8n with the local package loaded. For inbound webhook testing, expose local n8n to the internet and set n8n’s public webhook URL before starting it:

WEBHOOKURL=https://your-public-n8n-url.example.com/ N8NPROXY_HOPS=1 npm run dev

Use Tailscale Funnel, not Tailscale Serve, when Kapso needs to call your local n8n instance. tailscale serve 5678 is only reachable inside your tailnet. Kapso is outside your tailnet, so expose n8n with:

tailscale funnel 5678

With Tailscale Funnel, the public URL should forward to local port 5678. The Kapso Trigger webhook endpoint is generated by n8n and shown in the node UI. The node registers that generated URL with Kapso when the workflow is activated or when n8n starts listening for a manual test webhook. The trailing path configured by this node is webhook, but the full URL includes n8n’s workflow-specific webhook ID. If the editor also runs behind the same public URL, set N8NEDITORBASE_URL to that URL too.

If you create the Kapso webhook yourself, set Registration Mode to Manual on the Kapso Trigger node. For n8n’s test URL, you must click Test workflow before sending the WhatsApp message; /webhook-test/... URLs are temporary and n8n only keeps them registered while the workflow is listening for a test event. For persistent delivery, use the production URL shown by n8n, activate the workflow, and register that /webhook/... URL in Kapso.

For local manual testing, disable Verify Signature or send a valid X-Webhook-Signature HMAC header. In production, leave signature verification enabled and either let Kapso return the webhook secret during registration or paste the secret into Webhook Secret.

Resources

• n8n community nodes documentation
• n8n creating nodes documentation
• Kapso business-scoped user IDs guide
• Kapso

Version history

0.2.0

• Add BSUID-aware text and template recipients.
• Add BSUID message filtering and the contact identity changed trigger event.
• Document nullable phone identity and BSUID reply routing.

0.1.3

Adds verification metadata fixes and supported n8n codex categories.

0.1.2

Adds example workflow documentation and Kapso package author metadata for verification.

0.1.1

Adds an npm run test verification script for n8n Creator Portal checks.

0.1.0

Initial Kapso trigger and action nodes.