n8n Community Node (n8n-nodes-bessai)

The official n8n community node for BESS AI. It gives you drag-and-drop access to the platform from inside n8n workflows — no code and no SDK required. Use it to place calls, run batch campaigns, manage agents and phone numbers, and pull analytics, then wire the results into the 400+ other apps n8n connects to (Google Sheets, Slack, HubSpot, Gmail, ...).

The package ships two nodes:

Node	Type	Purpose
BESS AI	Action	Create calls, manage agents and phone numbers, run batch campaigns, query analytics
BESS AI Trigger	Polling trigger	Starts a workflow when a call completes or a batch campaign changes status

The node has zero runtime dependencies and makes direct authenticated HTTP calls to the BESS AI API.

---

Installation

1. In n8n, go to Settings → Community Nodes
2. Select Install
3. Enter n8n-nodes-bessai and confirm

After installation, "BESS AI" and "BESS AI Trigger" appear in the node palette.

Compatibility: n8n v1.0+ and Node.js 18+.

---

Credential setup

Both nodes authenticate with a single credential type: BESS AI API.

1. Get an API key from the BESS AI dashboard → Settings → API Keys (it looks like bess_sk_... and is shown only once — store it securely).
2. In n8n, go to Credentials → New Credential and search for BESS AI API.
3. Fill in the fields:

Field	Value
API Key	Your BESS AI API key (bess_sk_...)
Base URL	https://api.bess-ai.com (default — change only for self-hosted deployments)

n8n verifies the credential automatically with a lightweight test request when you save it. The key is sent as a Bearer token on every request.

---

Resources and operations

The BESS AI action node exposes five resources. Pick the resource, then the operation, and n8n shows only the relevant fields.

Agent

Operation	What it does
Create	Create a new AI voice agent
Get	Get one agent by ID
Get Many	List all agents (paginated)
Update	Update agent configuration
Publish	Publish/activate an agent (required before it can take calls)
Delete	Delete an agent

Call

Operation	What it does
Create Phone Call	Place an outbound phone call
Create Web Call	Create a browser-based web call session
Get	Get call details (transcript, recording URL, analysis) by ID
Get Many	List calls with optional filters (agent, status, type, date range, batch)
End	End an active call

Phone Number

Operation	What it does
Create	Register a phone number
Get	Get one phone number by ID
Get Many	List all phone numbers
Update	Update number configuration (for example, assign an agent)
Delete	Delete a phone number

Batch Call

Operation	What it does
Create	Create a batch call campaign from a list of contacts
Start	Start dialing a created campaign
Pause	Pause a running campaign
Resume	Resume a paused campaign
Cancel	Cancel a campaign
Get	Get one campaign (status and progress counts) by ID
Get Many	List campaigns

Analytics

Operation	What it does
Get Summary	Aggregate call stats (total calls, durations, success rate)
Get Calls by Day	Daily call counts, optionally filtered by agent and date range

Agent and phone number pickers are dynamic dropdowns — the node fetches your agents and numbers from the API, so you rarely need to paste UUIDs by hand. You can always switch a field to expression mode instead.

Key fields: Call → Create Phone Call

Field	Required	Notes
Agent	yes	Pick from the dropdown, or use an expression with an agent UUID
From Number	yes	E.164 format: +14155552671 — a number registered to your account
To Number	yes	E.164 format
Additional Fields → Metadata	no	JSON object stored with the call
Additional Fields → Dynamic Variables	no	JSON object injected into the agent's prompt at call time

Dynamic variables personalize the agent's script per call: pass {"customer_name": "Alice", "plan": "Pro"} and reference {{customer_name}} inside the agent's prompt.

Key fields: Batch Call → Create

Field	Required	Notes
Agent	yes	Dropdown
From Number	yes	E.164
Contacts	yes	JSON array — each item needs at least phone_number, e.g. [{"phone_number": "+1415...", "dynamic_variables": {"name": "Alice"}}]
Additional Fields → Max Concurrent Calls	no	Simultaneous calls
Additional Fields → Name	no	Campaign name
Additional Fields → Retry Attempts	no	Retries per failed contact

