---
sidebar_position: 1
title: n8n Integration
description: Official n8n community nodes for Firetell — automate programmable calls, SMS/MMS, Voice AI agents, Knowledge Bases, and HMAC-verified webhook triggers.
slug: /developers/integrations/n8n
---

# n8n Integration (`@firetell/n8n-nodes-firetell`)

The official **`@firetell/n8n-nodes-firetell`** community node package brings Firetell's programmable voice, SMS/MMS, Voice AI agents, Knowledge Bases, and real-time webhook events directly into your **n8n** workflows.

- **Package:** [`@firetell/n8n-nodes-firetell`](https://www.npmjs.com/package/@firetell/n8n-nodes-firetell)
- **Repository:** [`github.com/firetellcom/firetell-n8n-nodes`](https://github.com/firetellcom/firetell-n8n-nodes) (MIT License)
- **Zero runtime dependencies** (uses native n8n HTTP helpers and `node:crypto`)
- **AI Agent Tool compatible** (`usableAsTool: true`) — attach the Firetell node directly to n8n AI Agents

---

## 1. Installation

### Option A: Install via n8n UI (Recommended)

1. Open your n8n instance and navigate to **Settings → Community Nodes**.
2. Click **Install a community node**.
3. Enter `@firetell/n8n-nodes-firetell`, acknowledge the prompt, and click **Install**.

### Option B: Manual Installation (Self-Hosted)

```bash
npm install @firetell/n8n-nodes-firetell
```

---

## 2. Configure Credentials (`Firetell API`)

1. In your Firetell Console, generate a workspace **API Secret Key** (`sk-...`).
2. In n8n, open **Credentials → New Credential → Firetell API**.
3. Fill in:
   - **Workspace Domain:** Your Firetell workspace domain (e.g. `yourcompany.firetell.app`).
   - **API Secret Key:** Your secret key (`sk-...`).
4. Click **Test** to verify the connection (`GET /api/v1` with `Authorization: ApiKey <secretKey>`).

> [!TIP]
> The credential test runs against your workspace's metadata endpoint (`/api/v1`) so you can immediately verify both your domain and secret key before building workflows.

---

## 3. Firetell Trigger Node

The **Firetell Trigger** node starts a workflow whenever selected Firetell events occur.

### Automatic Webhook Management

- When you **Activate** or **Publish** a workflow, n8n automatically registers (or updates in-place via `PATCH`) its webhook URL in Firetell (`POST /api/v1/webhooks`) and deduplicates any stale endpoints sharing the same URL.
- When you **Deactivate** the workflow, n8n automatically cleans up the webhook (`DELETE /api/v1/webhooks/{id}`).

### HMAC-SHA256 Signature Verification

- **Verify Webhook Signature** is enabled by default (`true`).
- Every incoming request is verified against the `X-Webhook-Signature` header using `HMAC-SHA256` (`crypto.timingSafeEqual`) over the raw request body.
- Requests with missing or invalid signatures are rejected with HTTP `401 Unauthorized` before triggering your workflow.
- If you manually configure a webhook in Firetell Console, you can supply its secret via **Options → Manual Webhook Secret**.

### Supported Webhook Events (18)

| Category | Events |
| :--- | :--- |
| **Calls** | `call.created`, `call.answered`, `call.ended`, `call.recording.ready`, `call.transcription.completed`, `call.transcription.summary` |
| **Messages (SMS/MMS)** | `message.received`, `message.sent`, `message.delivered`, `message.failed`, `message.undelivered` |
| **Contacts** | `contact.created`, `contact.updated`, `contact.deleted` |
| **Agents** | `agent.created`, `agent.updated`, `agent.deleted` |
| **Workspace** | `workspace.credit.updated` |

---

## 4. Firetell Action Node

The **Firetell** action node follows n8n's **Resource → Operation** pattern, includes dynamic dropdowns (`loadOptions`) for Phone Numbers, Voice AI Agents, Knowledge Bases, Address Books, Agents, and Teams, and can also be attached directly as a **Tool** to an **n8n AI Agent**.

| Resource | Operations |
| :--- | :--- |
| **Call** | `Make Call`, `Send Actions`, `Get Many`, `Get Events`, `Get Recordings`, `Get Transcription` |
| **Message (SMS/MMS)** | `Send`, `Get`, `Get Many` |
| **Contact** | `Lookup by Phone`, `Create`, `Get`, `Get Many`, `Update`, `Delete` |
| **Address Book** | `Create`, `Get`, `Get Many`, `Update`, `Delete` |
| **Voice AI Agent** | `Get Many`, `Get`, `Create`, `Update`, `Update Settings`, `Publish Version` |
| **Knowledge Base** | `Get Many`, `Get`, `Create`, `Upload Document` *(binary)*, `Crawl URLs`, `Recrawl Document`, `Delete Document` |
| **Phone Number** | `Get Many`, `Get`, `Update` |
| **Agent** | `Get Many`, `Get`, `Create`, `Update`, `Delete` |
| **Team** | `Get Many`, `Get`, `Create`, `Update`, `Delete`, `Add Agent`, `Remove Agent` |

---

## 5. Popular Workflow Recipes

### Post-Call AI Summary & Sentiment to Slack / CRM
1. **Firetell Trigger** listening on `call.transcription.summary` (or `call.ended`).
2. **Firetell** → *Call: Get Transcription* to retrieve full transcript, summary, sentiment, and action items.
3. **Firetell** → *Contact: Lookup by Phone* to enrich caller details.
4. **Slack / HubSpot / Google Sheets** node to log the call summary and create follow-up tasks.

### Auto-Sync Documents from Google Drive to Firetell Knowledge Base
1. **Google Drive Trigger** on new/updated PDF or DOCX files in a folder.
2. **Google Drive** → *Download File* (outputs binary property `data`).
3. **Firetell** → *Knowledge Base: Upload Document* (input binary field `data`) to automatically index the document for your Voice AI agents.

### After-Hours Call Flow Routing
1. **Schedule Trigger** running at 6:00 PM / 9:00 AM.
2. **Firetell** → *Phone Number: Update* to switch `call_flow_id` between business-hours and after-hours Voice AI flows.

---

## Related Documentation

- [Workspace API Reference](/developers/rest-api/overview)
- [Webhooks Guide](/developers/rest-api/workspace-api/webhooks)
- [Authentication](/developers/getting-started/authentication)
- [Node.js Server SDK (`@firetell/firetell-node-sdk`)](/developers/sdks/nodejs/installation)
