Package Information
Available Nodes
Documentation generating…
Documentation
@cypherlenn/n8n-nodes-salesby-whatsapp
n8n community nodes for Salesby for WhatsApp – a WhatsApp Business inbox with contacts, consent
tracking, approved templates, campaigns and signed webhooks.
The package contains:
- Salesby for WhatsApp – an action node (also usable as an AI agent tool) for the REST API v1:
send text, template and media messages, manage contacts, conversations, templates and campaigns. - Salesby for WhatsApp Trigger – starts a workflow for events of the app (incoming messages,
delivery status, contacts, conversations, templates, campaigns). The webhook is registered and removed
automatically and every delivery is signature-checked. - Salesby for WhatsApp API credentials (API key).
n8n is a fair-code licensed
workflow automation platform.
Installation
n8n (self-hosted, community nodes enabled): Settings → Community Nodes → Install, enter@cypherlenn/n8n-nodes-salesby-whatsapp, confirm the risk notice and install. See the
n8n community nodes guide.
Manual installation (self-hosted):
mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install @cypherlenn/n8n-nodes-salesby-whatsapp
# restart n8n
With Docker, run the same inside the container (/home/node/.n8n/nodes) or mount that folder, then
restart the container. A local tarball (npm pack) can be installed the same way:npm install /path/to/cypherlenn-n8n-nodes-salesby-whatsapp-<version>.tgz.
Credentials
- In Salesby for WhatsApp create an API key. It is shown exactly once and looks like
sbw_live_…. - In n8n create credentials Salesby for WhatsApp API:
- Base URL – the address of the app without
/api/v1, e.g.https://whatsapp.example.com
(a trailing/api/v1is removed automatically). It must start withhttps://;http://is only
accepted forlocalhost, so the API key never travels unencrypted. - API Key – the
sbw_live_…key. It is sent asAuthorization: Bearer <key>.
- Base URL – the address of the app without
- Test calls
GET /api/v1/me.
The API key acts with the role of its owner. A key of a deactivated person stops working. These
endpoints need the key of an admin; other roles get 403 forbidden:
- Campaign → Create, Start, Pause, Resume, Cancel (reading campaigns works for every role),
- Contact → Delete,
- the Trigger (it manages webhooks:
GET/POST/PATCH/DELETE /webhooks), - creating, editing or deleting templates (not offered by this node; reading templates works for every role).
Each key has a rate limit (default 120 requests per minute). Treat keys like passwords and use one key
per integration.
Operations
| Resource | Operations |
|---|---|
| Message | Send Text (24-hour window), Send Template (approved template, placeholders, optional header media URL), Send Media (image, video, audio or document by https URL, 24-hour window), Get (with delivery status), Download Media (the file of a message as binary data) |
| Contact | Create (phone, name, email, notes, tags by name, custom fields; Update If Exists = upsert that merges, see below), Update (only the fields you add; tags replace or add; custom fields; Empty Values), Get, Get Many (search, phone, tag, consent; Return All), Delete, Set Consent (granted/revoked with source and note) |
| Conversation | Get, Get Many (status, number, assignee, contact; Return All), Update (status open/closed, assignee), Get Messages (newest first; Return All) |
| Template | Get (with placeholders slots and parameter mapping), Get Many (approved only or all statuses, number, name search) |
| Campaign | Create (name, template, audience: tags / contact IDs / all contacts, optional sender number, header media URL, parameter mapping JSON, scheduled time, start immediately), Get (with statistics), Get Many, Start, Pause, Resume, Cancel |
Sending messages – the recipient is chosen with Send To:
- Phone Number (
to): any number; without country code Germany is assumed. If no contact exists for the
number it is created; New Contact Defaults (name, tags, custom fields) are only used in that case. - Contact (
contact_id) or Conversation (conversation_id).
Optional for every send operation: the sender Number (dropdown of the connected numbers; default: the
default number of the app) and Reply To Message ID (quote a message of the same conversation).
Templates – the Template dropdown lists the approved templates (the language belongs to the
template). Template Parameters offers the placeholders of the chosen template (body.1, header.1,button.0.1 …) with their label and example. Placeholders without a value are filled from the parameter
mapping stored at the template in the app. Templates with an image, video or document header need a
Header Media URL.
Dropdowns are loaded live from the app: numbers, approved templates and their placeholders, tags,
custom contact fields and assignees ("Nobody" and the active people of the team from GET /api/v1/users;
older app versions without that endpoint only offer the owner of the API key). Every dropdown also
accepts an ID via expression.
Download Media – Message → Download Media reads the message (GET /api/v1/messages/{id}) and
returns it as JSON plus its file as binary data (field Put Output File in Field, default data), viaGET /api/v1/messages/{id}/media. The file name is the original one or <message id>.<extension> (e.g.msg_….ogg for voice messages), so it can go straight into a transcription or vision node. Incoming
files are fetched from WhatsApp in the background after message.received fired, so right after
the trigger the message usually has media.state = "pending" and media.url = null; the operation waits
up to Wait for File (Seconds) (default 30) until the file is stored. Files that were sent by link are
fetched from that link (the API key is not sent there). media.url in API answers and events needs the
API key as well; a plain HTTP Request without the credential gets 401.
"Get Many" of contacts, conversations, messages and campaigns follows next_cursor (pages of 100) for
Return All; templates are returned in one list and cut to the Limit. Every record becomes its
own n8n item.
Trigger
Salesby for WhatsApp Trigger registers a webhook when the workflow is activated
(POST /api/v1/webhooks with the n8n webhook URL, the selected events and the descriptionn8n: <workflow> / <node>, so admins can tell the webhooks apart in the app) and stores the returned ID and
signing secret in the workflow's static data (like n8n's own triggers do; anyone who can read the
workflow's static data can read the secret). Deactivating the workflow deletes the webhook
(DELETE /api/v1/webhooks/{id}).
On activation the trigger checks the stored webhook (GET /api/v1/webhooks):
- other n8n URL or other events → updated in place (
PATCH /api/v1/webhooks/{id}); secret and pending
retries stay. If the app rejects the new URL, the old webhook is kept and activation fails with the reason. - gone, deactivated by the app, or no secret stored → replaced by a new webhook with a new secret (the API
shows a secret only once). Events still queued for a deactivated webhook are dropped with it. - other webhooks of the app that point to the same n8n URL (leftovers of a lost answer, a crashed
Listen for test event or a failed delete) are deleted. They could never be verified and only count
towards the limit of 25 webhooks.
Events (empty = every event):
| Event | When |
|---|---|
message.received |
A contact sent a message |
message.sent, message.delivered, message.read, message.failed |
Status of an outgoing message |
conversation.created, conversation.assigned, conversation.closed, conversation.reopened |
Conversation changes |
contact.created, contact.updated, contact.opted_in, contact.opted_out |
Contact changes and consent |
template.status_changed |
Meta approved, rejected or paused a template |
campaign.completed |
A campaign finished sending |
Output: one item per delivery, the JSON body { id, type, created_at, data }. data holds the
objects in the same shape as the REST API, e.g. data.message for message events, data.conversation,data.contact, data.template (plus previous_status) or data.campaign. Message events (message.*)
also carry data.contact (id, phone, name) and the business number data.number (id, phone,label, verified_name), so the recipient of a sent message is {{ $json.data.contact.phone }} without an
extra lookup. With Simplify the item is { type, event_id, event_created_at, ...data } (then{{ $json.contact.phone }}). For message.received with a file, data.message.media.state is usually
still pending – see Download Media.
The test button of the app sends an event of type ping (data.message is a text) whatever events are
selected. It starts the workflow unless Ignore Test Events is on (then the trigger answers 200 and
nothing runs). Deliveries of event types that are not selected are answered with 200 and ignored.
Signature: every delivery carries Salesby-Signature: t=<unix seconds>,v1=<hex> wherev1 = HMAC-SHA256(secret, "<t>.<raw body>"). The trigger verifies it against the stored secret and
rejects invalid signatures and timestamps older than 5 minutes with HTTP 401 without starting the
workflow. If the secret got lost (e.g. the static data was reset), deactivate and activate the workflow.
Requirements and limits:
- The API key must belong to an admin.
- The n8n webhook URL must be public https (no localhost or private networks; the app refuses
them). Run n8n behind a public https address (WEBHOOK_URL) or a tunnel. - n8n's test URL and production URL each create their own webhook. The app allows at most
25 webhooks. - A failed delivery is tried 8 times in total (7 retries, 1 minute up to 2 hours apart, about 4 hours).
An endpoint that keeps failing for about four hours (50 counted failures) is deactivated by the app;
activating the workflow again replaces it. - Delivery is at least once: after a lost answer or an interrupted run the app sends the same event
again, with the sameid(also in the headerSalesby-Event-Id). The trigger remembers the IDs of the
last 500 events of the last 24 hours (in the static data of the node) and answers repeats with 200
without starting the workflow. This is best effort (e.g. two copies arriving at the same moment, or more
than 500 events in between); workflows with side effects should still checkidthemselves. - Order is not guaranteed; sort by
created_at.
Usage notes
- 24-hour window: free text and media can only be sent within 24 hours after the last message of the
contact (window_open/window_expires_atof a conversation). Outside of it, send an approved
template. - Consent: opt-outs are respected like in the app; campaigns only reach contacts with consent.
Contact → Set Consent records an opt-in or opt-out with source (defaultapi) and note. - Delivery errors: when WhatsApp rejects a message, the API answers 502 (permanent) or 503
(temporary) with codedelivery_failed. The node turns this into an error with the WhatsApp message and
the ID of the stored failed message; with Continue On Fail it becomes an item (error,description,httpCode,code). Delivery failures are never retried automatically; rate limits (429) are (up to three
times, waiting forRetry-After, at most 61 seconds). Each request times out after 70 seconds. - Idempotency-Key (Request Options of the send operations): a repeated request with the same key
returns the stored message instead of sending again – ideal for Retry On Fail. The key must be unique
per intended message: use a business key (e.g.order-{{ $json.orderId }}-confirmation) or{{ $execution.id }}-{{ $runIndex }}-{{ $itemIndex }}. Without$runIndex, every batch of
Loop Over Items and every further AI tool call in the same execution reuses the keys of the first run,
and those messages are not sent. A replay (HTTP 200 instead of 201) is marked withduplicate: truein the output item; otherwise the item is the message as returned by the API. If the
stored message had failed, the node reports the failure again; use a new key to send once more. - Custom fields: pick the field from the list (
GET /contact_fields). Dates asYYYY-MM-DDorDD.MM.YYYY, select fields by option name. Unknown keys are rejected. - Tags are given by name, comma-separated; missing tags are created. On Update, Tags Mode decides:
Replace Tags (default) – the contact afterwards has exactly the listed tags, all others are removed;
Add to Existing Tags – the listed tags are added, nothing is removed. - Contact → Update only changes the fields you add under Update Fields or Custom Fields. Empty
values keep the current value (default Empty Values: Keep the Current Value), so an expression that
resolves to nothing never wipes data. To clear fields, set Empty Values to Clear the Field: then an
empty Name, Email, Notes or custom field is cleared, and empty Tags with Replace Tags remove
every tag. If every value is empty, nothing is changed and the contact is returned as it is. - Contact → Create with Update If Exists (upsert) merges into an existing contact with the same
number: given values overwrite, empty values are ignored and tags are added (never removed). - Campaign parameter mapping (Parameter Mapping (JSON)): source per placeholder, e.g.
{"body.1": {"kind": "field", "field": "first_name", "fallback": "there"}, "body.2": {"kind": "text", "value": "20%"}}.
Fields:name,first_name,phone,email,profile_name,custom.<key>. Placeholders without an
entry use the mapping stored at the template; every placeholder needs a source. - Dates: Scheduled At without time zone is read in the workflow time zone and sent as UTC.
- IDs are prefixed:
con_…contacts,cnv_…conversations,msg_…messages,tpl_…templates,cmp_…campaigns,num_…numbers,tag_…tags; people are UUIDs. - Errors show the (German) message of the app, the code (
invalid_request,not_found,conflict,forbidden…), the field and a hint. Network errors (DNS, TLS, refused, timeout) name the base URL.
Compatibility
- Built and type-checked against
n8n-workflow2.16 and tested with n8n 2.x. The nodes useNodeConnectionTypesandusableAsTool, which older n8n 1.x releases do not have; on those the nodes
do not load. Community node API version 1, strict mode, Node.js 20 or later. - No runtime dependencies (
n8n-workflowis a peer dependency). - Requires Salesby for WhatsApp with REST API v1 (
/api/v1, OpenAPI at/api/v1/openapi.json).
Development
npm install
npm run build # n8n-node build → dist/
npm run lint # n8n-node lint (community node rules)
npm test # vitest (mapping, pagination, signature, trigger lifecycle, execute)
# inside the app repository it also compares the event list with src/lib/webhook-events.ts
npm run typecheck # tsc incl. tests
npm run dev # n8n with the node linked, http://localhost:5678
npm pack # cypherlenn-n8n-nodes-salesby-whatsapp-<version>.tgz