Vobiz nodes for n8n

Bring Vobiz voice and WhatsApp into your n8n workflows. Place calls that speak a message, answer incoming calls, act the moment a call is answered or ends, pull call records and recordings, send and receive WhatsApp messages, and set up sub-accounts for your customers or teams, KYC included, all without writing code or running a server of your own.

Package: @vobiz-ai/n8n-nodes-vobiz

Contents

• What's included
• Installation
• Credentials
• Nodes
• Quick start: a call that speaks
• Every call on the account
• Example workflows
• Good to know
• Security
• Troubleshooting
• Upgrading from 0.2
• Compatibility
• Development
• Support
• License

What's included

To act on every call on your account, or on new recordings, use n8n's Schedule Trigger with the Vobiz node: see Every call on the account.

The Vobiz node can also be used as a tool by n8n's AI Agent.

Installation

Self-hosted n8n

1. Go to Settings → Community Nodes and select Install.
2. Enter @vobiz-ai/n8n-nodes-vobiz, agree to the risks of using community nodes, and select Install.
3. Search for Vobiz in the nodes panel.

Self-hosted n8n with npm (Docker, queue mode)

mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install @vobiz-ai/n8n-nodes-vobiz

Restart n8n afterwards.

n8n Cloud

Once the package is verified by n8n, the Vobiz nodes appear directly in the nodes panel.

See n8n's community nodes installation guide for more options.

Credentials

You need a Vobiz account.

1. In the Vobiz console, open Settings → API and copy your Auth ID (it starts with MA_) and your Auth Token.
2. In n8n, create a Vobiz API credential and paste both.
3. Leave API URL set to https://api.vobiz.ai.
4. Select Save. n8n checks the credential with Vobiz straight away.

Nodes

Vobiz

Sub-accounts

A sub-account is a separate account under yours, with its own Auth ID (SA_…), Auth Token, numbers and call records. Its usage is billed to your main account. Manage sub-accounts with your main account's credential (MA_…).

• KYC: a personal use sub-account shares your KYC and can make calls at once, which suits your own teams and testing. A customer use sub-account is for a customer who must be verified in their own name: it needs an email address, and it cannot make calls until their KYC passes. Start KYC sends them the Vobiz KYC page; the Vobiz Trigger (Source: Sub-Account KYC) tells you the result.
• The Auth Token is shown once. Create returns it in its output; Vobiz never shows it again. Save it straight away, for example in a Vobiz credential for the sub-account. n8n also keeps it in that run's execution data.
• Acting as a sub-account: to make calls or read call records as the sub-account, add another Vobiz credential with the sub-account's Auth ID and Auth Token, and pick it in the node.
• Taking a number back works only if the number has had no calls for 15 days. Vobiz keeps a number that was used recently with the sub-account, so people who still dial it don't reach someone else. Unassign Number says until when.
• Switching a sub-account to customer use blocks its calls at once, until its own KYC passes.
• Delete is permanent: Vobiz revokes the sub-account's Auth ID and Auth Token at once.

Vobiz Trigger

One trigger for everything Vobiz reports the moment it happens. Choose its Source: Calls, WhatsApp or Sub-Account KYC. Each source shows only its own settings.

Source: Calls

Your n8n phone line. When a call is answered, Vobiz asks this trigger what to do. The trigger replies at once with a spoken message, then runs your workflow. The message can be:

• spoken in any of 16 languages, with a man's or a woman's voice;
• optionally followed by an audio file;
• or replaced entirely by your own Vobiz XML.

After the message, Then decides what happens, with no XML to write:

Menus, forwarding and voicemail need the workflow to be published: Vobiz sends the key, the forwarding result and the recording to the trigger's Production URL.

Settings:

• Trigger On: Call Answered, Call Ended, Key Pressed, Forward Finished and Voicemail Recorded, in any mix. Call Ended fires the moment the call finishes, with its duration, whether it was answered and how it ended. Key Pressed gives the key. Forward Finished says whether the number answered. Voicemail Recorded gives the recording's recording_id and length; pass the ID to Vobiz → Recording → Download to get the audio.
• Outgoing calls: paste the trigger's Production URL into Answer URL on Vobiz → Call → Make.
• Incoming calls: choose numbers in Answer Incoming Calls On. They are connected when you publish the workflow and released when you unpublish it.
• Require Vobiz Signature (on by default): Vobiz signs every call event with your Auth Token. The trigger checks that signature, so someone who learns its address cannot start your workflow with made-up calls. A signature that does not match is always refused. Turn this off only if your Vobiz account sends events without a signature.

