salesby-whatsapp

n8n community nodes for Salesby for WhatsApp: send text, template and media messages, manage contacts, conversations, templates and campaigns, and a signed webhook trigger for every inbox event.

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

  1. In Salesby for WhatsApp create an API key. It is shown exactly once and looks like sbw_live_….
  2. 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/v1 is removed automatically). It must start with https://; http:// is only
      accepted for localhost, so the API key never travels unencrypted.
    • API Key – the sbw_live_… key. It is sent as Authorization: Bearer <key>.
  3. 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), via
GET /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 description
n8n: <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> where
v1 = 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 same id (also in the header Salesby-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 check id themselves.
  • 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_at of 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 (default api) and note.
  • Delivery errors: when WhatsApp rejects a message, the API answers 502 (permanent) or 503
    (temporary) with code delivery_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 for Retry-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 with
    duplicate: true in 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 as YYYY-MM-DD or
    DD.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-workflow 2.16 and tested with n8n 2.x. The nodes use
    NodeConnectionTypes and usableAsTool, 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-workflow is 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

License

MIT

Discussion