# Carbon Voice + n8n

## Overview

Carbon Voice is the [best interface](../concepts/why-carbonvoice.md) for talking to AI agents on the go.

[n8n](https://n8n.io) is a powerful workflow automation platform that lets you connect apps and build AI-powered workflows with a visual node editor.

Connect Carbon Voice and n8n so you can **talk** to your n8n workflows like you would a chief of staff or other team member.

## Features of this Integration

- **Talk to it with swipe of a button** — Record voice messages to trigger n8n workflows instantly while on-the-go with the mobile app
- **Talk to it with a desktop shortcut** — Start talking to your agent with a single keyboard shortcut
- **Send even when agent is offline and recovers** — Your messages are queued and delivered when n8n comes back online
- **Visual workflow building** — Use n8n's node editor to create complex AI-powered workflows 

---

# Choosing Your Setup Method

There are two ways to integrate Carbon Voice with n8n depending on how you run n8n:

| | Cloud (n8n.io) | Self-Hosted |
|---|---|---|
| **Method** | Webhook trigger | Native Carbon Voice node **or** Webhook trigger |
| **Setup** | ~10 min | ~5 min (native node) |
| **Carbon Voice npm package** | Not yet available (pending n8n approval) | Available now |

> **Self-hosted users:** We publish an official n8n community node — [`@carbonvoice/n8n-nodes-carbonvoice`](https://www.npmjs.com/package/@carbonvoice/n8n-nodes-carbonvoice) — that gives you a native Carbon Voice trigger node with a simpler setup. See [Self-Hosted: Native Node Setup](#self-hosted-native-node-setup) below.
>
> **Cloud (n8n.io) users:** The native node is awaiting approval in the n8n community node registry. Until then, use the [Webhook Setup](#webhook-setup) below.

---

# What You'll Need

* A Carbon Voice "AI Agent" account with API Access
* An n8n instance (cloud at [n8n.io](https://n8n.io) or self-hosted)
* An AI provider API key (e.g. OpenAI) if you want AI-generated replies
* About 10 minutes

# How it works under the hood

![Carbon Voice agent message flow](../../config/images/cv_agent_message_flow_v2.svg)

The purple boxes are your agent. Carbon Voice handles the rest.

---

# Self-Hosted: Native Node Setup

If you run n8n on your own server, you can install the official Carbon Voice community node for the simplest setup.

## Install the Community Node

**Option A — via the n8n UI (recommended)**

1. Open your n8n instance and go to **Settings → Community Nodes**
2. Click **Install**
3. Enter the package name: `@carbonvoice/n8n-nodes-carbonvoice`
4. Accept the risk acknowledgment and click **Install**
5. n8n will install the package and restart automatically

**Option B — via the command line**

If you manage n8n manually (e.g. with Docker or npm), install the package in your n8n data directory and restart:

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

Then restart your n8n instance.

## Create the Agent Account

1. Go to [https://developer.carbonvoice.app](https://developer.carbonvoice.app) and log in to your account
2. Click **"Agents"** on the left and then **"Create Agent"**
3. Name your agent (e.g. "Hal (n8n AI EA)")

## Create a Personal Access Token (PAT)

1. On the Agent Setup page, scroll to **"Personal access tokens"** and tap **"Create token"**
2. Name it "n8n" and hit **Create Token**

Save the token — **it cannot be retrieved again**. You'll use it to configure the node credentials.

## Set Up Carbon Voice Credentials in n8n

1. In n8n, go to **Settings → Credentials → New Credential**
2. Search for and select **"Carbon Voice API"**
3. Paste in your Personal Access Token
4. Save the credential

## Build Your Workflow

1. Create a new workflow in n8n
2. Click **"+"** and search for **"Carbon Voice"**
3. Select the **Carbon Voice Trigger** node — this replaces the Webhook node
4. Choose your saved credential and configure message filters as needed
5. Add downstream nodes to process the incoming message

The incoming payload has the same structure as the webhook approach. The `transcript_txt` field contains the transcribed text of what was said or typed.

To send a reply back to Carbon Voice, follow [Step 3: Sending Messages to Carbon Voice](#step-3-sending-messages-to-carbon-voice) below — it's the same for both setup methods.

---

# Webhook Setup

Use this method if you are on **cloud n8n** or prefer webhooks on a self-hosted instance.

---

# **Step 1** **Create the n8n Webhook Trigger**

#### **Create a New Workflow**

1. Go to your n8n instance and click **"Create Workflow"**
2. Name it something like "Carbon Voice Assistant"

#### **Add a Webhook Trigger Node**

1. Click **"+"** to add a node and search for **"Webhook"**
2. Select the **Webhook** trigger node
3. Set **HTTP Method** to `POST`
4. **Path** will have a unique GUID, you can leave that or change if you like
5. Set **Response Mode** to `Respond to Webhook` — select **"Immediately"**
6. Click **"Listen for Test Event"** to activate the test URL

Copy the **Webhook URL** shown — you'll need it in the next steps.

> **Tip:** n8n gives you two URLs: a test URL and a production URL. Use the test URL while building, then switch to the production URL when you activate the workflow.

---

# **Step 2** **Create the Agent Account**

### **Create Agent Account**

1. Go to [https://developer.carbonvoice.app](https://developer.carbonvoice.app) and Login to your account.
2. Click "Agents" on the left side and then click "Create Agent"
3. Name your agent (Something like "Hal (n8n AI EA)")

### **Register your Webhook**

1. On the Agent Setup, scroll down to the "Webhook subscription" section
2. Set the URL to the n8n webhook URL you copied in Step 1
3. Set it to filter messages as you like
4. Hit Subscribe

### **Now Test your Webhook**

1. In n8n select "Listen for test event"
2. Now go to Carbon Voice app, you should see a new message from the agent you just created
3. Send a quick message

Shortly after the message is sent, you should see a message arrive.

You'll notice what you typed or said is in the `transcript_txt` field, which you can then map into workflows.
You can pull this mapped data field into other workflow steps.

To learn more about creating workflows in n8n and creating AI Agents see this video: https://www.youtube.com/watch?v=GuaKeDS6UKU

# **Step 3** **Sending Messages to Carbon Voice**

### **Get Personal Access Token (PAT) for this Agent Account**

1. On the Agent Setup, scroll down to the "Personal access tokens" section and tap "Create token"
   1. Name it "n8n"
   2. Hit Create Token

You'll be given the token. **Make sure to save this, it can not be retrieved again.** You'll have to create a new one if you lose it.

You will use this if you want n8n to send replies back to the agent using the API.

### **Post the Reply to Carbon Voice**

Add an **HTTP Request** node to send the reply back:

- **Method**: `POST`
- **URL**: `https://api.carbonvoice.app/v3/messages/start`
- **Authentication**: Select **"Generic Credential Type"** and **"Bearer Auth"** set:
  - **Name**: `Authorization`
  - **Value**: `Bearer <your personal access token>`
- **Body** (JSON):
  ```json
  {
    "channel_id": "{{ $json.body.data.resource.channel_id }}",
    "is_text_message": true,
    "reply_to_message_id": "{{ $json.body.data.resource.parent_message_id || $json.body.data.resource.message_guid }}",
    "is_streaming": false,
    "transcript": "<Enter your message text here>"
  }
  ```

  Test this and you should receive a reply to your message.


### **Optional: Mark Messages as Read**

To mark the incoming message as read after processing:

- **Method**: `DELETE`
- **URL**: `https://api.carbonvoice.app/notifications/{{ $json.channel_guid }}/{{ $json.message_guid }}?type=message&notificationRemovalMode=hard`
- **Authentication**: Same as above

### **Store Credentials Securely in n8n**

Rather than hardcoding your token in nodes, use n8n's **Credentials** system:

1. Go to **Settings → Credentials → New Credential**
2. Choose **"Header Auth"**
3. Set name to `Carbon Voice Bot` and value to `Bearer <personal access token>`
4. Reference this credential in all HTTP Request nodes that call the Carbon Voice API

> **Note:** For API reference, see:
> - OpenAPI spec: https://api.carbonvoice.app/docs/ai-agent-json
> - How-to guides: https://api.carbonvoice.app/ai-docs/index.json


---

# Troubleshooting

| Problem | Solution |
| ----- | ----- |
| No reply received | Check that your webhook URL is correctly registered with Carbon Voice and that the n8n workflow is activated (not in test mode) |
| Agent replies to itself | Make sure you've configured your agent's webhook to ignore messages from itself. |
| Replies go to wrong channel | Confirm the HTTP Request node uses the `channel_guid` from the incoming webhook payload, not a hardcoded channel ID |
| Webhook not firing | Verify the webhook URL in Carbon Voice matches the production URL (not the test URL) and the workflow is activated |
| n8n execution errors | Open the **Executions** tab in n8n to inspect the full payload and identify which node failed |
| Carbon Voice node not appearing (self-hosted) | Restart n8n after installing the package; check the n8n logs for install errors |
| Community node install fails | Ensure your n8n instance has internet access and that you're running a version of n8n that supports community nodes (v0.187+) |