n8n-nodes-contactship

This is an n8n community node package. It lets you use ContactShip in your n8n workflows.

ContactShip is a contact center platform where AI voice agents and people handle phone calls and WhatsApp conversations together. With these nodes you can start AI phone calls, keep contacts, boards and tasks up to date, send WhatsApp messages and events, manage voice agents and their versions, work with inbox conversations, and run a workflow every time a call ends.

The package has two nodes:

• ContactShip: actions on calls, contacts, boards, tags, tasks, events, WhatsApp, conversations, channels, voice agents and their versions, voices, phone numbers and credits.
• ContactShip Trigger: starts a workflow with the results of a call (outcome, summary, extracted data, transcript), with one output per call result, and with the follow-up closures of text agents.

n8n is a fair-code licensed workflow automation platform.

Installation · Credentials · Operations · ContactShip Trigger · Example workflows · Usage notes · Compatibility · Upgrading from 0.x · Development · Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

In short, on a self-hosted n8n instance:

1. Go to Settings → Community Nodes.
2. Select Install a community node.
3. Enter n8n-nodes-contactship and confirm.

The package has no runtime dependencies: it only uses the HTTP helpers that n8n provides.

Credentials

The nodes use the ContactShip public API (https://api.contactship.ai) with an organization API key, sent in the x-api-key header.

1. Sign in to ContactShip. Your plan must include API access.
2. Open Organization → API Keys and generate a key. Each key belongs to one organization.
3. In n8n, create a ContactShip API credential and paste the key in API Key. Leave Base URL as https://api.contactship.ai unless ContactShip support tells you otherwise.

n8n tests the credential by reading your credit balance (GET /v1/credits), which does not change anything in your account.

Keep the key private: it gives access to the whole organization. See API keys in the ContactShip docs.

Operations

Fields that point to a ContactShip record (agent, agent version, voice, phone number, board, stage, tag, contact, organization member, WhatsApp channel, template) can be picked from a list loaded from your account, or set by ID with an expression. When a list has nothing to pick, it says why (for example, No approved templates in this channel).

• Contact fields can be picked from a list (search by name, phone number or email), or set by ID, phone number or email. With a phone number or email, the node looks the contact up first (GET /v1/contacts/{identifier}).
• Phone numbers show the country (from the calling code), alias and type; voices show gender, accent and language.
• Fields with values that depend on your account (WhatsApp template variables, the {{variables}} of an agent's prompt, your contact properties) show one input per value.

Call

Phone numbers must be in international format (+12125551234). The node removes spaces, dashes, dots and parentheses before sending them.

Get Many sends the phone number filter to ContactShip; the result, status and date filters are applied by the node to the calls ContactShip returns, so a filter on an old date range reads more pages. With a 'Created After' date, the node stops reading at that date.

Agent Variables lists the {{variables}} written in the selected agent's prompt and begin message, one input each (ContactShip's own variables, such as {{contact_data}} or {{current_time}}, are left out). Extra Variables (name and value) and Extra Variables (JSON) add any other context. All of them are sent as additional_data; when two have the same name, the later one wins.

Contact

Contact Properties shows one input per property defined in your organization (GET /v1/organization/contact-properties): a list for properties with options, a number, a toggle or a date picker where it applies, and text otherwise. Custom Properties stores any other field, with a type (text, number, calendar, URL or location).

Board

Boards (pipelines) organize contacts into stages. Each contact on a board is a card.

Tag

WhatsApp

Messages are sent through a WhatsApp Business channel connected in ContactShip, to an existing contact.

The channel list comes from GET /v1/channels (channels of type WABA; disconnected channels show their status).

Send Template: the template list shows the approved templates of the channel as name (language), so a template that exists in several languages can be told apart, and the language is sent with it. With an expression, use the template name, or name:language (for example welcome:es_MX). Variables has two modes:

• Map Each Variable (default) shows one input per value the template needs, with Meta's example values as hints: the header (text variable, or the image, video or document URL, or the location), every body variable ({{1}} or named, such as {{first_name}}) and the button parameters (URL suffix, coupon code, one-time password). The node builds the components array.
• Using JSON sends Components (JSON) as it is, in the Meta Cloud API format.

Event

| Identify Session | Links the session ID of a visit (for example, the Google Analytics client ID) to a contact found by ID, external ID, phone or email, or created. The anonymous events sent with that session move to the contact within a minute. | POST /v1/identify |

Events require the Events add-on. Without it, ContactShip answers 403. Events that ContactShip marks as invalid or rejected stop the node (or are returned with an error field when Continue On Fail is on).

Task

Agent

Create, Update and Update Draft have a Configuration switch: Define Below (one input per field, with the voice picked from a list) or Using JSON (the API field names). Tools (JSON) and Post-Call Analysis Fields (JSON) replace the whole list: read the agent first and send everything it should keep.

Agent Version

The ContactShip editor works on a draft and publishes it explicitly. Publishing archives the previous version.

Voice

Conversation

Conversations (threads) are the WhatsApp and chat conversations of the ContactShip inbox. The ID is returned as thread_id when a WhatsApp message is sent.

Channel

Phone Number

Credit

Output

Version 2 of the ContactShip node returns the records themselves (the data field of the API response). Operations that list records return one item per record, and delete operations return { "deleted": true }. Calls and agents have a Simplify option, on by default, that returns the 10 most useful fields; turn it off to get the full record. Agent Version → Get Many has the same option, which returns the version details without the configuration.

ContactShip Trigger

The trigger receives the post-call webhook that ContactShip sends when a call ends and its analysis is ready, and, from trigger version 2, the follow-up closure webhook of text agents.

Setup

1. Add a ContactShip Trigger node and activate the workflow.
2. Copy the node's Production URL.
3. Send ContactShip that URL in one of these ways:
   • For every call of an agent: in ContactShip, open the voice agent, go to Advanced → Post-call, paste the URL as the webhook and publish the agent. You can also set it with the ContactShip node: Agent → Update → Webhook URL.
   • For one call: in the ContactShip node, Call → Make Phone Call → Additional Fields → Webhook URL.
   • For text-agent follow-ups: open the text agent, go to Advanced → Follow-ups → Close webhook, paste the URL and choose the POST method.
4. Make a test call and check the execution in n8n, and the delivery in ContactShip under Calls → Webhooks.

ContactShip has no API to register webhooks, so the trigger does not create or remove anything in your account: activating or deactivating the workflow only turns the URL on or off. Use the Test URL only while you listen for a test event in the editor.

Outputs

The node has one output per call result:

Each item is the webhook body as ContactShip sends it. The most used fields are:

See Call webhook payload for the full reference and examples. ContactShip can deliver the same call more than once (retries): use data.call.call_id to avoid repeating actions.

Follow-up closures have no data envelope: event, threadId, agentId, closureReason (all_stages_completed_no_response or ai_determined_conversation_resolved), closureReasonDescription, totalStages, currentStage, closedAt, contact (id, phone, name) and conversationSummary. See Follow-up closure webhook. They are not retried, and one conversation can have more than one follow-up cycle.

Authentication

ContactShip does not sign post-call webhooks or add custom headers to them. The n8n webhook URL contains a random ID, so keep it private. The trigger can also require Basic Auth or specific headers and rejects requests that do not match; these options are useful when a proxy or another system calls the URL.

Example workflows

The templates folder has workflows you can import in n8n (Workflows → Import from File). Each one has a sticky note with the setup steps.

Usage notes

• Calls and messages are real. Make Phone Call, Call Contact and the WhatsApp operations contact real people and use credits. Test with your own number first. If a request times out, check the call or message before running it again, so the person is not contacted twice.
• Agent changes go live. Agent → Create and Update, and Agent Version → Publish and Rollback, change what callers hear right away. Use Agent Version → Update Draft to stage a change and publish it later.
• Rate limits. ContactShip limits requests per organization, with a lower limit on listing contacts and calls. When it answers 429, the node says so; turn on Retry On Fail in the node settings to retry automatically.
• Call results arrive later. A call ends seconds after it starts, but its analysis and transcript are ready later. Use the ContactShip Trigger, or poll Get Status and then Get.
• Scheduled calls. A date without a time zone offset is read in the Time Zone field, or in the workflow time zone when it is empty.
• AI agents. Version 2 of the ContactShip node is usable as a tool by n8n AI agents. On self-hosted n8n, community nodes work as tools when N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true is set.

Compatibility

• Requires n8n 1.85.0 or later.
• Built and linted with @n8n/node-cli 0.51 and n8n-workflow 2.42.
• Works on self-hosted n8n. To appear in n8n Cloud, the package must be verified by n8n.

Upgrading from 0.x

Version 1.0.0 keeps the node and credential names (contactShip, contactShipTrigger, contactShipApi), so existing workflows and credentials keep working:

• Workflows created with 0.x keep using version 1 of the ContactShip node, with the same parameters and the same output (the full API response, including statusCode and data).
• New ContactShip nodes use version 2, with the resources and operations listed above. To move a workflow to version 2, add a new ContactShip node and update the expressions that read its output: version 2 returns the records directly (for example $json.id instead of $json.data.id).
• The ContactShip Trigger keeps its webhook path, and workflows created with 0.x keep trigger version 1 with its five outputs, so URLs already pasted in ContactShip keep working. New trigger nodes use version 2, which adds a sixth output, Follow-Up Closed, after the other five.

See the changelog for details.

Development

Requirements: Node.js 24 or later (lts/*) and npm.

git clone https://github.com/contactship/n8n-nodes-contactship.git
cd n8n-nodes-contactship
npm install
npm run build   # compile to dist/
npm run lint    # n8n community node linter
npm run dev     # start n8n with the nodes loaded, at http://localhost:5678

npm run dev starts n8n in a container (Docker or Podman). To use an n8n you run yourself, use npx n8n-node dev --external-n8n.

Releasing

Releases are published to npm from GitHub Actions with a provenance statement, as n8n requires for verified community nodes. The workflow is .github/workflows/publish.yml and runs when a version tag (1.2.3 or v1.2.3) is pushed. The tag must match version in package.json.

One-time setup, on npmjs.com: open the package settings, go to Publish access → Trusted Publishers, add a GitHub Actions publisher with owner contactship, repository n8n-nodes-contactship and workflow publish.yml. No token is needed. As a fallback, create a granular access token with publish rights for this package and store it as the NPM_TOKEN secret of the repository.

To release:

npm run release   # lint, build, bump the version, update the changelog, commit, tag and push

or bump version in package.json, update CHANGELOG.md, commit, and push a tag with the same version (git tag 1.0.1 && git push origin 1.0.1).

Resources

• n8n community nodes documentation
• ContactShip API reference
• ContactShip post-call webhook payload
• ContactShip follow-up closure webhook, inbound context webhook and HTTP tool execution
• ContactShip documentation
• Support: support@contactship.ai or open an issue

License

MIT