Creating a campaign does not start dialing — add a Batch Call → Start step after it.

---

The BESS AI Trigger node

A polling trigger that starts your workflow when something happens on the platform.

Event	When it fires
New Call Completed	Every time a call ends
New Batch Call Status Change	When a campaign transitions status (for example running → completed); the item includes a previous_status field

Parameters:

Field	Notes
Event	Required — pick one of the two events
Agent ID	Optional filter — leave blank to watch all agents

The trigger polls on the schedule configured in the workflow's polling settings and tracks what it has already seen internally, so it only emits new events — never duplicates. It is polling-based, not a real-time webhook: expect up to one polling interval of latency.

---

Example workflow patterns

1. Call a lead the moment they submit a form

[Webhook / Form Trigger]
  -> [Set: extract name and phone from the form data]
  -> [BESS AI: Call -> Create Phone Call]
       Agent: your qualifier agent
       From Number: +14155550100
       To Number: {{ $json.phone }}
       Dynamic Variables: {"customer_name": "{{ $json.name }}"}
  -> [Respond to Webhook: return the call_id]

The agent calls the visitor within seconds of the form submission, with their name already in its script.

2. Log every finished call to a sheet and update the CRM

[BESS AI Trigger: New Call Completed]
  -> [Google Sheets: Append row]
       (call id, agent, duration, summary)
  -> [IF: call was successful]
       true  -> [HubSpot / Salesforce: Update contact with the call summary]
       false -> [Slack: notify the sales team]

The completed-call item carries the transcript and post-call analysis (summary, sentiment, outcome), so downstream nodes can branch on it directly.

3. Weekly batch campaign from a Google Sheet

[Schedule Trigger: every Monday 9am]
  -> [Google Sheets: Get rows from the "Leads" sheet]
  -> [Code: map rows to a contacts array]
       return [{ json: { contacts: items.map(i => ({
         phone_number: i.json.phone,
         dynamic_variables: { name: i.json.first_name }
       })) } }];
  -> [BESS AI: Batch Call -> Create]
       Agent: your campaign agent
       From Number: +14155550100
       Contacts: {{ $json.contacts }}
  -> [BESS AI: Batch Call -> Start]
       Batch Call ID: {{ $json.batch_call_id }}
  -> [Slack: "Campaign started"]

Pair it with a second workflow on the New Batch Call Status Change trigger to get notified when the campaign finishes.

---

Using the node as an AI agent tool

The BESS AI node is marked as usable-as-tool, so it can be attached directly to an n8n AI Agent node:

1. Add an AI Agent node to the workflow.
2. In the agent's Tools section, add BESS AI.
3. Select the operation (for example Call → Create Phone Call).
4. The AI agent invokes it autonomously when appropriate — for example, "when the user asks to call someone, use the BESS AI tool to place the call."

---

Error handling and constraints

The node supports n8n's Continue On Fail: when enabled, a failed item returns { "error": "..." } as data instead of stopping the workflow, so you can branch on it with an IF node.

Common errors and causes:

Error	Cause
Invalid UUID for "Agent ID"	Malformed agent ID — use the dropdown or a valid UUID expression
401 Unauthorized	API key is wrong or expired
422 Unprocessable Entity	Phone number not in E.164 format, or agent not published
Invalid JSON in "Contacts"	Contacts must be a valid JSON array of objects

Constraints to keep in mind:

• Phone numbers must be E.164: + followed by country code and number, no spaces or dashes (+14155552671).
• Agents must be published before they can take calls — use Agent → Publish first if needed.
• Metadata and Dynamic Variables accept JSON objects only; Contacts must be a JSON array.
• The trigger is polling-based — for latency-sensitive automation, consider the API's webhooks instead.

---

Resources

• BESS AI API reference — the REST endpoints behind each operation
• n8n community nodes documentation
• Support: contact@bess-ai.com