> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chatwoot integration

> Connect Voiceflow to Chatwoot so AI agents can manage support conversations, answer from Help Center articles and connect customers with your team.

## Overview

Voiceflow integrates with Chatwoot so your AI agents can look up contacts, create and manage support conversations, answer from Help Center articles and connect customers with your support team.

Connect data through **custom API tools**, index approved public Help Center articles in **Knowledge**, and use a **Custom Handoff relay** for human replies. These are separate paths; live handoff requires your own deployed relay. The downloadable handoff pilot provides a starting point for that service.

### Examples of when to use Chatwoot

- **[Recognize a customer](#finding-contacts)** — retrieve the contact your application has verified.
- **[Record a support request](#creating-conversations)** — create an inbox conversation with a private escalation summary.
- **[Route a case](#managing-conversations)** — assign the conversation, change its priority or resolve it.
- **[Brief a teammate](#adding-notes)** — add internal context without sending it to the customer.
- **[Import help articles](#help-center)** — retrieve approved public Help Center articles.
- **[Human agent hand-off](#live-agent)** — exchange text messages with a Chatwoot teammate through your relay.

#### Studio

Use an editable Voiceflow project and a Chatwoot account whose resources you can access. Before testing contact tools, have your developer map the signed-in customer to a verified Chatwoot contact ID and supply it to the session. API tools and Knowledge are configured in Agent studio; live support additionally needs a deployed relay.

#### Developer

Use Voiceflow's management API or CLI for tools and the Knowledge API for imports. Your backend supplies verified customer IDs, prepares write payloads and runs the optional relay. Keep Chatwoot tokens on the server.

<a id="connecting-chatwoot"></a>

## Connecting Chatwoot

Authorize requests to your Chatwoot account and prepare a reusable API tool.

In Chatwoot, open **Profile Settings** and copy your personal API access token. Replace `https://CHATWOOT_HOST` in request URLs with your workspace URL's origin (for example `https://app.chatwoot.com`), and take `ACCOUNT_ID` from `/app/accounts/ACCOUNT_ID/` in that URL. The Account/Application API uses the `api_access_token` header; its routes and credential differ from Chatwoot's public inbox API and Platform administration API.

On Chatwoot Cloud, the account must have **API and webhooks** enabled. Otherwise token-authenticated requests return `403` with `API access is not enabled for this account`.

The token acts as its user. Confirm membership in the account and access to the intended inbox; webhook registration requires an account administrator. Store the token in the restricted Secret `chatwoot_token`. Use a test project and test inbox for writes.

### Prepare and test a contact lookup

#### Studio

### 1. Store the credential

Open the project in [Agent studio](https://creator.voiceflow.com). In the left sidebar, open **More → Secrets** and create `chatwoot_token` with the Chatwoot token. Creating the default also sets Main's Published value, so use a test project. Set an override for your test Environment's Draft when it uses a different credential.

### 2. Create the API tool

Open **Agent → Global tools → + → API**, then create **Find Chatwoot contact**. Choose **GET** and set the URL to `https://CHATWOOT_HOST/api/v1/accounts/ACCOUNT_ID/contacts/{contact_id}`. Add the header `api_access_token` with input `{api_access_token}` and `Accept: application/json`.

### 3. Bind trusted inputs and test

First create `chatwoot_contact_id` in **More → Variables**, leaving its default empty. Have your developer pass `variables: {"chatwoot_contact_id":"VERIFIED_CHATWOOT_ID"}` with the authenticated backend's initial `launch` action; creating a session alone does not populate it. Obtain a verified test contact ID from them. Return to the tool, set the api_access_token input's default to the Secret `chatwoot_token`, and bind `contact_id` to that identity variable rather than asking the model to choose a customer. Test that contact ID, inspect the response and capture only the fields your support task needs.

Native Find Chatwoot contact API tool with a verified contact ID input — Bind the contact lookup to an identity verified by your application.

Before publishing a tested tool, select the target Environment and open `chatwoot_token` in **More → Secrets**. Set its **Default value** to the credential that Environment's published agent should use; **Draft value** alone does not supply it. Follow [Secret publication behavior](/docs/documentation/build/data/secrets#publishing-reverting-and-discarding-changes), then [publish the tested agent](/docs/documentation/deploy/environments/publishing).

#### Developer

Create a [personal or service key](/docs/api-reference/authentication) with access to the project and set it as `VF_TOKEN`. Set `PROJECT_ID` to that project's ID and `ENVIRONMENT` to the alias shown on its [Environments page](/docs/documentation/deploy/environments/overview). Use a test Environment. Set `CHATWOOT_TOKEN` to your personal Chatwoot API token and `CHATWOOT_CONTACT_ID` to a contact ID verified by your application. Use a current [Voiceflow CLI](/docs/cli/install) with API-tool and tool commands; it reads `VF_TOKEN`.

Save this definition as `chatwoot-tool.json`, replacing `CHATWOOT_HOST` and `ACCOUNT_ID`. Braced names declare API-tool inputs, not project Secrets:

```json
{
  "name":"Find Chatwoot contact",
  "description":"Retrieve the customer verified by the signed-in application.",
  "httpMethod":"get",
  "url":"https://CHATWOOT_HOST/api/v1/accounts/ACCOUNT_ID/contacts/{contact_id}",
  "headers":[
    {"key":"api_access_token","value":"{api_access_token}"},
    {"key":"Accept","value":"application/json"}
  ]
}
```

#### API

### 1. Create the Secret and identity variable

Creating this Secret sets its project default and Main's Published value. Use a test project, then set the intended Draft override:

```sh
jq -n --arg value "$CHATWOOT_TOKEN" \
  '{name:"chatwoot_token",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Save `secret.id` as `SECRET_ID`:

```sh
jq -n --arg value "$CHATWOOT_TOKEN" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' |
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"chatwoot_contact_id","color":"#515A63","defaultValue":""}'
```

Send `variables: {"chatwoot_contact_id":"VERIFIED_CHATWOOT_ID"}` from your backend with the initial `launch` [action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). The action applies these variables before the turn; session creation alone does not set them. Do not set a shared contact ID as the variable default.

### 2. Save the request and discover its input IDs

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @chatwoot-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`, then inspect the schema and input IDs:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$API_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Match each `variables[].name` to its `id`; keep those IDs for the attachment below.

### 3. Execute against a test customer

```sh
jq -n --arg id "$CHATWOOT_CONTACT_ID" \
  '{inputs:{api_access_token:"{chatwoot_token}",contact_id:$id}}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

#### CLI

### 1. Create the Secret and identity variable

```sh
jq -n --arg value "$CHATWOOT_TOKEN" \
  '{name:"chatwoot_token",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json
```

This writes the project default and Main's Published value. Save `secret.id` as `SECRET_ID`, then set the test Draft override:

```sh
jq -n --arg value "$CHATWOOT_TOKEN" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' |
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" --output-format json

vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name chatwoot_contact_id --color-param '#515A63' --default-value '' --output-format json
```

Send `variables: {"chatwoot_contact_id":"VERIFIED_CHATWOOT_ID"}` from your backend with the initial `launch` [action](/docs/api-reference/v4interact/interact-non-stream#streaming-action), which sets variables before processing the turn. Do not use a shared contact ID as the variable default.

### 2. Save the request and discover its input IDs

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < chatwoot-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`:

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool variable list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --api-tool-id "$API_TOOL_ID" --output-format json
```

Match `variables[].name` to `id` for the attachment below.

### 3. Execute against a test customer

```sh
jq -n --arg id "$CHATWOOT_CONTACT_ID" \
  '{inputs:{api_access_token:"{chatwoot_token}",contact_id:$id}}' |
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json
```

Check `success`, `error`, `truncated`, `output.status` and `output.body`. A successful lookup has HTTP 200 and the expected `output.body.payload.id`, `payload.name` and `payload.email`. A Voiceflow HTTP 200 alone is not provider success.

### Make the lookup available to the agent

#### Studio

Keep the lookup in **Global tools**, write a trigger for authenticated customer questions, and run a conversation with your application-provided contact ID. Confirm that the correct record was used. Publish the tested Environment after preparing its published Secret value.

#### Developer

Save this as `chatwoot-attachment.json`. Replace the tool ID and the input IDs using the returned `variables[]` values:

```json
{
  "type":"api",
  "apiToolID":"YOUR_VOICEFLOW_API_TOOL_ID",
  "target":{"global":true},
  "description":"Look up the signed-in customer before answering their account question.",
  "inputVariables":{
    "api_access_token":{"apiToolInputVariableID":"TOKEN_INPUT_ID","required":false,"defaultValue":"{chatwoot_token}"},
    "contact_id":{"apiToolInputVariableID":"CONTACT_ID_INPUT_ID","required":false,"defaultValue":"{chatwoot_contact_id}"}
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @chatwoot-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < chatwoot-attachment.json
```

Inspect `tool` and resolve `unresolvedReferences` before testing. Creating the request does not attach it. Test agent routing in Draft, [set the target Published Secret value](/docs/cli/commands/secret/set-value) with `versionVariant: "published"`, then [publish the tested agent](/docs/documentation/deploy/environments/publishing). Management and standalone execution use Draft; a named Environment's Draft override does not set its Published value.

### Repair authorization or replace a key

Check the provider response and update the credential slot that actually executes the request.

- **401:** verify the host and token. Update the selected Draft Secret, test a read, then update the Published value when ready. Revoke the previous token after switching consumers.
- **403:** if the error is `API access is not enabled for this account`, enable that account capability first. Otherwise verify account membership and permission for the inbox or operation. Retrying with the same token does not add access.
- **429:** wait for the provider's rate-limit window before retrying. Do not retry writes blindly after a lost response; inspect the conversation first.

<a id="finding-contacts"></a>

## Finding and updating contacts

Use a verified contact to retrieve support context and keep customer details current.

The [lookup configured above](#connecting-chatwoot) reads **GET** `/api/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID`. The record is in `payload`, including `payload.id`, `name`, `email`, `phone_number` and `identifier`. Chatwoot contact IDs differ from your application's user IDs.

### Establish the identity mapping

#### Studio

- Create `chatwoot_contact_id` in **More → Variables**, leaving its default empty. Your authenticated application must populate it for the session.
- In **Find Chatwoot contact**, bind `contact_id` to this variable. Test a known contact and an absent ID, then inspect the returned `payload`.
- Capture only the support fields the agent needs. A customer typing someone else's email is not proof they own that contact.

#### Developer

Resolve the authenticated user to a stored Chatwoot contact ID on your backend. If you need a lookup, **GET** `/api/v1/accounts/ACCOUNT_ID/contacts/search?q=QUERY&page=1` returns `payload[]` and `meta.has_more`. Search is a substring match across name, email, phone and identifier, not an identity check. Follow pages and verify the match against your own identity record.

To create a missing contact, **POST** `/api/v1/accounts/ACCOUNT_ID/contacts` with approved `name`, `email`, `phone_number` or `identifier` values. Save **`payload.contact.id`** from the create response. Subsequent GET and PUT responses use `payload.id`. Persist this mapping instead of creating a contact on every turn.

### Update confirmed contact details

Use **PUT** `/api/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID` with only the fields the customer has confirmed. This example changes the display name:

```json
{"name":"Ada Chen"}
```

#### Studio

Create a separate API tool with that method and a URL ending in `/contacts/{contact_id}`. Add `api_access_token: {api_access_token}`, `Content-Type: application/json` and a raw JSON body containing `{payload}`. Bind the token input to the `chatwoot_token` Secret and `contact_id` to the `chatwoot_contact_id` variable from [Connecting Chatwoot](#connecting-chatwoot).

In **More → Variables**, create `chatwoot_contact_update_payload` with an empty default. Have your developer JSON-serialize the customer-confirmed changes using the [literal-safe preparation rules](#create-and-test-the-conversation-tool), then supply that string in the next action's `variables` before this tool runs. Bind `payload` to `{chatwoot_contact_update_payload}`. For a Studio test, paste the developer's prepared string into the test input. Verify `payload.name` by reading the contact again. Keep identity fields and permission-sensitive attributes outside model control.

#### Developer

Copy `chatwoot-tool.json` from the [API/CLI setup](#connecting-chatwoot), keep `/contacts/{contact_id}`, change `httpMethod` to `"put"`, and add `body: {"type":"raw-input","contentType":"json","content":"{payload}"}` plus `Content-Type: application/json`. Prepare the confirmed fields using the [literal-safe encoder](#create-and-test-the-conversation-tool); pass that string as `inputs.payload` for standalone execution.

Create `chatwoot_contact_update_payload` with the earlier variable API or CLI command, changing `name` and leaving `defaultValue` empty. Supply its serialized value in the next action's `variables` before the agent uses it. Discover this new tool's input IDs and [attach it](#make-the-lookup-available-to-the-agent) with defaults `api_access_token: {chatwoot_token}`, `contact_id: {chatwoot_contact_id}` and `payload: {chatwoot_contact_update_payload}`, each `required: false`. Read the contact back after success and verify `payload.name`.

<a id="creating-conversations"></a>

## Creating conversations

Open a support case in the right inbox and preserve its conversation ID.

Use a Chatwoot **API inbox** when Voiceflow will relay customer messages. Incoming message creation through the Account API is supported for API inboxes; a token alone does not turn another channel into one.

### Prepare the contact and inbox

Create an API inbox in **Chatwoot → Settings → Inboxes → Add inbox → API**, and give the responding teammates access. Open that inbox's settings and take `inbox_id` from `/app/accounts/ACCOUNT_ID/settings/inboxes/INBOX_ID` in the URL. Associate the verified contact with it using **POST** `/api/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID/contact_inboxes` and `{"inbox_id":12}`. Save the returned **root `source_id`**; it identifies this contact-inbox relationship, not the contact or your user.

**Backend prerequisite:** your developer provisions this association for the authenticated customer and keeps it in a server-side mapping. For Studio setup, ask for the resulting **account ID, API inbox ID, verified contact ID and contact-inbox `source_id`** before testing the conversation tool or relay. Do not collect these IDs from the customer or substitute an email address for them. If the contact does not exist, the backend creates it through Chatwoot's Contacts API first.

The IDs must belong together. A conversation's returned `id` is the account-scoped **display ID** used by subsequent API routes and webhooks.

#### Studio

Use the developer-provided mapping in your test request below. Have the application supply the complete prepared payload for each signed-in customer; a shared default or manually entered production contact ID would send different customers into the same case.

#### Developer

Set `CHATWOOT_URL` to the instance origin, `CHATWOOT_ACCOUNT_ID` to the account and `CHATWOOT_INBOX_ID` to its API inbox. With the verified `CHATWOOT_CONTACT_ID` and token from connection setup, provision or retrieve the association:

```sh
jq -n --argjson inbox "$CHATWOOT_INBOX_ID" '{inbox_id:$inbox}' |
curl --fail-with-body --silent --show-error \
  "$CHATWOOT_URL/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/contacts/$CHATWOOT_CONTACT_ID/contact_inboxes" \
  -H "api_access_token: $CHATWOOT_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Save the root `source_id` with that account, inbox and contact. Use this trusted mapping when serializing each customer's conversation payload. The handoff pilot uses it as `CHATWOOT_SOURCE_ID` for its single test customer.

### Create and test the conversation tool

This illustrative payload opens a case and gives teammates a **private note**. Replace the IDs and source ID using the mapping above. It does not yet connect live replies to Voiceflow.

```json
{
  "source_id":"CONTACT_INBOX_SOURCE_ID",
  "contact_id":3924,
  "inbox_id":12,
  "status":"open",
  "message":{
    "content":"Delivery investigation · order 2086",
    "message_type":"outgoing",
    "private":true
  }
}
```

#### Studio

### 1. Add the request

Open **Agent → Global tools → + → API** and create **Create Chatwoot conversation**. Choose **POST** `https://CHATWOOT_HOST/api/v1/accounts/ACCOUNT_ID/conversations`. Add `api_access_token` bound to `chatwoot_token` and `Content-Type: application/json`. Use the raw JSON body input `{payload}`.

Native Create Chatwoot conversation API tool with a prepared payload input — Prepare the conversation for a verified contact and inbox.

### 2. Bind the confirmed request

Create `chatwoot_conversation_payload` in **More → Variables**, leaving its default empty. Your backend builds its JSON from verified contact/inbox IDs and the customer-confirmed issue, then supplies the resulting string in an action's `variables` before creation runs. Bind the tool's `payload` default to that variable; do not ask the model to construct identity or authorization fields. Make literal-safe serialization part of the backend preparation: JSON-serialize the request, then encode `{` and `}` inside JSON strings as `\u007b` and `\u007d`, leaving object braces unchanged. Ask the developer to verify that quotes, newlines and text such as `{customer_name}` arrive unchanged after JSON decoding. Paste the returned prepared payload when testing in Studio; do not insert free text into quoted JSON by hand.

### 3. Confirm the result

Run once in a test inbox. Inspect the root `id`, `inbox_id`, `status` and `meta.sender.id`, then open the conversation in Chatwoot. Confirm the summary is a private note and retain the conversation ID for subsequent updates.

#### Developer

Save the payload above as `chatwoot-conversation-payload.json`, replacing the illustrative IDs on your backend. Save `chatwoot-conversation-tool.json` with your host and account ID:

```json
{
  "name":"Create Chatwoot conversation",
  "description":"Open one support case for the confirmed customer request.",
  "httpMethod":"post",
  "url":"https://CHATWOOT_HOST/api/v1/accounts/ACCOUNT_ID/conversations",
  "headers":[
    {"key":"api_access_token","value":"{api_access_token}"},
    {"key":"Content-Type","value":"application/json"}
  ],
  "body":{"type":"raw-input","contentType":"json","content":"{payload}"}
}
```

Serialize dynamic strings before execution. The standalone binder can interpret `{name}` or Secret-shaped text inside serialized input; this encoder escapes braces **inside JSON strings**, leaving object braces intact. Chatwoot receives the original text after JSON decoding:

```sh
python3 - <<'PYTHON'
import json, pathlib, re
p = pathlib.Path("chatwoot-conversation-payload.json")
original = json.loads(p.read_text())
serialized = json.dumps(original, ensure_ascii=True)
serialized = re.sub(r'"(?:\\.|[^"\\])*"',
    lambda m: m[0].replace("{", r"\u007b").replace("}", r"\u007d"), serialized)
assert json.loads(serialized) == original
p.write_text(serialized)
PYTHON

jq -n --rawfile payload chatwoot-conversation-payload.json \
  '{inputs:{api_access_token:"{chatwoot_token}",payload:$payload}}' > chatwoot-conversation-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @chatwoot-conversation-tool.json
```

Save `apiTool.id` as `CONVERSATION_TOOL_ID`:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$CONVERSATION_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @chatwoot-conversation-inputs.json
```

#### CLI

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < chatwoot-conversation-tool.json
```

Save `apiTool.id` as `CONVERSATION_TOOL_ID`:

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$CONVERSATION_TOOL_ID" --output-format json < chatwoot-conversation-inputs.json
```

Require `success: true`, a successful `output.status` and a root `output.body.id`. Verify `output.body.inbox_id` and `meta.sender.id` before storing the conversation mapping. Inspect `error` and `truncated` too; a management HTTP 200 is not proof of provider success.

For agent use, create `chatwoot_conversation_payload` with the [variable pattern](#connecting-chatwoot), leaving its default empty. Send its serialized confirmed request in the next action's `variables` before this tool runs, then [attach the tool](#make-the-lookup-available-to-the-agent). Discover this tool's input IDs and bind `api_access_token` to `{chatwoot_token}` and `payload` to `{chatwoot_conversation_payload}`, both `required: false`. Test routing and the prepared data before publishing.

### Supply verified case IDs

Before enabling case reads, routing or notes, have your backend developer map the signed-in customer's support request to a Chatwoot conversation display ID. Store the root `id` returned by conversation creation with its account, inbox and verified contact. For an existing case, GET it and check `meta.sender.id` against that contact before using it. Do not accept an arbitrary case ID from the customer or model.

#### Studio

Create `chatwoot_conversation_id` in **More → Variables** with an empty default. Have the developer supply the verified display ID in the customer's next action `variables` before a case tool runs. Obtain a disposable case ID for Studio tests and check that its contact and inbox match the intended customer. This mapping is application setup, not something the token connection creates.

#### Developer

Create `chatwoot_conversation_id` using the [variable API/CLI command](#connecting-chatwoot), changing its name and leaving the default empty. Populate it from the backend's verified case record in the next action's `variables`. When your backend creates the case through standalone tool execution, persist `output.body.id` before sending it to the session; for an agent-created case, verify its ownership through the provider before later operations. Test a different customer's case and reject it before tool execution.

### Prevent duplicate conversations

Reuse the stored case and reconcile uncertain create responses before retrying.

Store the returned conversation ID with your own stable support-request ID. Do not assume POST is idempotent: a lost response can leave a case open. Inspect the contact's conversations before retrying. An inbox configured to lock a contact to one conversation can reuse that conversation instead of creating a new one; verify its returned status and identity. The [Chatwoot Conversation API](https://developers.chatwoot.com/api-reference/conversations/create-new-conversation) describes the provider operation.

<a id="managing-conversations"></a>

## Reading and routing conversations

Review a customer's case, assign support and update its priority or status.

Read **GET** `/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID` using the stored display ID. Confirm `meta.sender.id` matches the verified contact before returning its `status`, `priority`, `meta.assignee` or `meta.team`.

### Read the message history

**GET** `/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/messages` returns `payload[]` with the latest 20 messages. Use `before=MESSAGE_ID` for older pages or `after=MESSAGE_ID` for up to 100 later messages. The conversation response's `messages[]` seeds only its latest message; it is not the full history. API message types are numeric (`0` incoming, `1` outgoing, `2` activity), while webhook message types are strings.

#### Studio

First complete [the case-ID handoff](#supply-verified-case-ids). Add a **GET** API tool for each read, replacing `CONVERSATION_ID` in its URL with `{conversation_id}`. Reuse `api_access_token: {api_access_token}`, bind that input to the `chatwoot_token` Secret and bind `conversation_id` to `{chatwoot_conversation_id}`. Map only customer-visible fields into the response. Private notes and activity messages must not be returned as customer replies.

#### Developer

Complete [the case-ID handoff](#supply-verified-case-ids), then copy the [lookup definition and API/CLI sequence](#connecting-chatwoot). Change its URL to the desired conversation route, using `{conversation_id}` in place of `CONVERSATION_ID`. Execute with the verified display ID in `inputs.conversation_id`. Discover this tool's input IDs and attach it with `api_access_token: {chatwoot_token}` and `conversation_id: {chatwoot_conversation_id}`, both `required: false`; do not reuse the contact tool's input IDs. Fetch further message pages on the backend when building a history and filter private/activity messages before returning it to the customer.

### Assign and update the case

All routes below start with `/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID`. These are distinct requests; use the case ID stored for this customer.

- **Assign a team:** POST `/assignments` with `{"team_id":4}`.
- **Assign a teammate:** POST `/assignments` with `{"assignee_id":9}`. If both assignments are needed, send the team request first and the teammate request second; combining both fields selects the assignee branch and does not apply the team change.
- **Change priority:** PATCH the conversation URL with `{"priority":"high"}`. Supported values are `low`, `medium`, `high`, `urgent`, or `null` to clear it.
- **Resolve or reopen:** POST `/toggle_status` with `{"status":"resolved"}` or `{"status":"open"}`. Always pass an explicit status; do not rely on toggling the current value.

#### Studio

### 1. Configure the permitted change

Create a separate API tool for each permitted change. Use the shown method and path, with `{conversation_id}` bound to `{chatwoot_conversation_id}` from [case setup](#supply-verified-case-ids). Reuse the token Secret and set `Content-Type: application/json`. The shown JSON bodies are fixed values; obtain permitted team/user IDs from your Chatwoot administrator before replacing the illustrative IDs. Confirm before resolving an active customer request.

### 2. Verify the updated case

Test against a disposable case, then GET it again to verify the assigned team/user, priority or status. Do not treat an assignment response as the full conversation.

#### Developer

Use the [API/CLI create, execute and attach sequence](#connecting-chatwoot) with `httpMethod: "post"` or `"patch"` and the appropriate conversation URL containing `{conversation_id}`. Set the raw JSON body's `content` to the shown fixed JSON, with `Content-Type: application/json`; these fixed examples do not need a `payload` variable. Replace the illustrative team/user IDs with IDs supplied by your Chatwoot administrator. Resolve this tool's input IDs and bind the token and case as in the read tool above. Keep allowed targets server-controlled. Read the conversation back after a write; assignments return their own resource rather than a full conversation.

<a id="adding-notes"></a>

## Adding internal notes

Share the customer's issue and completed checks with support teammates.

POST `/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/messages` with an outgoing **private** message. Leaving out `private: true` makes an outgoing message public.

### Add and verify the note

```json
{"content":"Order 2086: customer confirmed the delivery address. Carrier investigation requested.","message_type":"outgoing","private":true}
```

#### Studio

Create **Add Chatwoot note** in **Agent → Global tools → + → API**. Choose **POST**, use the message URL with `{conversation_id}`, add `Content-Type: application/json` and use a raw JSON `{payload}` body. Bind the token to the `chatwoot_token` Secret and `conversation_id` to `{chatwoot_conversation_id}` from [case setup](#supply-verified-case-ids).

Create `chatwoot_note_payload` in **More → Variables** with an empty default. Have your developer serialize the confirmed note with `private: true` using the [literal-safe preparation rules](#create-and-test-the-conversation-tool), and supply that string in the next action's `variables`. Bind `payload` to `{chatwoot_note_payload}`. Use the developer's prepared string in a Studio test; inspect the returned message `id` and `private`, then check that it appears as an internal note in Chatwoot.

#### Developer

Use the [write-tool definition and encoder](#create-and-test-the-conversation-tool), changing the URL to `/conversations/{conversation_id}/messages`. Add the verified case ID to standalone `inputs` alongside the token and encoded `payload`. Create `chatwoot_note_payload` with the [variable API/CLI pattern](#connecting-chatwoot), leaving the default empty; your backend supplies its serialized value in the next action before the note tool runs. Attach using this tool's own input IDs and defaults `api_access_token: {chatwoot_token}`, `conversation_id: {chatwoot_conversation_id}` and `payload: {chatwoot_note_payload}`, each `required: false`.

Verify the root message `id` and `private: true`. The REST response uses numeric `message_type: 1` for outgoing. A private note must never be forwarded by your relay as `message.received`.

<a id="help-center"></a>

## Import help articles

Answer from approved public Chatwoot Help Center articles in Knowledge.

Import approved public article URLs with Voiceflow's Web page importer. This indexes article content for Knowledge; it does not authorize conversation tools or create a managed Chatwoot account sync.

### Import and test a public article

#### Studio

### 1. Choose and import the article

Open its public URL in a signed-out browser and check the answer. In your Voiceflow project, open **Knowledge base → Add data source → Web page(s)** and paste the URL. Confirm the selection and import.

Native Web page importer with an approved public Help Center article URL — Import approved public Help Center articles into Knowledge.

### 2. Verify retrieval

Wait for processing to finish and inspect the imported content. Enable Knowledge on the agent, use **Run** to ask a question answered by that article and inspect the retrieved source. A URL in the list alone is not evidence that the agent used it.

#### Developer

Obtain the target project's project API key from its administrator (**Settings → API keys**) and set it as the server-side `VF_PROJECT_API_KEY`. This Knowledge route derives the project from that key; the management bearer token is not interchangeable. Set `ENVIRONMENT` to the target alias from the project's [Environments page](/docs/documentation/deploy/environments/overview). Replace the illustrative URL with a public article that opens in a signed-out browser:

```sh
jq -n --arg env "$ENVIRONMENT" \
  '{data:{type:"url",url:"https://support.northstar.example/hc/northstar/articles/shipping",refreshRate:"never",projectEnvironmentIDOrAlias:$env}}' |
curl --fail-with-body --silent --show-error \
  'https://realtime-api.voiceflow.com/v1alpha1/public/knowledge-base/document' \
  -H "Authorization: $VF_PROJECT_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

Save `data.documentID` as `DOCUMENT_ID`, then poll with the same project key and Environment:

```sh
curl --fail-with-body --silent --show-error --get \
  "https://realtime-api.voiceflow.com/v1alpha1/public/knowledge-base/document/$DOCUMENT_ID" \
  --data-urlencode "projectEnvironmentIDOrAlias=$ENVIRONMENT" \
  -H "Authorization: $VF_PROJECT_API_KEY"
```

Stop when `data.status` becomes `SUCCESS` or `ERROR`. Inspect the content and test actual agent retrieval in that Environment after success. An error is not a completed import; inspect and correct the source before retrying.

### Keep imported articles current

Maintain the indexed documents separately from contact and conversation access.

Public URL imports support `daily`, `weekly`, `monthly` or `never` refresh. Choose the schedule that matches how often the policy changes. Remove obsolete documents and verify a new agent answer against the updated source. In Code, replace a document with **PUT** `/v1alpha1/public/knowledge-base/document/{documentID}`, using the same `data` body as creation and the selected `projectEnvironmentIDOrAlias`. Poll that ID until `SUCCESS` or `ERROR`. Delete obsolete content with **DELETE** on the same document URL and `projectEnvironmentIDOrAlias` query, using the project API key. The [Knowledge document reference](/docs/api-reference/kbpublicapidocument/create-document) describes the full lifecycle. For private articles, build an authorized export and upload approved content; do not expose it publicly just to use a URL importer.

<a id="live-agent"></a>

## Human agent hand-off

Keep the customer in Voiceflow while your team replies from a Chatwoot inbox.

Use the downloadable **text-only Chatwoot pilot** in the [Custom Handoff starter](/docs/developers/handoff/connect). It creates a Chatwoot conversation, forwards incoming customer text, accepts signed public teammate replies and resolves the mapped conversation.

The pilot fixes **one test contact and API inbox**, and keeps mappings and duplicate IDs in memory. Before serving multiple customers, implement verified per-customer contact mapping, durable storage and a queued callback outbox. Restarting the pilot loses its mappings. File transfer and queue routing are not implemented; keep files disabled and use the configured test inbox.

### Prepare Chatwoot and deploy the pilot

#### Studio

### 1. Arrange the test inbox and relay

Have your developer deploy the [Chatwoot Custom Handoff starter](/docs/developers/handoff/connect#build-and-connect-the-service) for one dedicated contact and API inbox. Give them the target Voiceflow project ID and the Chatwoot administrator who can prepare the [contact-inbox mapping](#prepare-the-contact-and-inbox). The administrator must confirm that a teammate can reply in that test inbox.

### 2. Obtain the connection values

Before opening Voiceflow's connection form, obtain the relay's HTTPS **Base URL**, its **Authorization** header value (`Bearer …`), the separate Voiceflow callback **Webhook secret** of at least 32 characters, and the dedicated test contact ID. Have the developer confirm the relay is running for your project, the contact/inbox association exists, and one Chatwoot account webhook subscribes to both `message_created` and `conversation_status_changed` with its signing secret configured on the relay. The Chatwoot webhook signing secret stays on the relay; it is not the Voiceflow Webhook secret.

#### Developer

### 1. Prepare the API inbox and contact

Complete the [contact-inbox mapping](#prepare-the-contact-and-inbox). In Chatwoot, create a manual test conversation in that API inbox and verify that an assigned teammate can reply. Use a dedicated test contact, not a shared production customer.

### 2. Download and configure the service

Download all four files into one folder: [server.mjs](/docs/examples/live-agent-handoff/server.mjs), [protocol.mjs](/docs/examples/live-agent-handoff/protocol.mjs), [chatwoot.mjs](/docs/examples/live-agent-handoff/chatwoot.mjs) and [test.mjs](/docs/examples/live-agent-handoff/test.mjs). Use Node.js 22 or later.

Set these environment variables on the server:

- `PROVIDER=chatwoot`, `CHATWOOT_URL` (instance origin), `CHATWOOT_ACCOUNT_ID` and `CHATWOOT_TOKEN`.
- `CHATWOOT_INBOX_ID`, `CHATWOOT_CONTACT_ID` and `CHATWOOT_SOURCE_ID` from the same contact-inbox mapping.
- `HANDOFF_TOKEN` for Voiceflow's requests to your relay, and a separate `EVENT_TOKEN` for the starter's normalized `/events` endpoint.
- `WEBHOOK_SECRET`, a random secret of at least 32 characters for callbacks **to Voiceflow**; `VOICEFLOW_PROJECT_ID` for the one allowed project; and `VOICEFLOW_WEBHOOK_URL` set to `https://general-runtime.voiceflow.com/handoff/webhook/custom`.

Run `node --test test.mjs`, then `node server.mjs` (port 8787 by default). Expose it through an HTTPS reverse proxy. Keep tokens outside source control. Local tests use mock requests; they do not create or verify a real Chatwoot conversation.

### 3. Register the signed provider webhook

An account administrator registers **one account webhook** for `message_created` and `conversation_status_changed`, pointing to `https://YOUR_RELAY/provider-events`. Its own Chatwoot-generated secret must be set as `CHATWOOT_WEBHOOK_SECRET` in the relay, separately from `WEBHOOK_SECRET` above.

Use Chatwoot's **Settings → Integrations → Webhooks**, or create the account webhook through its API. Set `CHATWOOT_URL`, `CHATWOOT_ACCOUNT_ID`, `CHATWOOT_TOKEN` and `RELAY_URL` in your admin shell:

```sh
jq -n --arg url "$RELAY_URL/provider-events" \
  '{webhook:{name:"Voiceflow support relay",url:$url,subscriptions:["message_created","conversation_status_changed"]}}' |
curl --fail-with-body --silent --show-error \
  "$CHATWOOT_URL/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/webhooks" \
  -H "api_access_token: $CHATWOOT_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Read **`payload.webhook.secret`** from the response and configure the relay's `CHATWOOT_WEBHOOK_SECRET`, then restart it. Do not paste this secret into public logs. Leave the API inbox's own webhook URL blank when using the account webhook: that second delivery path has a different secret and would duplicate notifications. See [Chatwoot webhooks](https://app.chatwoot.com/hc/user-guide/articles/1677693021-how-to-use-webhooks).

Keep the deployed HTTPS origin as `RELAY_URL`. For Studio configuration, hand over that Base URL, `Authorization: Bearer HANDOFF_TOKEN`, the separate Voiceflow `WEBHOOK_SECRET` and the dedicated test contact ID through your team's secret-sharing process. Confirm the service and signed provider receiver are configured before connecting Voiceflow. Two-way acceptance happens after the Workflow and customer client are ready below.

### Connect and route the handoff

#### Studio

### 1. Connect the deployed service

Open your project in **Agent studio → More → Integrations**. Find **Custom Handoff** and select **Connect**. Enter the developer-provided HTTPS **Base URL**, **Auth header name** `Authorization`, **Auth header value** `Bearer YOUR_HANDOFF_TOKEN`, and the separate Voiceflow **Webhook secret** from the handoff above. This form connects your service, not Chatwoot directly.

Native Custom Handoff connection form in project Integrations — Connect the deployed Chatwoot relay through Custom Handoff.

### 2. Configure a support Workflow

Create a **Workflow**, add a **Handoff** step and select **Custom Handoff**. For this single-contact pilot, set **End user ID** to the dedicated test contact ID provided by your developer. Select **Full transcript** under **Handoff context** so the relay can prepare private staff context without an undeclared summary variable. Keep files disabled and enable **Return** and **Fail** paths. The pilot uses its configured inbox; changing the editor's queue does not route it to a different team.

Native Handoff editor with Custom Handoff selected — Route the support Workflow through your Chatwoot relay.

### 3. Attach and test the Workflow

Add the Workflow to the agent and describe when to call it, such as a customer asking for a person. Publish to a test Environment and connect the customer chat to that Environment. Complete the conversation checks below with a teammate.

#### Developer

Use the [management credential and project ID from setup](#connecting-chatwoot). Save `chatwoot-handoff.json` with your deployed HTTPS origin, `HANDOFF_TOKEN` and the same `WEBHOOK_SECRET` used by the relay for Voiceflow callbacks. The Chatwoot token and Chatwoot-generated signing secret stay on the relay:

```json
{
  "integration":"custom_handoff",
  "credentials":{
    "baseUrl":"https://YOUR_RELAY",
    "authHeaderName":"Authorization",
    "authHeaderValue":"Bearer YOUR_HANDOFF_TOKEN",
    "webhookSecret":"REPLACE_WITH_YOUR_WEBHOOK_SECRET_AT_LEAST_32_CHARACTERS"
  }
}
```

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/integration/custom_handoff?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @chatwoot-handoff.json
```

A 200 confirms stored project default-slot configuration, not message delivery. Follow the [headless Workflow creation, attachment and publication sequence](/docs/developers/handoff/connect#configure-voiceflow-through-the-api) with provider `custom` and Return/Fail paths. Preserve existing agent registrations when attaching it. Implement the [Chat handoff traces and human-message contract](/docs/api-reference/agent-runtime/chat/handoff) in the customer client and test its published Environment.

### Verify the complete conversation

1. Escalate once from the test customer. Confirm one conversation in the intended Chatwoot API inbox and the correct contact. Its escalation summary must be a private note.
2. Send customer text from Voiceflow and a public teammate reply from Chatwoot. Confirm each arrives once in the other interface.
3. Add a private note and replay a signed provider event. Neither should produce an extra customer-visible reply. Reject invalid signatures and unmapped conversations.
4. Resolve in Chatwoot and verify the Return path. Separately end from Voiceflow and confirm the same case resolves once; a reflected closure must not resume the agent twice.
5. Stop the relay and verify the Fail path for a new handoff. Check provider deliveries and the signed Voiceflow callback response if a reply is missing.

### Harden the relay before serving customers

Persist identity and delivery state and reconcile gaps in provider notifications.

- **Creation and privacy:** the pilot posts to `/conversations` with its verified test mapping and `status: "open"`. The initial `outgoing`, `private: true` message is staff context; it must not be sent as a public reply. Store the returned display ID before acknowledging creation.
- **Customer messages:** POST `/conversations/ID/messages` with `message_type: "incoming"`, `private: false` and the customer's text. Deduplicate the Voiceflow message ID before writing. Keep uploads disabled until you implement both directions.
- **Human messages:** verify `X-Chatwoot-Timestamp` within five minutes and `X-Chatwoot-Signature` against the raw body. Chatwoot signs `TIMESTAMP + "." + RAW_BODY` with HMAC-SHA256 and a `sha256=` hexadecimal prefix. Filter by account and mapped conversation; accept only `message_created`, `message_type: "outgoing"`, non-private, non-empty messages whose `sender.type` is `user`. Exclude AgentBot and Captain assistant messages, missing or unknown sender types, incoming echoes and activity. Deduplicate by the stable message ID, not delivery ID alone.
- **Closure:** POST `/conversations/ID/toggle_status` with explicit `status: "resolved"`. A signed `conversation_status_changed` notification with root `status: "resolved"` becomes one `conversation.ended` callback. Persist the terminal state so your own close cannot loop.
- **Delivery:** account webhooks have a default five-second timeout (configurable when self-hosted), without a guaranteed retry. Authenticate and queue promptly, then reconcile missed messages using the provider's message history. This is separate from Chatwoot's AgentBot retry behavior. Sign callbacks with the separate Voiceflow webhook secret and inspect their response.

Use the [shared service durability checks](/docs/developers/handoff/connect#build-and-connect-the-service) for persistent mappings, an outbox and restart recovery. Verify signed delivery on your deployed Chatwoot version before accepting customer traffic.
