Build with

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

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 and a server-side API credential.
  • A service owner to host an authenticated HTTPS exchange endpoint and maintain its session store. The downloadable adapter 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. 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.

Code

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

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:

Example context from the CXone script

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.

Code

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

Create context Variables

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.

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

Prepare text-only replies and route human support requests through the CXone hand-off Workflow. Photo:

Code

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:

Agent settings
Update agent settings

Example agent instructions

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

Connecting CXone

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

Host the exchange endpoint

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

Code

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.

Start the local pilot adapter

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

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:

Request a CXone human agent

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

Emit the structured hand-off trace, then end the AI Workflow; CXone performs the transfer. Photo:

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.

Code

The Function returns the hand-off trace. Download handoff.mjs and save it beside your authoring files:

Hand-off signal

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

Prepare Function request
Create the Function

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

Create and attach the Workflow

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:

Use the CXone script’s Reqagent action 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 and Textbot Exchange branches.

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.

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 the tested Environment before the CXone adapter creates runtime sessions. Photo:

Code

Test the Draft using conversation tests, then publish the test Environment. Runtime session creation uses its Published version; compiling Draft alone does not publish it.

Publish the 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 with your CXone administrator. The adapter’s automated checks use mocked runtime responses; they do not establish a successful call in your NICE tenant.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.