> ## 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.

# Kustomer integration

> Connect Voiceflow to Kustomer with built-in customer and conversation tools, help-article imports and human agent hand-off.

## Overview

Voiceflow integrates with Kustomer so your AI agents can work with customer records and support conversations, answer from approved help articles, and bring in a human teammate. Connect Kustomer in the app, then add the actions your agent needs.

- **[Recognize a customer](#customers)** and use their authorized support history.
- **[Record a support request](#creating-conversations)** with the confirmed issue and the right assignee.
- **[Import help articles](#help-articles)** to ground answers in your support content.
- **[Human agent hand-off](#human-agent-hand-off)** to continue a live Chat conversation with your team.

**Note:** 
**Helping your support teammates?** Follow [Kustomer agent assist](/docs/guides/channels/agent-assist/kustomer) to install a staff assistant in the Kustomer workspace. This manual covers the integration's actions, Knowledge and customer hand-off.

Agent studio with Kustomer actions attached to the Northstar support agent — Add the Kustomer actions your support agent needs.

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

## Connecting Kustomer

Authorize the account and prepare its built-in actions.

### Prepare the connection

A Kustomer administrator supplies the **org slug** and a server API key from **Settings → Security → API Keys**. For `northstar.kustomerapp.com`, the slug is `northstar`.

Grant only the [Kustomer roles](https://developer.kustomer.com/docs/get-started/api-keys-and-roles) needed for your workflow:

| Job | Key roles |
| --- | --- |
| Read customer or conversation records | `org.permission.customer.read`, `org.permission.conversation.read`. |
| Read the latest message | `org.permission.message.read`. |
| Create a customer or conversation | `org.permission.customer.create`, `org.permission.conversation.create`, respectively. |
| Update a customer or conversation | `org.permission.customer.update`, `org.permission.conversation.update`, respectively. |
| Add internal notes | `org.permission.note.create`. |
| Add conversation tags | `org.permission.conversation.update`. |
| Read teams or update companies | `org.permission.team.read`, `org.permission.company.update`, respectively. |
| Discover custom attributes | `org.permission.metadata.read`. |
| Import help articles | `org.permission.kb.read`. |
| Human hand-off | Customer read/create, conversation create/update and message create. Add note create or attachment permissions when using those features; the callback worker separately needs conversation/message read. |

Check the exact operation's Authorization block in [Kustomer's API reference](https://developer.kustomer.com/api/core-resources). Finding a record does not authorize every update to it. Keep the key on the server; never ask the customer or the agent model to provide it.

#### Studio

### 1. Open Kustomer in Integrations

Open your project in [Agent studio](https://creator.voiceflow.com). In the left sidebar, expand **More**, select **Integrations**, then choose **Connect** on **Kustomer**.

Integrations navigation and the Kustomer connection card — Open More → Integrations and select Kustomer.

### 2. Save the account credentials

Enter **Org name** and **API key**, then select **Connect**. **Webhook signing secret (optional)** is needed for [human hand-off](#human-agent-hand-off); tools and article imports do not require it.

Connect **Published** first. If the connection offers a **Draft** override, use it for sandbox actions. Without an override, Draft runs use Published credentials. Changing the Environment does not by itself change the Kustomer account. Article imports use the Published connection.

Kustomer connection dialog with Org name, API key and optional Webhook signing secret — Store the org slug and API key; add the callback secret for hand-off.

### 3. Attach the first action

Return to **Agent**, select **+** beside **Global tools**, and choose **Kustomer → Find customer**. In the editor, set **Trigger** to explain when to look up the verified customer. Review its inputs and create a text variable `kustomer_customer_id` in **More → Variables** with an empty default. In **Capture response**, map `customer.id` into it after a successful lookup. Use that variable for a later customer action.

For a Playbook-specific action, add it to that Playbook's tools instead. A connected account alone does not attach tools.

### 4. Check the customer lookup

Use a sandbox customer and run the action with an email you can inspect. Check the current result's `customer.id` and the matching record in Kustomer. Then test a conversation that invokes the action; the agent should use that returned record, and offer your support fallback when lookup fails.

#### Code

Use a server-side [Voiceflow API credential](/docs/api-reference/authentication), cURL and jq. Set `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT` in your shell; examples use `ENVIRONMENT=main`. For CLI calls, configure the same credential using the [CLI authentication guide](/docs/cli/authentication).

Save the following outside source control as `kustomer-connection.json`, with your actual slug and key:

```json title="kustomer-connection.json"
{
  "integration": "kustomer",
  "credentials": {
    "orgName": "YOUR_ORG_SLUG",
    "apiKey": "YOUR_KUSTOMER_API_KEY"
  }
}
```

This operation replaces the project's **Published** connection. It has no Environment or Draft-slot selector. Use a separate test project for isolation; connecting through the API is credential storage, not a successful provider test.

#### API

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/integration/kustomer?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @kustomer-connection.json
```

#### CLI

```bash
vf --output-format json integration connect --integration kustomer \
  --project-id "$PROJECT_ID" < kustomer-connection.json
```

Expect `Integration kustomer connected.` Then read the catalog and test an action using the workflow below. The catalog's `connected` flag reports stored credentials, not whether Kustomer accepts them. Standalone execution uses the selected Environment's Draft, with its Draft connection override when present and Published otherwise.

#### Execute an action

<a id="execute-actions" />

Save a request from the relevant section as `request.json`. Each request has a catalog `toolName` and typed `inputs`.

#### API

```bash title="Read the action schemas"
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/integration/kustomer/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" > kustomer-schema.json
```

```bash title="Run request.json once"
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/integration/kustomer/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json > result.json
```

#### CLI

```bash title="Read the action schemas"
vf --output-format json integration get-schema --integration kustomer \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" > kustomer-schema.json
```

```bash title="Run request.json once"
vf --output-format json integration execute --integration kustomer \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  < request.json > result.json
```

Check `success`, `error`, `output` and `truncated`, not just HTTP status. For example, a successful customer lookup returns the record at `output.customer`. Stop on failure or truncation; never treat a retained ID from an earlier call as current success. A timeout after a write leaves its outcome uncertain: inspect Kustomer before retrying.

#### Let the agent use the action

### 1. Add the catalog action

Read `tools[].toolName`, `inputs` and `integrationToolID` in `kustomer-schema.json`. If Find customer's ID is null, add it once:

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/integration/kustomer/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"toolName":"kustomer_find_customer"}' > kustomer-added.json
```

The CLI equivalent is `vf integration add-tool --integration kustomer --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --tool-name kustomer_find_customer`. Keep its `integrationToolID`; this operation does not attach it.

### 2. Create the attachment

Save this as `kustomer-tool.json`, replacing `YOUR_INTEGRATION_TOOL_ID`. This sandbox example lets the model collect an email; production customer-history access needs the [identity check](#customer-access) below.

```json title="kustomer-tool.json"
{
  "type": "integration",
  "integrationToolID": "YOUR_INTEGRATION_TOOL_ID",
  "target": { "global": true },
  "description": "Find the sandbox customer when asked about their support profile. Use only the current successful result; on failure offer support.",
  "inputVariables": {
    "email": {
      "integrationToolVariableName": "email",
      "description": "The sandbox customer's email address.",
      "required": true,
      "defaultValue": null
    }
  }
}
```

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

Or use `vf --output-format json tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" < kustomer-tool.json`. For a Playbook, replace `target` with `{"playbookID":"YOUR_PLAYBOOK_ID"}`. Review existing attachments before repeating creation.

### 3. Compile and test a conversation

```bash
curl --fail-with-body --silent --show-error --request PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Or use `vf environment compile --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT"`. Compilation prepares Draft; it does not publish. Run a [Draft conversation](/docs/cli/commands/conversation/send), ask about the test customer's profile, and verify the action inputs and returned record inform the reply. Repeat with an unknown email and confirm no earlier customer's data appears.

### Replace or disconnect the connection

Coordinate key rotation with Draft overrides, article refresh and active hand-offs.

In **More → Integrations → Kustomer**, manage the intended Published or Draft connection. Removing Published also removes its Draft override. Reconnect with the new key, then test a read and each required write before retiring the old key.

For Code, repeat the connect operation to replace Published. `DELETE /v1/stable/integration/kustomer?projectID=…`, or `vf integration disconnect --integration kustomer --project-id "$PROJECT_ID"`, clears the stored Published and Draft slots. The stable deletion path clears credentials; the Studio/provider disconnect also stops Kustomer article refresh jobs. Before API deletion, set affected imports to **Never** in Knowledge and verify that scheduled refresh is stopped.

Replacing credentials does not update active hand-offs' stored credentials. Finish those sessions before changing the callback secret. A same-org reconnect with an empty signing-secret field preserves the stored secret; supply a new value to rotate it.

### An action cannot access Kustomer

Check the account, operation permissions and connection slot.

Check the org slug, key expiry and the exact operation's roles. An accepted connection or populated catalog does not prove provider permission. Test a permitted read against a known record in the intended account. If Draft uses the wrong account, inspect its override and Published fallback. Fix credentials or access before repeating a failed write.

<a id="customers"></a>

## Finding and updating customers

Match a verified customer and keep their permitted profile details current.

<a id="customer-access" />

Before returning a profile or support history, your application must authenticate the person and authorize the Kustomer record. An email match is a lookup, not identity verification. For production, the application developer creates `verified_customer_email` in **More → Variables** with an empty default, authenticates the customer, and supplies that email in the [Chat action variables](/docs/api-reference/v4interact/interact-non-stream) before the lookup runs. Obtain that variable mapping and an allowed/denied test account from the developer. Verify it through the actual signed-in application; Studio Run does not automatically receive backend identity. Instructions and Trigger text do not enforce the access policy.

| Action | Inputs | Current result |
| --- | --- | --- |
| Find customer | At least one of `email`, E.164 `phone`, `externalID`. | `customer`; a missing match is an error. |
| Create customer | At least one of `email`, `phone`, `externalID`; optional `name`, `locale`, `custom`. | Newly created `customer`. |
| Update customer | `customerID`; optional `name`, `email`, `phone`, `externalID`, `locale`, `custom`. | Updated `customer`. |

Find customer tries email, phone, then external ID and returns the first match. Supplying several values does not require them all to match. Send one trusted identifier, then verify the returned ID belongs to the authenticated customer.

#### Studio

### 1. Configure the customer action

Add **Kustomer → Find customer** to the agent or Playbook. Insert `{verified_customer_email}` as the provided email value, disable model fulfillment for it, and keep the other lookup inputs unset. For a sandbox test, enter `maya@northstar.example` manually.

Kustomer Find customer tool and its lookup inputs — Choose the identifier your application has verified.

### 2. Use the matching record

Test the lookup and inspect `customer.id`. Create `kustomer_customer_id` in **More → Variables** with an empty default. In **Capture response**, map `customer.id` to it, then insert `{kustomer_customer_id}` in the next action’s `customerID` input and disable model fulfillment for that provided value. Clear the variable before a new lookup; only continue after the current action succeeds. Have the agent answer from the current permitted fields; if lookup fails, ask the customer to use your approved support route rather than disclosing another record.

### 3. Create or update after confirmation

Use **Create customer** only when your authorized lookup found no existing profile. Use **Update customer** with the verified `customerID` for confirmed changes. Collect the intended values, confirm the change, run the action once and inspect the same record in Kustomer. An API error after creation is not permission to create another profile.

Test a known customer, an unknown identifier and a denied customer. The agent must not expose data on a failed or unauthorized lookup. Test the create/update paths with disposable profiles and confirm the reply describes only the successful change.

#### Code

Save this as `request.json` and run the [execution workflow](#execute-actions) after your backend's identity check:

```json
{
  "toolName": "kustomer_find_customer",
  "inputs": { "email": "maya@northstar.example" }
}
```

Use `output.customer.id` only after current success and the ownership check. To create or update, replace the request with the appropriate operation and confirmed values:

```json title="Create a disposable customer"
{
  "toolName": "kustomer_create_customer",
  "inputs": { "name": "Maya Chen", "email": "maya@northstar.example", "externalID": "northstar-test-1042" }
}
```

```json title="Update the verified profile"
{
  "toolName": "kustomer_update_customer",
  "inputs": { "customerID": "YOUR_CUSTOMER_ID", "locale": "en_US" }
}
```

For agent use, [add and attach](#connecting-kustomer) the chosen action with input names from its schema. Populate identity from trusted application state rather than model guesses. In a Draft conversation, ask for the confirmed profile change and verify `customer.id` and the changed field before letting the agent report success. Simulate a missing match and provider failure; neither may reuse a previous result.

### Set custom attributes

Use fields discovered from the connected Kustomer resource.

The tool editor loads the connected resource's custom fields using `org.permission.metadata.read`. Configure only the fields needed for the task. Customer, conversation and company schemas can differ, as can Draft and Published accounts.

For a standalone Code request, `custom` uses objects with `id` and `value`, not a flattened provider payload. For example, an existing numeric field can use `"custom":{"Customer tier":{"id":"tierNum","value":2}}`. Replace the ID with your actual field name. Empty values are omitted; number and boolean field suffixes are converted before the Kustomer request. This is not a field-deletion interface. Discover and verify the field in your account before attaching it to an agent.

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

## Creating support requests

Record a confirmed issue as a Kustomer conversation for your team.

**Create conversation** opens a support record for an existing `customerID`. It requires a `name` (the subject). Optional inputs are `priority` from 1 to 5, `assignedUserID`, `assignedTeamID` and `custom` attributes.

The action creates status `open`. It does not add an initial message or notify the customer. Add the confirmed issue as an [internal note](#notes-and-tags), and let your team's configured Kustomer routing handle the work. For an immediate two-way Chat transfer, use [Human agent hand-off](#human-agent-hand-off).

#### Studio

### 1. Attach Create conversation

Add **Kustomer → Create conversation** to the agent or the support Playbook. Set its Trigger to run only after the customer confirms the request. Use the verified `customerID` from [customer lookup](#customers), collect the issue and write a concise subject in **name**. Keep optional routing fields unset unless your administrator supplied the destination IDs.

Kustomer Create conversation tool with customer ID, subject and routing inputs — Create the request for the verified customer and confirmed issue.

### 2. Retain the new conversation ID

Test with a disposable customer. Create `kustomer_conversation_id` in **More → Variables** with an empty default. In **Capture response**, map `conversation.id` into it. In **Add internal note → conversationID**, insert `{kustomer_conversation_id}` as the provided value and disable model fulfillment. Clear the variable before creation and continue to the note only on current success; a previous value is not a successful new request. The agent should confirm that the request was recorded only when this call succeeded.

### 3. Test the customer journey

Ask, “The mug in order NS-1042 arrived cracked. Can your team help?” Confirm the issue when prompted. Check that exactly one open conversation appears for the correct customer, then verify any follow-up note uses that new ID. On failure, the agent must offer your support route without inventing a request reference.

#### Code

After the customer has confirmed the issue, save this as `request.json` with the authorized customer ID and [execute it once](#execute-actions):

```json
{
  "toolName": "kustomer_create_conversation",
  "inputs": {
    "customerID": "YOUR_CUSTOMER_ID",
    "name": "Damaged mug · Order NS-1042",
    "priority": 3
  }
}
```

Keep `output.conversation.id` on current success. An assignment ID is an existing Kustomer user or team ID, not a display name. The agent attachment uses these same input names; bind customer/routing IDs to trusted state and let the agent collect the confirmed subject.

Run a Draft conversation with the damaged-mug request and confirmation. Verify one open record belongs to the intended customer and that the agent reports the returned reference. If a later note fails, retain the created conversation and repair the note; do not repeat creation. After a timeout, inspect the customer's conversations before deciding whether to retry.

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

## Managing conversations

Read an authorized request before changing its status or assignment.

| Action | Inputs | Current result |
| --- | --- | --- |
| Find conversation | `conversationID`. | `conversation`. |
| Find customer's conversations | `customerID`. | `conversations`, or an empty list. |
| Update conversation | `conversationID`; optional `name`, `status`, `priority`, `assignedUserID`, `assignedTeamID`, `custom`. | Updated `conversation`. |
| Find latest message | `conversationID`. | `message`; an empty thread is an error. |

The customer-list action returns the provider's response page, not a complete paginated history. Latest message is the newest message in the conversation; inspect its direction and author before treating it as a teammate reply. It does not retrieve internal notes.

Updates accept status `open`, `snoozed` or `done` and priority 1–5. Use only the snooze behavior your Kustomer configuration supports; this action has no snooze-duration input. Enforce [customer-to-conversation access](#customer-access) before reading or changing any thread.

#### Studio

### 1. Read the permitted conversation

Add **Find conversation**, or **Find customer's conversations**, to the relevant agent or Playbook. Supply the authorized ID from your backend, not an unverified customer claim. In a sandbox conversation, ask for the test request's status and confirm the agent uses the current result.

### 2. Configure a confirmed update

Add **Update conversation**. Set its Trigger for the specific permitted change and retain the same `conversationID`. Set only the intended status, priority or assignee inputs. Have the customer or support operator confirm consequential changes before the action runs.

Kustomer Update conversation action with status, priority and assignment inputs — Change the existing request rather than creating a second conversation.

### 3. Check the result and failure path

Run the confirmed update, read the same conversation again and inspect the changed fields. To use **Find latest message**, add it separately and check `message.attributes` before quoting text. Test an empty thread and an invalid ID; the agent must explain that it could not confirm the latest state instead of using cached details.

#### Code

Use the [execution workflow](#execute-actions) with one of these requests at a time:

```json title="Read the authorized conversation"
{"toolName":"kustomer_find_conversation","inputs":{"conversationID":"YOUR_CONVERSATION_ID"}}
```

```json title="List the customer's returned page"
{"toolName":"kustomer_find_customer_conversations","inputs":{"customerID":"YOUR_CUSTOMER_ID"}}
```

```json title="Apply a confirmed update"
{"toolName":"kustomer_update_conversation","inputs":{"conversationID":"YOUR_CONVERSATION_ID","status":"open","priority":3}}
```

```json title="Read the newest message"
{"toolName":"kustomer_find_latest_message","inputs":{"conversationID":"YOUR_CONVERSATION_ID"}}
```

Read `output.conversation`, `output.conversations` or `output.message` for the chosen operation. Re-read after updating. An empty list is different from an execution error; neither confirms a customer's entire support history.

For agent use, [attach](#connecting-kustomer) only the required actions and provide authorized IDs. Test a request for the existing case's status, then a confirmed update. Verify the resulting agent reply matches the current readback. Missing IDs, no messages and provider errors must produce your fallback without leaking another thread or claiming a successful change.

<a id="notes-and-tags"></a>

## Adding notes and tags

Give teammates confirmed context without sending a customer reply.

**Add internal note** takes `conversationID` and `body`; the note is visible to Kustomer staff. **Add tags** takes `conversationID` and a JSON array of 1–20 tag names. Names that do not exist can create new tags. Keep an approved tag vocabulary rather than accepting arbitrary customer-supplied labels.

#### Studio

### 1. Add the supporting action

Attach **Add internal note** or **Add tags** to the support agent or Playbook. In Trigger, name the event that warrants it: for example, recording the confirmed replacement request after [creating its conversation](#creating-conversations). Supply `{kustomer_conversation_id}` from the successful creation result as the provided **conversationID** value. Let the agent collect the confirmed **body**, then invoke the note only after the current creation succeeds.

Kustomer Add internal note action with conversation ID and body inputs — Add customer-approved context for the receiving support team.

### 2. Check what staff receive

For notes, summarize the confirmed issue without claiming a refund or replacement was approved. For tags, enter an approved array such as `["replacement-review"]`. Run the action once and inspect the note or tag on the same conversation. The agent can acknowledge that the information was recorded; it must not say a customer message was sent.

Test a request that creates a conversation and adds one note. Then simulate a note failure: preserve the conversation ID and explain the partial result instead of opening another request. For tags, check a repeated tag does not produce a second distinct label.

#### Code

Save one request as `request.json` and run the [execution workflow](#execute-actions):

```json title="Record the confirmed issue"
{
  "toolName": "kustomer_add_conversation_note",
  "inputs": {
    "conversationID": "YOUR_CONVERSATION_ID",
    "body": "Customer confirmed a damaged mug in order NS-1042 and requested replacement review. No replacement has been approved."
  }
}
```

```json title="Add an approved tag"
{"toolName":"kustomer_add_conversation_tags","inputs":{"conversationID":"YOUR_CONVERSATION_ID","tags":["replacement-review"]}}
```

The result is `output.note` or `output.conversation`. Inspect the target in Kustomer before retrying an uncertain note write; repeated notes can duplicate. Exact duplicate names within one tag input are removed before the provider request.

For agent use, [attach](#connecting-kustomer) the selected action with the verified conversation ID and the confirmed body or approved tags. Test the full create → note journey and a failed note after successful creation. The reply must distinguish a recorded request from an unconfirmed note and must never describe either action as a customer send.

<a id="teams-and-companies"></a>

## Managing teams and companies

Validate a routing team or update an authorized company record.

**Find team** reads an existing `teamID`; it does not search for a team by name. **Update company** takes `companyID` and optional `name` (at least three characters), `externalID`, `domains` and `custom` attributes. Company changes affect the company record, so restrict them to authorized staff workflows.

#### Studio

### 1. Prepare the approved IDs

Ask your Kustomer administrator for the existing team or company ID. Attach **Find team** for a routing check, or **Update company** in the authorized staff Playbook. Keep company updates outside customer-controlled paths.

### 2. Configure and check the action

For Find team, supply `teamID` and inspect `team.id` and its name. For Update company, supply the verified `companyID`, collect and confirm only the intended fields, then inspect the returned `company` and the saved record in Kustomer.

Kustomer Update company tool with company ID and optional fields — Keep company-wide changes in an authorized staff workflow.

Test with an allowed sandbox team/company, then an invalid ID. The agent should use the current team result or confirm the saved company change, and give a clear fallback if the action fails. A successful team lookup does not prove live hand-off queue configuration.

#### Code

[Execute](#execute-actions) the operation with administrator-provided IDs:

```json title="Check a team"
{"toolName":"kustomer_find_team","inputs":{"teamID":"YOUR_TEAM_ID"}}
```

```json title="Update a permitted company"
{"toolName":"kustomer_update_company","inputs":{"companyID":"YOUR_COMPANY_ID","name":"Northstar Supply","domains":["northstar.example"]}}
```

Use `output.team` or `output.company` on current success. `domains` is an array; `externalID` maps to the provider's `externalId`. Omitted fields remain unset in the request. For custom fields, use the [custom-attribute format](#customers).

If an agent needs this capability, [attach it](#connecting-kustomer) to the staff Playbook with the trusted record ID and a specific invocation condition. Verify a confirmed sandbox change in a Draft conversation and in Kustomer, then deny an unauthorized company. Failed execution must not produce a success statement or a response from the previous company.

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

## Import help articles

Use approved Kustomer articles as your agent's Knowledge.

Article import uses the **Published Kustomer connection** and its `org.permission.kb.read` permission. The API key for actions can serve both jobs when it has the required roles; attaching a tool does not import content.

| Setting | Purpose |
| --- | --- |
| Languages, Knowledge bases, Categories, Tags | Narrow the articles to the support content you want. |
| Scope | Select the article visibility your deployment is allowed to use. Review private content before exposing an agent to customers. |
| Refresh rate | Choose the supported refresh schedule; the initial selection is Never. |
| Smart chunking | Choose how imported content is prepared for retrieval. |
| Folder | Choose where imported documents appear in Knowledge. |
| Preserve Kustomer structure | Group documents by language and category. |
| Metadata | Add your own retrieval metadata. |

#### Studio

### 1. Open the Kustomer import

In your project's **Knowledge base**, choose **Add data source → Kustomer**. If asked to connect, enter the Published org slug and API key from [Connecting Kustomer](#connecting-kustomer).

### 2. Select the approved content

Set the filters, check the matching source count and choose the folder, chunking and refresh settings. Select **Import … data sources** to start the import.

Kustomer article import dialog with filters and import settings — Filter the approved articles before importing them into Knowledge.

### 3. Verify the agent's answer

Wait for processing to finish, open an imported document and check its text and language. Enable the agent's **Knowledge base** system tool and ask a policy question whose answer is in that article. Check the answer and source, then ask a question the article does not answer; the agent should acknowledge the gap.

#### Code

The native Kustomer import is configured in the browser. Open [Agent studio](https://creator.voiceflow.com), select the project, then **Knowledge base → Add data source → Kustomer**. The administrator supplies the Published org slug/key; choose the approved filters and processing options, then select **Import … data sources**. Wait for processing and inspect the imported text before using it from Code.

Kustomer Knowledge import settings required before programmatic retrieval — Complete the native import before testing retrieval through the API.

Use [List documents](/docs/cli/commands/document/list) to find the imported records in the intended Environment and [Query Knowledge Base](/docs/cli/commands/knowledge-base/query) for a diagnostic retrieval check. These calls do not authorize or create a native Kustomer import.

Finally, enable Knowledge for your agent and run a [Draft conversation](/docs/cli/commands/conversation/send) asking a question from an imported article. Confirm the answer uses the approved content and its source. A document listing or diagnostic query alone does not establish that the agent used it. Test an unanswerable question as well.

### Refresh or remove imported content

Check refresh behavior, changed filters and content removal before relying on updated answers.

Use the Knowledge source's available sync/refresh controls and inspect the completed document status. Where a managed integration source is offered, its synchronization can reconcile newly matching articles and changed filters. Existing individual imports are not automatically equivalent to a managed source; review the interface's adoption notice before changing their behavior.

For an existing individual import, re-import with the intended filters to bring in matching translations and update matching records. Narrowing filters alone does not prove previous documents were removed: inspect the old documents and remove content the agent must no longer retrieve. After an article edit, removal or permission change, verify both the Knowledge text and a fresh agent answer. Remove unwanted sources using Knowledge's deletion controls; a stopped refresh schedule is not deletion.

Before disconnecting, set refresh to Never for the affected imports. Reconnect an expired key, run a refresh/import and check the actual result; reconnecting does not by itself prove stale documents recovered.

<a id="human-agent-hand-off"></a>

## Human agent hand-off

Continue a live customer Chat with a Kustomer teammate.

This path uses Voiceflow's **Kustomer** Handoff provider. The widget or your custom Chat client remains the customer's interface; your teammate works in Kustomer. The connection can create or reuse a customer and opens a new conversation for the hand-off.

The same Kustomer credential also needs a **Webhook signing secret**. Despite the field's name, this adapter checks the literal **x-vf-secret** callback header; it does not validate Kustomer's raw webhook HMAC. A Kustomer administrator or developer must configure the [formatted callback workflows](#kustomer-callbacks). Saving the in-app connection does not create them.

For production, create `customer_id`, `customer_email` and `customer_name` in **More → Variables**, leaving defaults empty. Your authenticated application supplies their verified values in the [Chat action request variables](/docs/api-reference/v4interact/interact-non-stream) before the Workflow runs. Insert those variable references in the identity fields; do not share the pilot’s fixed customer across sessions.

| Handoff setting | What to supply |
| --- | --- |
| Title | Start the subject with `[Voiceflow]` so the callback Workflow can select this deployment’s closure events. |
| End user ID | An existing Kustomer customer ID when using this lookup; it is not the data tool's externalID lookup. |
| User email, Customer name | Verified identity values from your application. Email lookup is tried before the supplied customer ID. |
| Assigned team ID | Required. The hand-off adapter sends this value as Kustomer `queue.id`; have your administrator supply and verify the receiving queue ID. The data tool's team ID is a separate assignment concept. |
| Language, Brand | Stored with the hand-off context; these inputs do not establish translation or provider-side brand routing. |
| Context | Choose the transcript or the permitted summary staff should receive. |
| Configuration | Optional `noteBodyText` creates a private note. Its failure does not prevent the hand-off; verify the note separately. |
| Return and Failure paths | Decide what happens after support ends or connection fails. |

#### Studio

### 1. Have the administrator prepare callbacks

Give the Kustomer administrator the [callback setup](#kustomer-callbacks). Obtain the receiving queue ID, the shared callback secret, and confirmation that human messages and closure reach Voiceflow. This is separate from saving the org/API key.

### 2. Save the hand-off connection

Return to **More → Integrations → Kustomer**, enter the org/API key and **Webhook signing secret**, then save the connection. Use the callback secret supplied by the administrator.

### 3. Configure the Handoff step

Open a support **Workflow**, add a **Handoff** step, choose **Kustomer**, and supply the required queue and verified identity. Choose the context your support team needs and configure **Return** and **Failure** behavior.

Kustomer Handoff step with identity, assigned team ID and conversation context — Configure the receiving queue, customer context and return behavior.

### 4. Attach the support Workflow

In **Agent → Workflows**, add the saved Workflow and explain in Instructions when to use it, such as when a customer requests a person. Test the [complete exchange](#test-kustomer-handoff) before publishing. A configured step alone does not route the agent to it.

#### Code

Use the same [connection operation](#connecting-kustomer), adding `credentials.secretKey` with the callback header secret. It updates Published; use your test project. Have the Kustomer administrator configure the callback workflows and supply the receiving queue ID before testing. The Workflow below uses one dedicated test customer; replace all pilot identity values before production.

Save `kustomer-workflow.json`. Replace the queue placeholder and use one dedicated test customer. Do not deploy this fixed identity for multiple customers.

```json title="kustomer-workflow.json"
{
  "name": "Kustomer support",
  "entry": "handoff",
  "blocks": [{
    "key": "handoff",
    "name": "Connect Kustomer support",
    "steps": [{
      "kind": "handoff",
      "content": {
        "config": {
          "provider": "kustomer",
          "title": "[Voiceflow] Customer requests support",
          "brand": "",
          "endUserId": "YOUR_KUSTOMER_CUSTOMER_ID",
          "userEmail": "maya@northstar.example",
          "customerName": "Maya Chen",
          "userLanguage": "en",
          "assignedTeamId": "YOUR_KUSTOMER_QUEUE_ID"
        },
        "handoffContext": { "type": "full" },
        "returnPath": true,
        "failPath": true
      }
    }]
  }]
}
```

This pilot leaves Return and Failure exits unlinked, handing control back to the calling agent. Define the fallback in Instructions or link the exits to Workflow blocks.

Save `prepare-kustomer-patch.sh`. Run it after Workflow creation and agent read succeed. Inspect `kustomer-created.json` for `workflow.id`, `unresolvedReferences` and diagnostics first; stop on unresolved values. Keep the returned ID rather than repeating creation after a later failure.

```bash title="prepare-kustomer-patch.sh"
set -euo pipefail
WORKFLOW_ID=$(jq -er '.workflow.id' kustomer-created.json)
jq --arg id "$WORKFLOW_ID" '
  .agent | {
    workflows: ((.workflows // []) + [{workflowID: $id, description: null}]),
    instructions: ((.instructions // "") + "\nWhen a customer asks for a person, use `Kustomer support`. If it cannot connect, offer the approved alternative contact route.")
  }
' agent-before.json > agent-patch.json
```

The patch preserves the current Workflow registry and Instructions. Replace the fallback with your real contact option and review `agent-patch.json` before applying it. Both methods below cover create → read → patch → compile.

#### API

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @kustomer-workflow.json > kustomer-created.json

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&includeInstructions=true" \
  --header "Authorization: Bearer $VF_TOKEN" > agent-before.json
```

After inspecting the create result, prepare and review the attachment:

```bash
bash prepare-kustomer-patch.sh
cat agent-patch.json
```

Apply the reviewed patch and compile Draft:

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

curl --fail-with-body --silent --show-error --request PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```bash
vf --output-format json workflow create --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" < kustomer-workflow.json > kustomer-created.json

vf --output-format json agent get --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" --include-instructions > agent-before.json
```

After inspecting the create result, prepare and review the attachment:

```bash
bash prepare-kustomer-patch.sh
cat agent-patch.json
```

Apply the reviewed patch and compile Draft:

```bash
vf --output-format json agent update --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" < agent-patch.json

vf --output-format json environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT"
```

A custom customer interface must implement the [Chat handoff event contract](/docs/api-reference/agent-runtime/chat/handoff): keep the active session connected, render teammate replies, send subsequent customer messages through handoff requests and handle completion. Do not use the **Custom Handoff** connection API for the built-in Kustomer provider.

Run the [full exchange test](#test-kustomer-handoff) through that client and the teammate's Kustomer workspace. A successful compile, connection response or `chat_started` event does not prove a human reply reached the customer.

### Configure Kustomer callbacks

<a id="kustomer-callbacks" />

#### Studio

Ask your developer to deploy the supplied callback normalizer with persistent state and an approved list of human teammate IDs. Give them the Code instructions in this section. Obtain the worker’s HTTPS callback URL, its ingress secret, the separate Voiceflow callback secret, and confirmation that failed jobs remain queued for recovery.

Your Kustomer administrator then saves and enables two Workflows: a message trigger reconciles outbound replies and Voiceflow-origin seed messages, and a status-change-to-done trigger queues closure. Both call that worker with its ingress header; they do not post raw events directly to Voiceflow. The developer supplies the exact trigger/body mapping below as the setup handoff.

Before continuing, have the developer show a queued callback draining successfully, and have the administrator confirm both Workflows are enabled. Then run the customer exchange test below, including a final reply followed immediately by resolution. A saved connection or a queued callback does not prove delivery.

#### Code

The supplied [callback normalizer](/docs/examples/kustomer-handoff/callbacks.mjs) checks approved human authors, rereads Kustomer and queues replies before closing the Voiceflow hand-off. Your developer hosts it; the Kustomer administrator connects two Workflows to it. No customer API key or message text belongs in a public URL.

### 1. Deploy the callback worker

Download [callbacks.mjs](/docs/examples/kustomer-handoff/callbacks.mjs), [start.mjs](/docs/examples/kustomer-handoff/start.mjs) and the [deployment notes](/docs/examples/kustomer-handoff/README.md) into one directory. Use Node.js 22.13+ with SQLite available, one worker process and a private persistent state volume. Put an HTTPS reverse proxy in front of its loopback listener with a 64 KiB body limit and rate limits.

Set these server environment values, then run `node start.mjs`:

| Value | Producer |
| --- | --- |
| `KUSTOMER_ORG`, `KUSTOMER_API_KEY` | Administrator supplies the org slug and a key with conversation/message read. |
| `KUSTOMER_HUMAN_IDS` | Administrator verifies the comma-separated Kustomer user IDs belong to the human teammates allowed to reply. Do not include service users, bots or AI assistants. |
| `KUSTOMER_CALLBACK_SECRET` | Developer generates the ingress secret for Kustomer → worker. |
| `VF_HANDOFF_SECRET` | The different secret saved as **Webhook signing secret** in Voiceflow. The worker sends it in `x-vf-secret`. |
| `KUSTOMER_STATE_PATH` | Absolute SQLite file path on the worker’s private persistent volume. |

The developer hands the administrator `https://YOUR_CALLBACK_HOST/kustomer/callbacks`, the ingress secret and an operational check that the worker is running with its state volume. This address is your service, not a new Voiceflow endpoint.

### 2. Create the two Kustomer Workflows

In **Settings → Platform → Workflows**, create one Workflow per row. Add a **REST API: JSON** action. Use the builder’s sample output to select the paths; [Kustomer trigger output](https://developer.kustomer.com/docs/workflows/triggers-and-actions) flattens attributes and relationships.

| Workflow | Trigger and condition | REST action data |
| --- | --- | --- |
| Queue a reply | `kustomer.message.create`; `direction` is `out` **or** `app` is `voiceflow` (including incoming seeds). | `event: message`, `conversationId` from `/#steps.1.conversation`. |
| Queue closure | `kustomer.conversation.update`; `changes.attributes.status.after` is `done` and `name` starts with `[Voiceflow]`. | `event: end`, `conversationId` from `/#steps.1.id`, `messageCount` from `/#steps.1.messageCount`. |

For each action, set `method` to `post`, `uri` to your callback-worker URL and `json` to `true`. Add `Content-Type: application/json` and `x-kustomer-callback-secret` headers. Store that header’s value in a secret Workflow variable and insert it by its actual variable ID.

The reply action’s data is:

```json
{"event":"message","conversationId":"/#steps.1.conversation"}
```

The closure action’s data is:

```json
{"event":"end","conversationId":"/#steps.1.id","messageCount":"/#steps.1.messageCount"}
```

The Voiceflow-origin condition is required: a human reply can arrive before the connector has seeded its first message. That later seed queues another reconciliation. Unrelated conversations with no Voiceflow-origin messages are ignored. For the named `[Voiceflow]` hand-offs, an early closure stays queued until its seed appears; its closure count is retained. Keep that title prefix when resolving a hand-off.

Save and enable both Workflows. Inspect each REST action’s response; `202` means the hint was queued. It does not certify delivery to the customer. Configure the administrator’s error handling for non-2xx responses and review failed runs. Do not point raw Kustomer outbound webhooks directly at Voiceflow.

### 3. Verify normalized delivery

The worker rechecks the provider record, confirms Voiceflow-origin messages and forwards only public outbound text from the administrator-approved human IDs. It excludes automated messages, the connector’s own messages and internal notes. On closure, it drains qualifying unsent messages before sending `end`, checking the provider’s message count, the closure event’s count, newly queued hints and resolved state.

The worker posts the normalized `message_received` and `end` bodies to `https://general-runtime.voiceflow.com/handoff/webhook/kustomer`. It retains failed jobs for retry; the supplied `node start.mjs` service reports a redacted pending-job count and failure reasons to stderr at most every 30 seconds. A custom host can inspect `callbacks.pending()`. Histories above 500 messages or inconsistent provider snapshots stop delivery rather than silently losing the final reply.

Ordinary event replay is deduplicated in persistent state. Delivery remains at least once: a crash between Voiceflow accepting a reply and the worker recording it can produce a duplicate after recovery. Keep the normal support route available, and complete the rapid reply-and-resolution test below before release.

### Test the live exchange

<a id="test-kustomer-handoff" />

### 1. Request a human from the customer interface

Open a fresh sandbox Chat, ask for a person and check that the intended Workflow runs. Verify the correct customer, new conversation, queue and permitted transcript or summary in Kustomer. If identity lookup misses, check that a new customer was intended rather than assuming a profile was reused.

### 2. Exchange messages in both directions

Have the human teammate send a public reply and confirm it appears in the customer interface. Send a customer follow-up and confirm it appears in the same Kustomer conversation. Add an internal note and trigger a bot reply; neither may be forwarded as a human message.

### 3. Check completion and fallback

Send a final reply, then resolve the conversation. Confirm the reply reaches the customer before the end event and that the configured Return path runs. Test rapid reply-and-resolution as well. Use an invalid queue to verify the initial connection Failure path and approved support alternative. Separately interrupt callback delivery after a successful connection: confirm the worker retains the pending job, restore delivery and check the customer receives it. A later callback outage does not automatically take the initial Failure path.

### The customer never receives a reply

Check normalized callbacks, human filtering and the active customer connection.

Inspect the Kustomer Workflow run and REST response. Match the exact `conversationId`, body `type` and `x-vf-secret`. Verify the message is a public outbound human reply and the customer session still consumes hand-off events. A successful write to Kustomer is only one direction of the conversation. Fix delivery before treating the hand-off as ready.

### Include files in a hand-off

Respect this provider's upload shape and test the customer-visible result.

The Kustomer adapter's customer upload path requires file size, uploads to the provider's storage fields and attaches the file to the conversation message. It handles the first file in a file-upload request; send and verify one file at a time. Custom clients must follow the [Chat upload contract](/docs/api-reference/agent-runtime/chat/handoff) rather than posting a local file URL. The normalized teammate-reply callback above carries text; it does not establish inbound staff-file rendering.
