Description

n8n-nodes-sendseven

This is an n8n community node for SendSeven – a unified messaging API platform enabling multi-channel messaging through WhatsApp, Telegram, SMS, Email, Messenger, Instagram, and more.

n8n is a fair-code licensed workflow automation platform.

Installation

Follow the installation guide in the n8n community nodes documentation.

npm Installation

npm install n8n-nodes-sendseven

Manual Installation

1. Clone this repository
2. Run npm install
3. Run npm run build
4. Copy the dist folder to your n8n custom nodes directory

Operations

SendSeven Node (Actions)

#### Message

• Send: Send a message through any channel (WhatsApp, Telegram, SMS, Email, etc.)

– Supports attachments: provide a comma-separated list of attachment UUIDs (from the Attachment resource) in the Attachment IDs field. These map to the attachments array of POST /messages. Raw URLs are not accepted — upload first.
– Multiple attachments are delivered as separate messages, in the order listed, with the Message Text attached only to the first — except on an Email channel, where all attachments go out together as one email. Each attachment message is billed separately (the email exception is billed as one message). The output’s new relatedMessageIds field lists the IDs of the additional messages (parts 2..N); it’s empty for ordinary single-part sends.

#### Contact

• Create: Create a new contact. A Custom Fields mapper lets you set any of the tenant’s active custom fields (by definition, one row per field, typed per its field_type) at the same time — leave a row unmapped to skip it.
• Update: Update an existing contact (name, email, phone, avatar URL). Has its own Custom Fields mapper (same as Create). Blank/unmapped rows are never sent — SendSeven treats blank the same as clearing the field on update, so an untouched row must never risk wiping it. To deliberately clear a field, use Set Custom Field‘s Clear Field option instead, or map an expression that evaluates to a real null.
• Get: Get a contact by ID
• Delete: Delete a contact (GDPR delete — conversations anonymized, billing preserved)
• Search: Search contacts by name, email, or phone
• Add Tag: Add a tag to a contact
• Remove Tag: Remove a tag from a contact
• Set Custom Field: Set (or, with Clear Field Instead, clear) a single custom field on a contact. The Custom Field dropdown is populated from your tenant’s active field definitions (GET /custom-fields?activeonly=true). The value is written via PUT /contacts/{id} with { customfields: { id>: value } } — the same validated bulk endpoint as Create/Update — so an invalid value (wrong type, not one of a select’s options, an unknown/deleted field, etc.) fails with a clear, per-field error instead of silently accepting bad data. This replaced the legacy POST /contacts/{id}/fields/{fieldid} write, which has no server-side type validation.
• Add Method: Add a contact method (platform ID). Method types: phone, email, whatsappid, telegramid, messengerid, instagramid. For messengerid/instagramid a Channel must be selected (these IDs are page-scoped).
• Delete Method: Delete a contact method by its method ID.

#### Conversation

• Get: Get a conversation by ID
• Search: Search conversations by contact, status, or channel type
• Close: Close a conversation
• Assign: Assign a conversation to a team member

#### List

• Add Member: Add (subscribe) a contact to a static or newsletter list — POST /lists/{list_id}/members. Channel Type is a required field (defaults to Email) so every workflow explicitly states which channel the subscription is for; it’s ignored server-side for static lists. Channel Type = Telegram, Messenger, or Instagram additionally requires Channel ID (which bot/page). The same contact can subscribe to the same newsletter via multiple channels by running this operation once per channel.
• Remove Member: Remove (unsubscribe) a contact from a list — DELETE /lists/{listid}/members/{contactid}. Same Channel Type / Channel ID rules as Add Member; removes only the subscription for the specified channel.

Both operations work against static lists too (Channel Type is sent but ignored there). Dynamic lists cannot have members added/removed directly — their membership comes from segment conditions.

> Note on the backend’s channeltype default: the SendSeven API has a deprecated fallback where a newsletter list add/remove with no channeltype defaults to email (kept indefinitely for old raw-HTTP callers, e.g. workflows built before this node had a List resource). This node never relies on that fallback — it always sends channel_type explicitly.

