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

# NICE CXone integration

> Connect Voiceflow AI agents to NICE CXone phone and Chat conversations with Virtual Agent Hub, customer context and human agent hand-off.

## Overview

Voiceflow integrates with **NICE CXone** through **Virtual Agent Hub**. Keep your CXone phone number or ACD Chat entry point, use a Voiceflow agent for self-service, and return the customer to a CXone queue when they need a person.

Your team hosts an exchange adapter between the two platforms. CXone sends each customer turn as text; the adapter calls Voiceflow and returns the reply. For phone calls, CXone handles speech recognition and text-to-speech. This recipe covers CXone phone and ACD Chat scripts. Digital Experience channels need their own verified routing and message mapping. The adapter uses turn-by-turn text, rather than Voiceflow's audio WebSocket or SIP transport.

### Examples of when to use NICE CXone

- **[Answer inbound questions](#preparing-your-agent)** — use approved Knowledge and your agent's tools before involving a contact-center agent.
- **[Keep existing entry points](#connecting-cxone)** — attach self-service to a CXone script without moving the phone number or customer interface.
- **[Pass customer context](#customer-context)** — carry an existing case reference into the AI conversation.
- **[Human agent hand-off](#human-agent-hand-off)** — return control to CXone and route the customer to a staffed skill.
- **[Test before routing traffic](#testing-and-launch)** — verify replies, human routing, silence and adapter failure through the real point of contact.

### What you need

- A NICE CXone administrator who can configure **Virtual Agent Hub**, edit CXone **Studio** scripts and assign a test point of contact. For phone calls, also prepare a turn-by-turn transcription profile and speech playback.
- An editable Voiceflow project, an isolated test [Environment](/docs/documentation/deploy/environments/overview) and a server-side [API credential](/docs/api-reference/authentication).
- A service owner to host an authenticated HTTPS exchange endpoint and maintain its session store. The [downloadable adapter](#connecting-cxone) is a locally tested pilot, not a managed Voiceflow endpoint.
- A staffed CXone **ACD skill** and an explicit fallback route. CXone Studio below means NICE's routing editor; **Agent studio** means Voiceflow's visual editor.

#### Studio

Configure the agent in [Agent studio](https://creator.voiceflow.com). Your integration engineer hosts the adapter; your CXone administrator connects it to the routing script. Agent studio does not provision CXone scripts or an exchange endpoint.

#### Developer

Use Node.js 22 or later for the example adapter. Agent authoring examples use cURL, jq and the current [Voiceflow CLI](/docs/cli/install). Set `PROJECT_ID`, `ENVIRONMENT_ALIAS` and `VF_TOKEN` for a test Environment. Keep the project credential and exchange secret on your server.

<a id="customer-context"></a>

## Customer context

Pass trusted case information from the CXone script into the Voiceflow conversation.

### Map case fields

In the CXone script's **Custom Payload** snippet, populate these fields from your authenticated case lookup or contact attributes. Pass the resulting JSON through the exchange action's `customPayload` input:

```json title="Example context from the CXone script"
{
  "cxone_customer_name": "Ada Nguyen",
  "cxone_case_id": "CASE-2048"
}
```

These are fields defined by this recipe. The adapter allowlists them and writes them to the matching Voiceflow session variables before processing each turn. It ignores other custom payload fields and limits each value to 200 characters. Context is not identity verification; perform sensitive account checks before exposing protected records or executing account changes.

#### Studio

In your Voiceflow project, open **More → Variables** and create `cxone_customer_name` and `cxone_case_id`. Insert their Variable references in Instructions or the tool inputs that need them; for example, `Customer name: {cxone_customer_name}`. Create these resources before writing the prompt references in Preparing your agent. Leave test values out of the live connection's defaults; the exchange request supplies each customer's context.

#### Developer

Create the two Variables in the same project and Environment. Reuse an existing Variable with the same name rather than creating duplicates.

#### API

```bash title="Create context Variables"
for name in cxone_customer_name cxone_case_id; do
  jq -n --arg name "$name" '{name:$name,color:"#515A63",defaultValue:""}' |
    curl --fail-with-body --request POST \
      "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
      --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' --data-binary @-
done
```

#### CLI

```bash title="Create context Variables"
for name in cxone_customer_name cxone_case_id; do
  vf variable create --project-id "$PROJECT_ID" \
    --environment-alias "$ENVIRONMENT_ALIAS" --name "$name" \
    --color-param '#515A63' --default-value '""'
done
```

### Keep context available to the receiving agent

Keep the CXone case reference in the routing script when the AI begins, then map it to the receiving agent's workspace on the human route. The adapter returns `customPayload.reason`; it does not automatically create a CXone case, populate a screen pop or copy the Voiceflow transcript into the agent desktop. Configure those mappings in your CXone script and verify them with the receiving team.

<a id="preparing-your-agent"></a>

## Preparing your agent

Create short text replies and a structured way to request a CXone human agent.

### Configure the conversation

Use a text agent for both CXone phone and Chat turns. Keep replies suitable for speech, and avoid cards, buttons, audio traces and attachments: the adapter below delivers text only. You can use the agent's [Knowledge](/docs/documentation/build/querying-the-knowledge-base) and verified tools to answer questions; connecting CXone does not import its records or content.

#### Studio

Open the project in **Agent studio → Agent → Instructions**. Define what the agent can resolve, the policy sources it should use and when it must invoke the **CXone hand-off** Workflow configured below. In **System tools**, disable **Buttons**, **Cards** and **Carousels** for this text exchange.

Organize the instructions with headings and Steps. Attach the relevant Playbooks, tools and the hand-off Workflow, then insert their resource references so the instructions identify what to invoke. The example shows delivery and returns Playbooks, approved Knowledge and a **Look up order** tool connected to the fictional retailer's own order service; that tool is not a CXone records connection.

Voiceflow agent Instructions for NICE CXone text exchanges — Prepare text-only replies and route human support requests through the CXone hand-off Workflow.

#### Developer

Update the agent's Instructions and disable rich output. Keep your existing Playbooks and Workflows; these examples omit their registries rather than replacing them. Attach the hand-off Workflow in Human agent hand-off below.

Save these fields as `agent.json`, replacing the example policy with your actual instructions:

```json title="Agent settings"
{
  "instructions": "Answer customer questions using approved Knowledge and tools. Keep replies short enough to read aloud. Customer name: {cxone_customer_name}. Case reference: {cxone_case_id}. Treat these values as context, not identity verification. When a customer asks for a person, invoke the CXone hand-off Workflow. Never claim a transfer succeeded before CXone takes over.",
  "buttonTool": null,
  "cardTool": null,
  "carouselTool": null
}
```

#### API

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

#### CLI

```bash title="Update agent settings"
vf agent update --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" < agent.json
```

### Example agent instructions

Adapt the support boundary to the work your agent can actually complete.

```markdown title="Customer support instructions" presentation="website"
# Role
Help customers understand delivery and return policies using approved Knowledge.
Ask one question at a time. Keep each reply short enough to read aloud.

# Customer context
Customer name: {cxone_customer_name}.
Case reference: {cxone_case_id}.
Use this reference to identify the existing case being discussed.
Do not treat a name, case reference or caller number as proof of identity.

# Human support
When a customer asks for a person, invoke the CXone hand-off Workflow.
Do not promise a queue, wait time or completed transfer yourself.
```

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

## Connecting CXone

Connect Virtual Agent Hub to an authenticated exchange endpoint and the intended Voiceflow Environment.

### Host the exchange endpoint

Download [exchange.mjs](/docs/examples/nice-cxone/exchange.mjs). It translates NICE's exchange request into Voiceflow session and text-action calls, then returns NICE's response envelope. Your service must expose it through HTTPS; a public Voiceflow runtime URL cannot replace this translation layer.

#### Studio

Give your integration engineer the adapter and the target Voiceflow **Project ID** and **Environment alias**. Have them configure its server-side Voiceflow credential, your CXone **business unit ID**, the exact **Virtual Agent (Bot) Name**, and a new random exchange secret. Obtain the resulting HTTPS URL ending in `/exchange` and its secret through your team's secure handover.

The adapter uses that Environment's **Published** version. Finish and publish the pilot configuration in Testing and launch before the first end-to-end call.

#### Developer

Set the adapter's environment variables. `CXONE_BOT_NAME` must match the name you will enter in Virtual Agent Hub. `CXONE_BUSINESS_UNIT` scopes requests to that CXone tenant. The exchange secret authenticates CXone to your service; it is separate from `VF_TOKEN`.

```bash title="Start the local pilot adapter"
export PROJECT_ID='YOUR_PROJECT_ID'
export ENVIRONMENT_ALIAS='YOUR_TEST_ENVIRONMENT_ALIAS'
export CXONE_BUSINESS_UNIT='YOUR_CXONE_BUSINESS_UNIT_ID'
export CXONE_BOT_NAME='Voiceflow support'
export CXONE_EXCHANGE_SECRET="$(openssl rand -hex 32)"
# Set VF_TOKEN securely in this shell or your service's secret store.
node exchange.mjs
```

The pilot listens on `127.0.0.1:8787`. Put it behind your HTTPS service ingress and route `POST /exchange` to it. Store the same exchange secret in Virtual Agent Hub's header configuration. Do not point CXone at localhost, expose the Node listener without authentication, or place `VF_TOKEN` in the request body.

### Configure Virtual Agent Hub

In **NICE CXone**, open **Connection Hub → Virtual Agent Hub** and add a bot with provider **Custom Exchange Endpoint**. Use integration version **3.0.0**, your HTTPS `/exchange` URL and a **Custom Header** named `Authorization` with value `Bearer YOUR_EXCHANGE_SECRET`. Use the exact bot name and business unit configured on the adapter.

For **Chat**, choose **Text Only**. For **phone**, choose **Turn by Turn Control (CXone Voice Bot Gateway)** and **Use Turn-by-Turn Transcription Profile** with your CXone transcription profile. Configure speech playback in the CXone script. This adapter accepts text, not recorded audio from bot-account transcription.

Follow [NICE's Custom Exchange Endpoint configuration](https://help.nice-incontact.com/content/aiassistantsandbots/customaiintegrations/vah/implementation.htm) for the provider fields and transcript-capture settings. The endpoint timeout defaults to **10,000 ms**. The pilot gives its Voiceflow calls a combined **8-second** deadline; measure actual latency before changing either setting.

### Connect the routing script

Start with [NICE's integration scripts and example](https://help.nice-incontact.com/content/aiassistantsandbots/customaiintegrations/vah/exampleintegration.htm). Use **Voicebot Exchange** for phone or **Textbot Exchange** for Chat, selecting the same Virtual Agent Hub app on every exchange action.

Have the CXone script owner configure these boundaries:

- **First request:** send the automated intent `WELCOME`; the adapter creates one Voiceflow session and sends `launch` once.
- **Following turns:** send the customer's text. Set **botSessionStateVarName (out)** to `botSessionState`, and pass `{botSessionState.asJSON()}` into the next exchange's **botSessionState** input. Do not reset it between actions.
- **Replies:** set **nextPromptVarName (out)** to `nextPromptSequence`, then pass that output into NICE's prompt-and-collect loop on `OnPromptAndCollectNextResponse`.
- **Return and failure:** set **customPayloadVarName (out)** to `cxoneResult`. Explicitly wire `OnReturnControlToScript`, error/timeout branches and the fallback. Read `cxoneResult.reason` on return; use Human agent hand-off below for its values.

Assign a **test** point of contact to the completed script. Keep the existing customer route unchanged until the full journey passes. This route does not require a Voiceflow phone-number assignment or SIP trunk; CXone retains the call.

### Session and hosting requirements

Keep one customer conversation across retries, restarts and delayed requests.

The example is a **single-process pilot** with an in-memory store. It scopes sessions by business unit, bot and contact ID; returns an opaque `exchangeID` in `botSessionState`; caches each `requestId` response; and serializes turns for a contact. It never returns the Voiceflow session key to CXone.

The pilot keeps up to 500 contacts, 100 cached responses per contact and a 30-minute idle lifetime. These are example-service bounds, **not Voiceflow or NICE product limits**. A missing or expired session returns control rather than silently starting another conversation. After hand-off or completion, new customer turns are refused.

Before production, replace in-memory state with a shared, durable store and a per-contact lock. Preserve request fingerprints, cached replies, terminal state and expiration across instances and restarts. Replaying a turn can repeat a tool's side effect. On an uncertain timeout, route to the configured fallback; do not automatically create and launch a replacement session. Enforce HTTPS, request-size/rate limits and secret rotation at your ingress.

NICE's customer-ended notification is not guaranteed. Expire stored sessions independently and stop sending actions when the CXone contact closes. The pilot stopping its own turns does not issue a separate Voiceflow session-delete request.

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

## Human agent hand-off

Use an explicit agent signal, then let CXone route the existing contact to the right skill.

### Add the hand-off signal

The adapter recognizes a trace named **`cxone_handoff`**. It returns `ReturnControlToScript` with `customPayload.reason: "human_agent"`; it does not call a CXone transfer API. Configure the agent to invoke the Workflow when the customer asks for a person.

#### Studio

### 1. Create the hand-off Workflow

Open **Agent** and click **+** beside **Workflows**. Create **CXone hand-off** and describe its trigger as “Use when the customer asks to speak with a human support agent.” Ensure it is attached to the agent.

### 2. Emit the structured signal

Open that Workflow's canvas. In the step menu, choose **Tools → Function**, connect it after Start and create **Request a CXone agent**. In the Function's **JavaScript** editor, replace the starter code with:

```js title="Request a CXone human agent"
export default async function main() {
  return { trace: [{ type: 'cxone_handoff', payload: {} }] };
}
```

Close the Function editor. Keep **Async execution** off, then connect the Function step to **Logic → End** so the Function finishes before the Workflow ends.

A CXone hand-off Workflow calling the Request a CXone agent Function before End — Emit the structured hand-off trace, then end the AI Workflow; CXone performs the transfer.

The Function emits the signal; it does not select a NICE provider or transfer the call by itself. The adapter stops forwarding turns after the signal.

#### Developer

The Function returns the hand-off trace. Download [handoff.mjs](/docs/examples/nice-cxone/handoff.mjs) and save it beside your authoring files:

```js title="Hand-off signal"
export default async function main() {
  return { trace: [{ type: 'cxone_handoff', payload: {} }] };
}
```

Save the Function request. Each method below creates the Function, builds a Workflow around its returned ID and attaches that Workflow to the agent:

```bash title="Prepare Function request"
jq -n --rawfile code handoff.mjs \
  '{name:"CXone hand-off",code:$code,description:"Request a CXone human agent."}' > function.json
```

#### API

```bash title="Create the Function"
curl --fail-with-body --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/function?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @function.json > function-result.json
export FUNCTION_ID="$(jq -er '.function.id' function-result.json)"
jq -n --arg id "$FUNCTION_ID" '{name:"CXone hand-off",entry:"handoff",blocks:[{key:"handoff",name:"Return to CXone",steps:[{kind:"function",content:{functionID:$id}},{kind:"end"}]}]}' > workflow.json
```

Continue with the Workflow request and preserve the agent's existing registry:

```bash title="Create and attach the Workflow"
curl --fail-with-body --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @workflow.json > workflow-result.json
export WORKFLOW_ID="$(jq -er '.workflow.id' workflow-result.json)"
curl --fail-with-body \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" > agent-current.json \
  --header "Authorization: $VF_TOKEN"
jq --arg id "$WORKFLOW_ID" '{workflows: ((.agent.workflows // []) + [{workflowID:$id,description:"Use when the customer asks to speak with a human support agent."}])}' \
  agent-current.json > attach.json
curl --fail-with-body --request PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' --data-binary @attach.json
```

#### CLI

```bash title="Create the Function"
vf function create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT_ALIAS" \
  --output-format json < function.json > function-result.json
export FUNCTION_ID="$(jq -er '.function.id' function-result.json)"
jq -n --arg id "$FUNCTION_ID" '{name:"CXone hand-off",entry:"handoff",blocks:[{key:"handoff",name:"Return to CXone",steps:[{kind:"function",content:{functionID:$id}},{kind:"end"}]}]}' > workflow.json
```

Continue with the Workflow request and preserve the agent's existing registry:

```bash title="Create and attach the Workflow"
vf workflow create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT_ALIAS" \
  --output-format json < workflow.json > workflow-result.json
export WORKFLOW_ID="$(jq -er '.workflow.id' workflow-result.json)"
vf agent get --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT_ALIAS" \
  --output-format json > agent-current.json
jq --arg id "$WORKFLOW_ID" '{workflows: ((.agent.workflows // []) + [{workflowID:$id,description:"Use when the customer asks to speak with a human support agent."}])}' \
  agent-current.json > attach.json
vf agent update --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT_ALIAS" < attach.json
```

The attachment examples preserve existing Workflow entries and omit Playbooks. Read the returned registry before patching; do not use an empty registry or overwrite unrelated routing. The Function emits the hand-off trace and the final End step prevents the Workflow from continuing the AI conversation. A natural End without the hand-off trace is treated as `completed` instead.

### Route the returned contact

In the CXone script's **OnReturnControlToScript** branch, inspect `cxoneResult.reason`, bound from the response's `customPayload` through **customPayloadVarName (out)**. Keep these outcomes separate:

| Reason | CXone script action |
| --- | --- |
| `human_agent` | Play any final returned prompt once, then route the existing contact to the staffed ACD skill. |
| `completed` | Play the final reply and follow your normal completion route. |
| `customer_left` | Close the integration's local state; do not request another agent for a departed customer. |
| `upstream_error`, `session_expired`, `session_mismatch`, `session_finished`, `unsupported_input`, `duplicate_welcome`, `capacity` | Use the configured recovery or human fallback route. |

Use the CXone script's [Reqagent action](https://help.nice-incontact.com/content/studio/actions/reqagent/reqagent.htm) with **Skill** set to the receiving phone or ACD Chat skill. The skill's channel must match that contact. Do not send `human_agent` back into the AI exchange loop or leave the return branch connected only to Default. See [Voicebot Exchange branches](https://help.nice-incontact.com/content/studio/actions/voicebotexchange/voicebotexchange.htm) and [Textbot Exchange branches](https://help.nice-incontact.com/content/studio/actions/textbotexchange/textbotexchange.htm).

The same script must handle `UserInputTimeout` and the exchange action's transport-error/timeout branches. The pilot returns `UserInputTimeout` for `NO_INPUT`; it forwards `DTMF_AS_TEXT` as a text message only when your CXone script is configured to collect digits. It does not process raw audio or infer a payment/identity workflow from those digits.

<a id="testing-and-launch"></a>

## Testing and launch

Verify the customer journey through CXone before changing a live entry point.

### Publish the pilot Environment

#### Studio

Run the agent in **Agent studio** first. Check an answer from approved Knowledge and a request for a person. Confirm that the hand-off Workflow emits `cxone_handoff` in the test traces. Then select **Publish**, name the release **CXone pilot** and publish to the test Environment used by the adapter.

Publish dialog naming the CXone pilot release — Publish the tested Environment before the CXone adapter creates runtime sessions.

#### Developer

Test the Draft using [conversation tests](/docs/api-reference/resources/conversation), then publish the test Environment. Runtime session creation uses its Published version; compiling Draft alone does not publish it.

#### API

```bash title="Publish the pilot"
curl --fail-with-body --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT_ALIAS/publish?projectID=$PROJECT_ID" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data '{"name":"CXone pilot"}'
```

#### CLI

```bash title="Publish the pilot"
vf environment publish --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" --name 'CXone pilot'
```

### Verify replies and human routing

Use Virtual Agent Hub's test control, then make a call or send a message through the actual CXone test point of contact. Test each configured channel separately:

- **Conversation continuity:** send `WELCOME`, ask two related questions and confirm the second turn retains context. Retry the same request ID and confirm it does not produce a second Voiceflow turn.
- **Customer context:** provide a test case ID and confirm the AI uses the correct value. Check a second contact cannot read the first contact's session or case.
- **Human support:** ask for a person. Confirm the adapter returns `human_agent`, the same CXone contact reaches the expected staffed skill, and the receiving agent sees the case reference.
- **Completion:** finish a self-service task. Confirm the `completed` route plays the final answer and does not enter the human queue.
- **Recovery:** disconnect the adapter, use an invalid Voiceflow credential, and exercise silence/timeout. Confirm the customer's actual fallback rather than just an HTTP response.

### Switch the entry point

Record the tested bot configuration, script version, Voiceflow release and receiving skill. Assign the approved script to the intended CXone point of contact, keeping the previous assignment ready for rollback. Existing numbers stay in CXone; moving a number to Voiceflow is not a prerequisite for this connection.

Complete the [Contact Center launch checklist](/docs/guides/integrations/contact-centers/test-connection) with your CXone administrator. The adapter's automated checks use mocked runtime responses; they do not establish a successful call in your NICE tenant.