When the workflow is published, the trigger creates a Vobiz application for its address, named n8n-call-answered-…. It removes the application when the workflow is unpublished.

Your existing setups are safe. The trigger only takes numbers that aren't linked to anything else. It refuses a number already used by another application (such as a CRM integration) or routed to a SIP trunk, and changes nothing in your account when it does. The number list labels each number not linked, on a SIP trunk or used by … so you can see which ones are free.

Source: WhatsApp

Starts a workflow when a customer sends you a WhatsApp message (Message Received), or when a message you sent is sent, delivered, read or fails (Message Status Changed).

• It registers itself with Vobiz when you publish the workflow, and removes itself when you unpublish it.
• Every event is checked against a signature made with a secret only this trigger knows. Forged events are refused.
• You can limit it to one WhatsApp channel.

Source: Sub-Account KYC

Starts a workflow when a customer sub-account's KYC moves on: KYC Started, Documents Submitted, KYC Completed, KYC Failed, Link Expired or Link Revoked.

1. Publish the workflow, open the trigger, and copy its Production URL.
2. On Vobiz → Sub-Account → Start KYC, paste it into Options → Webhook URL. Vobiz then reports that customer's KYC to the trigger.

• Use your main account's credential: Vobiz signs each KYC event with that account's Auth Token, and the trigger checks the signature. Forged events are refused, and so are unsigned ones while Require Vobiz Signature is on.
• You can limit it to one sub-account.
• The output names the sub-account (sub_account_id) and the result (status), so the next node knows which customer it was. It also passes on any metadata Vobiz sends back. To check that the customer can now make calls, add Vobiz → Sub-Account → Get KYC Status.

Quick start: a call that speaks

When a call is answered, Vobiz asks a web address what to say. The Vobiz Trigger, with Source: Calls, is that address.

1. Create a workflow with a Vobiz Trigger, keep Source on Calls, set its Message, and Publish the workflow.
2. Open the trigger, select Webhook URLs → Production URL, and copy the address. It contains /webhook/, not /webhook-test/.
3. In another workflow, add Vobiz → Call → Make. Pick a From Number, enter the number to call in To, and paste the address into Answer URL.
4. To say something different on each call, fill in Message on Make a Call, for example Hi {{ $json.name }}, your appointment is tomorrow at 10. It replaces the trigger's message for that call.
5. To act once the call is over, for example to log it or send a WhatsApp follow-up, tick Call Ended in the trigger's Trigger On.

A call between two people

n8n cannot talk on a call itself, so Vobiz rings two phones and connects them: first the one in To, then the one in Connect To.