#### WhatsApp Template

• Send: Send a pre-approved WhatsApp template message. Provide at least one recipient (Contact ID is no longer mandatory):

– Contact ID — a contact; uses its first WhatsApp method, phone as fallback.
– WhatsApp ID — a phone number without a leading + (stripped automatically) or an alphanumeric WhatsApp ID; matches an existing contact or creates one (ideal for stateless integrations).
– Contact Method ID (Additional Options) — target a specific WhatsApp number when a contact has several; must be a whatsapp_id-type method. If Contact ID is also set it must name the same contact.
– Conversation ID (Additional Options) — send within an existing WhatsApp conversation.

Additional Options also expose Channel ID (disambiguates a template referenced by NAME across channels, and selects the sending channel when only a WhatsApp ID is given), Language (Meta locale code such as en, de, enUS, ptBR — needed only when a template name exists in multiple languages; auto-resolved from the contact’s preferred language otherwise), Header Media URL, Header Document Filename, and Variable Values (JSON).

• List: List available WhatsApp templates

#### Attachment

• Upload: Upload a binary file (from an incoming binary property such as the output of an HTTP/Read-Binary node) as a multipart POST /attachments/upload. Returns the attachment id.
• Upload from URL: Fetch a public http(s) URL server-side via POST /attachments/from-url and store it. Returns the attachment id. Note: the URL-fetch MIME allowlist is stricter than direct upload (images, mp4/mov/webm, common audio, pdf).

##### Sending a message with an attachment

Chain two nodes:

1. Attachment → Upload (or Upload from URL) — produces an attachment object whose id is the attachment UUID.
2. Message → Send — set the Attachment IDs field to an expression referencing the previous node’s id (e.g. {{ $json.id }}), or a comma-separated list of several UUIDs. The node passes these into the attachments array of POST /messages, and the channel adapter renders them by content type (e.g. WhatsApp image/document, email attachment). Listing several UUIDs sends them as separate messages, in order, with the caption/text on the first — except on Email, where they’re combined into one email with multiple attachments.

#### Team Chat

• Send Channel Message: Post a message to a Team Chat channel as a bot — POST /team-chat/bot/channels/{channel_ref}/messages. Channel accepts either the channel UUID or a name such as #general or general. The channel must have “Allow Bots to send messages” enabled in its Team Chat settings; system channels (e.g. #knowledgebase) never accept bot messages. Bot messages always render with a bot avatar; Bot Name (Additional Fields) sets the display name shown, up to 50 characters.
• Send Direct Message: Send a Team Chat direct message to a user as a bot — POST /team-chat/bot/users/{user_id}/messages. Always allowed once authenticated — there is no “Allow Bots” setting for DMs.
• Both operations support attachments in either form (Additional Fields): a comma-separated Attachment IDs list (previously uploaded via the Attachment resource), or an Attachment URL (+ optional Attachment Filename) for a public image/video/audio URL that SendSeven downloads server-side. Use whichever form fits your workflow.
• Requires the teamchat:write OAuth2 scope (bot-only — distinct from the human team_chat:* scopes). Existing OAuth2 credentials must be reconnected once to pick up this scope.

SendSeven WhatsApp & more Node (Webhooks)

Listen for real-time events:

• Message Received: Triggers when a new inbound message is received
• Message Sent: Triggers when an outbound message is delivered
• Message Delivered: Triggers when message delivery is confirmed
• Message Failed: Triggers when a message fails to send
• Message Read: Triggers when a message read receipt is received
• Email Received: Triggers when an inbound email is received
• Email Sent: Triggers when an outbound email is sent
• Email Delivered: Triggers when an email delivery is confirmed
• Email Bounced: Triggers when an email bounces
• Email Opened: Triggers when an email is opened
• Conversation Created: Triggers when a new conversation starts
• Conversation Closed: Triggers when a conversation is closed
• Conversation Assigned: Triggers when a conversation is assigned to an agent
• Conversation Reopened: Triggers when a conversation is reopened
• Contact Created: Triggers when a new contact is created
• Contact Updated: Triggers when a contact is updated
• Contact Deleted: Triggers when a contact is deleted
• Link Clicked: Triggers when a tracked link is clicked
• Campaign Sent: Triggers when a campaign completes sending
• Team Chat Message Created: Triggers when a bot- or human-authored message is posted to a Team Chat channel with “Allow Bots” enabled. Use the Channel Filter field (accepts a channel UUID or a name such as #general/general) to restrict the trigger to one channel; leave it blank to receive messages from every eligible channel. Important: Team Chat direct messages never trigger this node — SendSeven only publishes a webhook for channel messages, so there is no way to subscribe to DM events.

Authentication

This node supports two authentication methods:

API Key (Recommended for most users)

1. Log in to your SendSeven account at https://app.sendseven.com
2. Navigate to Settings > API Tokens
3. Create a new API token with the required scopes
4. Copy the token (format: s7_xxxxxxxxxxxx)
5. In n8n, add a new credential of type “SendSeven API”
6. Paste your API token

OAuth2 (For advanced integrations)

1. Log in to your SendSeven account
2. Navigate to Settings > OAuth Apps
3. Create a new OAuth application
4. Configure the redirect URI to match your n8n instance
5. In n8n, add a new credential of type “SendSeven OAuth2 API”
6. Complete the OAuth2 authorization flow

Required Scopes

Different operations require different scopes:

| Operation | Required Scopes |
|———–|—————–|
| Send Message | messages:create |
| Upload Attachment | messages:create |
| Read Messages | messages:read |
| Create/Update Contact (incl. Custom Fields mapper) | contacts:create, contacts:update |
| Delete Contact / Add or Delete Method / Set Custom Field | contacts:update (delete: contacts:delete) |
| Read Contacts | contacts:read |
| Read Custom Field Definitions | settings:read |
| Manage Tags | tags:read |
| Read Conversations | conversations:read |
| Manage Conversations | conversations:update |
| Add/Remove List Member | lists:update |
| Webhooks | webhooks:create, webhooks:read, webhooks:delete |
| Knowledge Base | knowledge_base:read |
| Team Members | team:read |
| Send Team Chat Channel/Direct Message | teamchat:write (bot-only; no underscore — distinct from the human team_chat:* scopes) |

Example Workflows

Send WhatsApp notification on new CRM lead

1. Add a trigger from your CRM (e.g., HubSpot, Salesforce)
2. Add SendSeven node with “WhatsApp Template > Send” operation
3. Map the lead data to template variables

Log support conversations to spreadsheet

1. Add SendSeven WhatsApp & more with “Conversation Closed” event
2. Add Google Sheets node to append row
3. Map conversation data to spreadsheet columns

Auto-respond to incoming messages

1. Add SendSeven WhatsApp & more with “Message Received” event
2. Add IF node to check message content
3. Add SendSeven node with “Message > Send” to reply

Resources

• SendSeven Documentation
• SendSeven API Reference
• n8n Community Nodes

Support

• Email: dev@sendseven.com
• Documentation: https://docs.sendseven.com/guides/integrations/n8n
• Status: https://status.sendseven.com

License

MIT License – see LICENSE file for details.

Changelog

Unreleased — Contact custom fields (Create/Update mapper + validated Set Custom Field)

• Added a “Custom Fields” resourceMapper to Contact → Create and Contact → Update — one row per active custom field definition (name, type, and select options shown inline), loaded live via a new getCustomFieldColumns resource-mapping method (GET /custom-fields?activeonly=true, paginated). Values are sent as customfields: { : value } on POST/PUT /contacts. Rows left unmapped, or mapped to a blank/empty value, are never sent (SendSeven treats blank the same as an explicit clear on update — an unmapped row must never accidentally wipe a field); an explicit null (e.g. from an expression) is passed through as a deliberate clear.
• Contact → Set Custom Field now routes through the validated bulk endpoint (PUT /contacts/{id} with a single-key customfields map) instead of the legacy POST /contacts/{id}/fields/{fieldid}, which had no type validation. Added a Clear Field Instead boolean for parity with the new bulk clear behavior. The Custom Field dropdown now filters to active fields only (active_only: true) and shows each field’s type.
• Friendly 422 handling: an invalid custom-field value (wrong type, not a valid select option, an unknown/deleted field definition, a duplicate, etc.) now raises a clear, per-field error naming the field instead of a generic HTTP failure — resolves the field id back to its current name via a fresh lookup. Never echoes the submitted value.
• Fixed a latent bug: any 422 whose detail was a list of validation objects (not just custom-field errors) previously rendered as the literal string "[object Object]" in thrown errors; getErrorMessage() now joins each item’s own msg.
• Old backend compatibility: against a not-yet-deployed backend that silently drops customfields in the create/update body and ignores activeonly, the mapper still loads (listing inactive fields too) and create/update requests still succeed — the extra customfields key is simply ignored, same as before this change. getCustomFields‘s dropdown may list inactive fields until the backend recognizes activeonly.
• No existing parameter renamed or removed — purely additive. Not yet republished to npm.

1.5.0 — Team Chat Bots: send actions + trigger

• Added Team Chat resource to the SendSeven node with two new operations: Send Channel Message (POST /team-chat/bot/channels/{channelref}/messages, channel by UUID or #name) and Send Direct Message (POST /team-chat/bot/users/{userid}/messages). Both support attachments via a comma-separated Attachment IDs field or a public Attachment URL + optional Attachment Filename.
• Added team_chat.message.created to the Trigger node’s Events dropdown, with a new Channel Filter field (channel UUID or #name) matched client-side against both the channel ID and name. Direct messages never trigger this node — SendSeven only emits a webhook for channel messages.
• Added the teamchat:write OAuth2 scope (bot-only; deliberately no underscore, distinct from the human team_chat:* scopes) to the SendSeven OAuth2 credential. Existing OAuth2-authenticated workflows must reconnect the credential once to pick up the new scope before these actions/trigger will work.

Unreleased — Contact Subscribed / Unsubscribed trigger events

• Added contact.subscribed and contact.unsubscribed to the Trigger node’s Events dropdown — previously these backend events existed and already fired in production, but were not selectable here at all, so no n8n workflow could react to a newsletter opt-in/opt-out.
• Added a matching switch case in webhook() that formats the payload’s data.subscription object (listid, listname, channeltype, channelid, status, optinmethod) into a subscription field alongside the standard contact field, instead of falling through to the generic default: passthrough.
• No new backend event or request-shape change — purely additive to the trigger node. Not yet republished to npm.

1.4.1

• Fix (List → Remove Member): Channel ID (listChannelId) is now read and sent as channelid on DELETE /lists/{listid}/members/{contact_id} when Channel Type is Telegram, Messenger, or Instagram — it was previously collected in the UI but silently dropped, so the backend could not identify the correct channel-scoped subscription to remove. Mirrors the existing Add Member behavior.
• Fix (OAuth2 credentials): Added the missing lists:update scope to the OAuth2 default scope string — required for both List → Add Member and List → Remove Member, as already documented in the Required Scopes table below.

1.4.0

• Added List resource with Add Member / Remove Member operations (POST/DELETE /lists/{listid}/members[/{contactid}]), fixing the case where n8n users had no first-class way to subscribe/unsubscribe a contact from a newsletter list and were forced onto the generic HTTP Request node (which previously 501’d on newsletter lists before a backend fix).
• Channel Type is a required field on both operations (options: Email/SMS/WhatsApp/Telegram/Messenger/Instagram; defaults to Email) — this node always sends it explicitly rather than relying on the backend’s deprecated missing-channel_type-defaults-to-email fallback. Channel ID is additionally required (and only shown) when Channel Type is Telegram, Messenger, or Instagram (page/bot-scoped).
• Added getLists loadOptions dropdown (GET /lists).
• Purely additive — no existing resource, operation, or field changed. Existing workflows are unaffected.

Unreleased — Multi-attachment fan-out (copy update, not yet republished)

• Message → Send: docs/descriptions no longer imply attachments beyond the first are dropped. POST /messages now fans out N attachments into N separate messages (in order, text on the first) instead of silently discarding parts 2..N — the Attachment IDs field’s documented “comma-separated UUIDs” behavior is now actually true for more than one ID.
• Additive response field: formatMessageResponse now also returns relatedMessageIds (array of message IDs, parts 2..N, empty by default). No existing field changed or removed.
• Billing note: sending N attachments now creates N billable messages instead of 1 (except on an Email channel, which still sends one email with all attachments as MIME parts).
• No request-shape or client-side parsing changes — the comma-split logic already produced a flat UUID array, which is unaffected. Not yet published to npm.

1.2.4

• Republished from GitHub Actions with an npm provenance statement (required for n8n verified community node review). No functional changes from 1.2.3.
• Normalized repository.url to the git+https://...git form required for provenance verification.

1.2.0

• BREAKING FIX (custom fields): Custom fields are no longer sent in the contact Create/Update body — the backend silently dropped them (they are not contact-body fields). The dead Custom Fields JSON option was removed from Contact → Create. Use the new Contact → Set Custom Field operation, which resolves the field definition via GET /custom-fields (loadOptions dropdown) and writes the value via POST /contacts/{id}/fields/{field_id}. Action required: any workflow that relied on the old Custom Fields create/update option must switch to Set Custom Field — the old option had no effect.
• Added Attachment resource:

– Upload — binary input → multipart POST /attachments/upload (file part file, optional message_id).
– Upload from URL — POST /attachments/from-url (stricter MIME allowlist).
– Both return the attachment id for downstream use.

• Message → Send: added an Attachment IDs field (comma-separated attachment UUIDs) wired into the attachments array of POST /messages.
• Added Contact → Delete (DELETE /contacts/{id}, GDPR delete).
• Added Contact → Add Method / Delete Method (POST/DELETE /contacts/{id}/methods). Channel selection is shown conditionally and required for messengerid/instagramid.
• Added Contact → Remove Tag (DELETE /contacts/{id}/tags/{tag_id}).
• Added getCustomFields loadOptions helper and a sendSevenApiRequestFormData helper for authenticated multipart uploads.

1.1.0

• BREAKING: Webhook endpoint path changed from /webhooks to /webhook-endpoints
• BREAKING: Conversation close now uses POST (was PUT) with notes field (was resolution_note)
• BREAKING: Conversation assign now uses POST with user_id in URL path (was PUT with body)
• BREAKING: Removed pending conversation status (only open and closed remain)
• Added 3 message addressing modes: Recipient+Channel, Conversation ID, Contact+Channel
• Added contact_methods support for contact creation
• Updated contact fields: removed firstName, lastName, company, notes; added contactMethods, language, isBlocked
• Updated conversation fields: assigneduserid (was assignedtouserid), added needsreply, islivechat, isemail, subject; removed messagecount, unread_count
• Updated contact update to only accept name, email, phone, avatar_url
• Added close options: notes and summarize fields
• Added conversation search filter: needs_reply
• Updated webhook events: added message.delivered, message.failed, message.read, email.*, conversation.assigned, conversation.reopened, contact.deleted, link.clicked; removed message.status_updated, ticket.created, ticket.closed
• Updated OAuth2 scopes: replaced webhooks:update with webhooks:create/webhooks:delete; added knowledge_base:read, team:read

1.0.0

• Initial release
• Actions: Send Message, Create/Update/Get/Search Contact, Add Tag, Get/Search Conversation, Close/Assign Conversation, Send WhatsApp Template
• Triggers: Message Received/Sent, Conversation Created/Closed, Contact Created/Updated, Ticket Created/Closed, Campaign Sent
• Authentication: API Key and OAuth2 support