1. Set up the Vobiz Trigger (Source: Calls) once, as above, and paste its Production URL into Answer URL on Make a Call.
2. In Make a Call, put your own phone (or your agent's) in To, and the person to talk to in Connect To. Both can come from your data, such as {{ $json.phone }} from a sheet or CRM row.
3. Leave Message empty to connect straight away, or set one, such as "Connecting you to Asha", to hear it first.

When the first phone answers, Vobiz rings the second, showing your Vobiz number, and connects them. If the second phone does not answer, the first hears the trigger's No Answer Message (or can leave a voicemail). Each connected phone is billed as its own call.

Every call on the account

The Vobiz Trigger fires for calls that go through it. To act on every call on your account, including calls on numbers used by other setups such as a CRM integration, let n8n check Vobiz on a schedule:

1. Schedule Trigger, for example every 5 minutes.
2. Vobiz → Call Record → Get Many, with a Limit above the number of calls you expect between checks.
3. Remove Duplicates with Operation Remove Items Processed in Previous Executions and Value to Dedupe On {{ $json.uuid }}, so each call is passed on only once. The first run passes on every call it finds.

For new recordings, use Vobiz → Recording → Get Many instead, dedupe on {{ $json.recording_id }}, then Recording → Download to get the audio.

Example workflows

• Appointment reminders: Google Sheets or a schedule → Vobiz: Make a Call with a personalised message.
• Log every call: Schedule → Vobiz: Call Record → Get Many → Remove Duplicates → Google Sheets or your CRM.
• Missed-call follow-up: Vobiz Trigger (Calls; Trigger On: Call Ended) → If not answered → Vobiz: Send a WhatsApp template.
• Phone menu with voicemail to email: Vobiz Trigger (Calls; Then: Menu; 1 forwards to sales, 2 takes a voicemail; Trigger On: Voicemail Recorded) → Vobiz: Recording → Download → Gmail.
• Agent missed the call: Vobiz Trigger (Calls; Then: Forward; Trigger On: Forward Finished) → If not answered → Slack.
• Recordings to cloud storage: Schedule → Vobiz: Recording → Get Many → Remove Duplicates → Recording → Download → Google Drive.
• WhatsApp auto-reply: Vobiz Trigger (WhatsApp; Message Received) → Vobiz: Send a WhatsApp text.
• Daily call report: Schedule → Vobiz: Call Record → Get Summary → Slack.
• Customer onboarding: a sign-up form → Vobiz: Sub-Account → Create (customer use) → Start KYC by email. Then Vobiz Trigger (Sub-Account KYC; KYC Completed) → Assign Number → a WhatsApp welcome.

Good to know

• Instant triggers need a public address. Vobiz sends events over the internet, so the Vobiz Trigger needs n8n to be reachable over HTTPS. This works automatically on n8n Cloud. On self-hosted n8n, set WEBHOOK_URL to your public address.
• If your public address changes, for example with a tunnel that gets a new address on every restart, unpublish and publish your trigger workflows again so Vobiz uses the new address.
• WhatsApp's 24-hour rule. Free-form messages can only be sent within 24 hours of the customer's last message. For a first message, or outside that window, send an approved template. A free-form message sent outside the window is reported as failed in a Message Status Changed event.
• Recordings are private. Their links need your Vobiz credential, so use Recording → Download to get the file.
• Call records appear a few seconds after a call ends.
• Phone numbers use international format with the country code, for example +919876543210. Spaces and dashes are removed for you.
• Hang Up on Voicemail is off by default. Voicemail detection listens for up to 5 seconds and can mistake a person who stays silent for a machine.
• Avoid Retry On Fail on Make a Call. If a request is retried, the same call can be placed twice.

Security

• Your Auth ID and Auth Token are kept in n8n's encrypted credential store and are sent only to Vobiz.
• Recording downloads send your credential only to Vobiz hosts, never to any other domain.
• Call events to the Vobiz Trigger (Calls) are verified against Vobiz's X-Vobiz-Signature-V3 (or V2) header, an HMAC-SHA256 of the trigger's address and a nonce, keyed with your Auth Token. Forged events are rejected with 403, and so are unsigned ones while Require Vobiz Signature is on.
• WhatsApp events are verified with HMAC-SHA256, using a secret created for each subscription. Unsigned or forged events are rejected.
• KYC events to the Vobiz Trigger (Sub-Account KYC) are verified against Vobiz's X-Vobiz-Signature header, an HMAC-SHA256 of the raw body keyed with your main account's Auth Token. Forged events are rejected with 401, and so are unsigned ones while Require Vobiz Signature is on.
• A new sub-account's Auth Token is passed on only by Create, the one time Vobiz shows it. Every other sub-account operation leaves the token out of its output.
• The package has no runtime dependencies beyond n8n itself.

Troubleshooting

Upgrading from 0.2

Version 0.3 merges the four triggers into one Vobiz Trigger, as n8n asks of verified packages. Nothing was taken away.

1. Before you update, unpublish the workflows that use the old triggers. This releases their numbers, Vobiz applications and WhatsApp subscriptions.
2. Update the package.
3. In each workflow, replace the old trigger with the Vobiz Trigger, choose its Source, and enter the same settings.
4. Publish again. The new trigger has a new Production URL: paste it into Answer URL on Make a Call, and into Webhook URL on Start KYC.

Compatibility

Built with @n8n/node-cli and tested with n8n 2.37. You need a Vobiz account; the WhatsApp features also need a WhatsApp channel on that account.

Development

Use a current Node.js 24 (see .nvmrc; 24.21 or newer). The npm bundled with older 24.x releases (11.9 and earlier) rejects the lockfile in npm ci.

git clone https://github.com/vobiz-ai/Vobiz-n8n-nodes.git
cd Vobiz-n8n-nodes
npm install
npm run build   # compile to dist/
npm run lint    # n8n's lint rules
npm test        # unit tests against a mock Vobiz API

npm run test:e2e runs the built nodes inside a real n8n against the mock API, so nothing is called, texted or billed. To run a local n8n with the nodes loaded and test against a real Vobiz account, run npm run n8n (Windows, macOS or Linux) and see TESTING.md.

Issues and pull requests are welcome.

Support

• Vobiz API documentation: vobiz.ai/docs
• Bugs and feature requests: GitHub Issues
• Vobiz account and billing: support@vobiz.ai

Version history

See CHANGELOG.md.

License

MIT © Vobiz AI