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

# RingCentral RingCX integration

> Connect Voiceflow AI agents to RingCentral RingCX call routing, human support queues and staff-assistance scripts.

## Overview

Voiceflow integrates with **RingCentral RingCX** to answer selected customer calls with an AI agent, transfer callers to your contact-center team and give staff an on-demand assistant. Keep your existing public number and queues; choose the calls that reach Voiceflow in RingCX Workflow Studio.

The telephone route uses a Voiceflow phone number and a separate RingCX number for human support. Staff assistance uses an authenticated application embedded in a RingCX agent script. These are separate connections: routing a call does not install the assistant or copy RingCX interaction data into Voiceflow.

### Examples of when to use RingCX

- **[Answer inbound calls](#routing-calls)** — send a selected IVR branch to Voiceflow for order updates or policy questions.
- **[Human agent hand-off](#human-agent-hand-off)** — return callers to a RingCX workflow that routes directly to the right staffed queue.
- **[Add agent assist](#agent-assist)** — let staff request policy guidance and reply drafts inside their agent script.
- **[Test the complete journey](#testing-and-launch)** — check two-way speech, rejected transfers and the receiving queue before changing public routing.

### What you need

- A **RingCX** administrator who can edit Workflows, configure test numbers and assign agent scripts. RingCX is the contact-center product; RingEX answering rules and call queues use a different contract.
- A Voiceflow **phone project**, an editable test [Environment](/docs/documentation/deploy/environments/overview) and a connected [phone number](/docs/documentation/deploy/phone/connect-a-phone-number).
- A **different RingCX number** for human support. It must bypass the AI branch and reach the receiving voice queue.
- For Code, a server-side [personal or service key](/docs/api-reference/authentication), project ID, test Environment alias, cURL, jq and the current [Voiceflow CLI](/docs/cli/install) with Agent v2 support. Set `PROJECT_ID`, `ENVIRONMENT_ALIAS` and `VF_TOKEN`. Configure the CLI with that same token using [CLI authentication](/docs/api-reference/authentication#cli), or pass `--token "$VF_TOKEN"` to its commands. Voiceflow credentials do not authorize RingCX administration.

### Telephone routing and RingCX SIP IVA

Choose the transport contract before configuring an IVA node.

This manual's call recipe uses a RingCX **Route → PSTN** destination. RingCX's [SIP IVA interface](https://developers.ringcentral.com/engage/voice/guide/bots) is a separate contract: it exchanges context and final results through SIP INFO as well as carrying audio. The IVA node's Success and Failed paths depend on that contract. A Voiceflow phone number or Socket.IO voice URL does not implement it. Use the telephone recipe below; a direct IVA connection requires a separately verified signaling adapter. Generic [SIP setup](/docs/guides/integrations/phone-messaging) does not establish RingCX IVA interoperability.

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

## Preparing your voice agent

Resolve the supported customer requests before transferring callers to RingCX staff.

### Configure the conversation

Use short spoken replies, ask one question at a time and state when the agent should bring in a person. Attach the [Playbooks](/docs/documentation/build/playbooks), Knowledge and tools needed for the requests you actually support. Connecting a RingCX number does not import company policies or create business-system tools.

#### Studio

### 1. Prepare the phone agent

Open the project in [Agent studio](https://creator.voiceflow.com), select the test Environment, then open **Agent → Instructions**. Define the support tasks, approved policy sources and transfer conditions. Attach the relevant Playbooks and tools, then insert their resource references in the instructions.

Voiceflow phone agent with delivery and returns Playbooks, order lookup and structured Instructions — Connect the agent's instructions to the Playbooks, Knowledge and tools that resolve the caller's request.

The example retailer uses its own order lookup service. It is not a RingCX customer-record API.

### 2. Check speech and escalation

Configure the agent's [Voice settings](/docs/documentation/build/voice). Test a policy question, an order question and a request for a person. Configure the actual transfer destination in **Human agent hand-off** below before testing a phone transfer. Run the agent after edits to compile its Draft before calling the connected line.

#### Developer

Start with an existing phone project and attached Playbooks/tools. Save your Instructions as `agent.json`; use the names of resources already attached to that agent. These fields leave its existing resource registries and Voice settings unchanged:

```json title="agent.json"
{
  "instructions": "Help callers with delivery and returns using the attached Playbooks, approved Knowledge and order lookup tool. Ask one question at a time and keep replies short enough to speak. Confirm the order reference before looking it up. When the caller asks for a person or needs an action outside your supported tasks, use Call forward. Never claim the transfer has succeeded before the call is forwarded.",
  "buttonTool": null,
  "cardTool": null,
  "carouselTool": null
}
```

#### API

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

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

#### CLI

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

vf environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS"
```

Read the agent back with [Get agent](/docs/api-reference/agent/get-agent). Confirm the intended Instructions and tools remain configured. Compile the Draft after edits using **Testing and launch** below; a saved configuration is not yet proof of a working telephone conversation.

<a id="routing-calls"></a>

## Routing calls to Voiceflow

Keep your RingCX number and send a selected call-flow branch to the AI agent.

### Assign the Voiceflow destination

Use a dedicated test line first. Your RingCX administrator needs its full E.164 number and a reachable human fallback before changing Workflow Studio.

#### Studio

### 1. Find the AI entry number

In **Agent studio**, open your phone agent's project. In the left sidebar, open **Phone numbers** and find the connected test line. Copy its full number, including the country code.

Voiceflow Phone numbers navigation and the RingCX AI entry line — Use this Voiceflow line as the external destination of the RingCX test branch.

### 2. Select the test version

Open the line's Environment assignment, choose the test Environment and **Draft**, then save. Call this number directly and confirm the intended agent answers before testing through RingCX.

Voiceflow phone-line assignment selecting Main Draft for an isolated RingCX test project — Match the line's Environment and version to the agent you are testing.

#### Developer

Use a personal or service key with access to this workspace and phone project. Set `WORKSPACE_ID` to the workspace containing the connected line. Obtain it through [Workspaces](/docs/cli/commands/workspace/list), and keep `PROJECT_ID` and `ENVIRONMENT_ALIAS` from the agent configuration above. The key needs `vf.phone-number:LIST` and `vf.phone-number:READ` for the workspace, plus `vf.phone-number:ASSIGN` on the target Environment. The number and project must belong to the same workspace.

#### API

### 1. Find the connected line

```bash title="List the workspace's phone lines"
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/phone-number?workspaceID=$WORKSPACE_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Select the dedicated test line from `phoneNumbers`. Set `PHONE_NUMBER_ID` to its `id`, not its E.164 `value`. Keep `value` for the RingCX administrator and retain its current `voice` assignment for rollback.

### 2. Pin the voice side to the test Draft

```bash title="Create assignment.json and assign the line"
jq -n --arg project "$PROJECT_ID" --arg environment "$ENVIRONMENT_ALIAS" \
  '{target:"voice",projectID:$project,environmentAlias:$environment,version:"draft"}' \
  > assignment.json

curl --fail-with-body --request PUT \
  "https://realtime-api.voiceflow.com/v1/stable/phone-number/$PHONE_NUMBER_ID/assign?workspaceID=$WORKSPACE_ID" \
  --header "Authorization: Bearer $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @assignment.json

curl --fail-with-body \
  "https://realtime-api.voiceflow.com/v1/stable/phone-number/$PHONE_NUMBER_ID?workspaceID=$WORKSPACE_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Verify `phoneNumber.voice.projectID`, `environmentAlias` and `version` are the intended project, test alias and `draft`. Assignment changes the voice side only; it leaves SMS routing unchanged.

#### CLI

### 1. Find the connected line

```bash title="List the workspace's phone lines"
vf phone-number list --workspace-id "$WORKSPACE_ID" --output-format json
```

Select the dedicated test line from `phoneNumbers`. Set `PHONE_NUMBER_ID` to its `id`, not its E.164 `value`. Keep `value` for the RingCX administrator and retain its current `voice` assignment for rollback.

### 2. Assign and inspect the voice side

```bash title="Assign the test Draft and inspect the result"
vf phone-number assign --workspace-id "$WORKSPACE_ID" \
  --phone-number-id "$PHONE_NUMBER_ID" --project-id "$PROJECT_ID" \
  --target voice --environment-alias "$ENVIRONMENT_ALIAS" --version-param draft

vf phone-number get --workspace-id "$WORKSPACE_ID" \
  --phone-number-id "$PHONE_NUMBER_ID" --output-format json
```

Confirm `phoneNumber.voice` names the intended project, test alias and `draft`. The `--version-param` flag selects Draft/Published; it is not a CLI version flag. Only voice routing changes.

Compile the Draft after agent edits, then call the Voiceflow number directly. Confirm the expected greeting and two-way speech before giving the number to the RingCX administrator. The RingCX flow changes below use RingCX administration, not the Voiceflow credential.

### Route the RingCX workflow to Voiceflow

Use an isolated RingCX test number and workflow. Preserve the previous number-to-workflow assignment before editing. In [RingCX Admin](https://ringcx.ringcentral.com), open **Categorization → Workflows**, expand the workflow group, select the test workflow and open **Workflow Studio**.

#### Phone number

### 1. Add the external phone route

On the AI branch, drag a **Route** node onto the canvas. Hover over it and select **Edit**. Give it a recognizable **Node ID**, select **Type → PSTN** and set **Destination** to the tested Voiceflow phone number. This is the AI entry number, not the human-support return number.

### 2. Set transfer behavior

Choose the **Caller ID** behavior, **Ring Duration** and any required hold audio. Leave **TT Accept** off for this automated destination: it requires the answering party to press a key before accepting the call. Select **OK** and connect the intended branch to the Route node.

### 3. Verify the test number

Save the workflow changes and confirm that the isolated test number reaches this workflow. Call it, choose the AI branch and check two-way speech with Voiceflow. Exercise the RingCX route's unsuccessful-transfer handling before changing the public number's routing. Follow RingCX's [Route node configuration](https://support.ringcentral.com/article-v2/Using-the-Route-node-in-the-RingCX-IVR-Studio.html?brand=RingCentral&product=RingCX&language=en_US) for the destination and transfer controls.

#### Cloud Routing profile

Use this alternative when the selected RingCX workflow uses a **Cloud Profile** instead of a direct PSTN destination. It configures future routing; it does not transfer an active call. Keep the pilot profile isolated from public numbers and live branches.

#### Studio

### 1. Create the AI phone destination

In **RingCX Admin → Categorization → Cloud destinations**, hover over the pilot routing group and choose **New destination**. Name it, choose **Route Destination Type → DID**, set **Country → United States** for a US Voiceflow line and enter its ten-digit **Destination**; for `+14155550142`, enter `4155550142`. Use the actual country's number rules for other lines. Keep **TT Accept** off: Voiceflow will not press a key to accept a call.

### 2. Make the pilot destination eligible

Set the destination's **Active**, **Start**, **End** and **Business Hours** so the test call falls within its allowed schedule. Configure **Ring Duration** and save. Follow [RingCX Cloud destinations](https://support.ringcentral.com/article-v2/Configuring-cloud-destinations-in-RingCX.html?brand=RingCentral&product=RingCX&language=en_US) for these fields.

### 3. Assign the destination to the test profile

Open **Categorization → Cloud profiles**, select the isolated test profile and open **Assigned Destination → Add Assigned Destination**. Select the AI phone destination and set its rank and allocation for the selected routing policy. Confirm the profile and destination are active, the allocation is valid and any assignment overrides preserve automatic call acceptance. See [RingCX Cloud Profiles](https://support.ringcentral.com/article-v2/Configuring-cloud-profiles-in-RingCX.html?brand=RingCentral&product=RingCX&language=en_US).

### 4. Connect only the test branch

In Workflow Studio, choose **Route → Type → Cloud Profile** and select this profile. Call the test number and verify the Voiceflow agent answers before changing production routing.

#### Developer

Use this alternative when the selected RingCX workflow already routes to a **Cloud Profile**. It configures future routing; it does not transfer an active call. The RingCX administrator must provide a test profile and confirm its routing policy, current destinations and rollback settings. Do not add the pilot destination to a live profile.

### 1. Obtain the RingCX token and account IDs

Use a linked RingCentral login and an application with **Read Accounts**, plus the RingCX user's routing permissions. Obtain the RingCentral access token with the app's configured OAuth flow and set `RC_ACCESS_TOKEN` to that value, then exchange it for a **RingCX** access token. See [RingCX authentication](https://developers.ringcentral.com/engage/voice/guide/authentication/auth-ringcentral).

```bash title="Exchange the RingCentral token"
umask 077
curl --fail-with-body --silent --show-error --request POST \
  'https://ringcx.ringcentral.com/api/auth/login/rc/accesstoken?includeRefresh=true' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "rcAccessToken=$RC_ACCESS_TOKEN" \
  --data-urlencode 'rcTokenType=Bearer' > ringcx-auth.json

RINGCX_TOKEN=$(jq -er '.accessToken' ringcx-auth.json)
curl --fail-with-body --silent --show-error \
  'https://ringcx.ringcentral.com/voice/api/v1/admin/accounts' \
  --header "Authorization: Bearer $RINGCX_TOKEN"
```

Keep `ringcx-auth.json` in a private temporary directory and remove it after securely storing the credentials. Select the RingCX **sub-account** `accountId`, not the RingCentral account UID. Set `RINGCX_ACCOUNT_ID`. Tokens expire; use the provider's refresh flow when needed, without repeating writes whose outcome is uncertain.

### 2. Locate the test routing resources

Set `RINGCX_BASE` to the account-scoped API URL. List destination groups, then use the administrator's profile-group ID to list its profiles:

```bash title="Inspect destination groups and profiles"
RINGCX_BASE="https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/$RINGCX_ACCOUNT_ID"
curl --fail-with-body "$RINGCX_BASE/cloudRouteDestinationGroups" \
  --header "Authorization: Bearer $RINGCX_TOKEN"

curl --fail-with-body \
  "$RINGCX_BASE/cloudRouteProfileGroups/$RINGCX_PROFILE_GROUP_ID/cloudRouteProfiles" \
  --header "Authorization: Bearer $RINGCX_TOKEN"
```

Set `RINGCX_DESTINATION_GROUP_ID` from the selected destination group's `cloudGroupId` and `RINGCX_PROFILE_ID` from the test profile's `cloudProfileId`. Keep its profile-group ID separate. Confirm the profile routes only the pilot branch. The [Cloud Routing contract](https://developers.ringcentral.com/engage/voice/guide/routing/cloud-routing) describes its ranking, allocation and activation settings.

### 3. Create and assign the AI phone destination

Set `VF_PHONE_DIGITS` to the connected Voiceflow number in the dialable digits format required by RingCX, for example `14155550142`. This is the phone number's value, not its Voiceflow resource ID. The example uses an isolated percent-allocation profile with one destination; do not replace an existing production allocation.

```bash title="Add the Voiceflow destination to the test profile"
jq -n --arg number "$VF_PHONE_DIGITS" \
  '{destinationName:"Voiceflow phone pilot",destinationDesc:"Isolated AI entry",destinationType:"DID",routeDestination:$number,ringDuration:20,isActive:true,ttAccept:false}' \
  > ringcx-destination.json

curl --fail-with-body --silent --show-error --request POST \
  "$RINGCX_BASE/cloudRouteDestinationGroups/$RINGCX_DESTINATION_GROUP_ID/cloudRouteDestinations" \
  --header "Authorization: Bearer $RINGCX_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @ringcx-destination.json > ringcx-destination-response.json

RINGCX_DESTINATION_ID=$(jq -er '.cloudDestinationId' ringcx-destination-response.json)
jq -n --argjson destination "$RINGCX_DESTINATION_ID" \
  '{cloudDestination:{cloudDestinationId:$destination},destinationType:"STANDARD",rank:1,allocationPercent:100,ringDuration:20,ttAccept:false}' \
  > ringcx-assignment.json

curl --fail-with-body --request POST \
  "$RINGCX_BASE/cloudRouteProfileGroups/$RINGCX_PROFILE_GROUP_ID/cloudRouteProfiles/$RINGCX_PROFILE_ID/assignedDestinations" \
  --header "Authorization: Bearer $RINGCX_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @ringcx-assignment.json

curl --fail-with-body \
  "$RINGCX_BASE/cloudRouteProfileGroups/$RINGCX_PROFILE_GROUP_ID/cloudRouteProfiles/$RINGCX_PROFILE_ID/assignedDestinations" \
  --header "Authorization: Bearer $RINGCX_TOKEN"
```

Confirm the returned assignment points to the created destination, and that the test profile is active with the intended allocation. In Workflow Studio, select **Route → Type → Cloud Profile** and choose that test profile. Call the test number and confirm the AI branch reaches Voiceflow. A successful configuration response alone does not prove a working call. If a destination-creation request times out, list the group's `cloudRouteDestinations` before creating another. If an assignment request times out, read `assignedDestinations` before retrying it.

### Keep customer context explicit

- **Interaction data:** this PSTN transfer does not map RingCX workflow variables, a case ID or a transcript into the Voiceflow session.
- **Identity:** a caller number is not authentication. Verify account-specific requests through your own trusted service before returning protected data.
- **Continuation:** this is an external phone route, not a resumable IVA node. Use the dedicated RingCX return number for human hand-off.

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

## Human agent hand-off

Transfer callers to a separate RingCX number that reaches a staffed queue.

### Prepare the RingCX return route

Give human support its own RingCX number and workflow. In **Admin → Categorization → Workflows → Workflow Studio**, configure a **Route** node with **Type → Voice queue** and select the receiving queue. Confirm that the human number reaches this workflow directly and never runs the AI route. Verify staffing and closed-hours handling with the receiving team.

### Configure Call forward

Use **Call forward** when the caller requests a person or needs an action outside the AI agent's supported tasks. Set the destination to the dedicated RingCX human-support number, not the public number that routes to AI.

#### Studio

### 1. Open the phone agent's transfer tool

In **Agent studio**, select the test Environment and open **Agent → Call forward**. Enable the tool and choose **Phone number**.

### 2. Set the human destination

Enter the dedicated RingCX return number with its country code. Describe the requests that require a person, then close the editor to return to the agent.

Voiceflow Call forward configured with the separate RingCX human-support number — Forward to the human-only RingCX number, never to the public number's AI branch.

### 3. Test with an answered call

Call through the RingCX test entry, ask the AI for a person and have a teammate answer the queue. Confirm two-way audio and that the AI stops speaking. Use a connected telephone line: prototype test calls cannot forward.

#### Developer

Save this configuration as `transfer.json`, replacing the illustrative number with your actual human-only RingCX number. Updating the tool replaces its settings; preserve existing extension, message or caller-ID options if you use them.

```json title="transfer.json"
{
  "callForwardTool": {
    "enabled": true,
    "addressType": "phone",
    "address": "+14155550145",
    "description": "Transfer when the caller asks for a person or needs an account action outside the AI agent's supported tasks.",
    "messages": null,
    "toolSound": null
  }
}
```

#### API

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

#### CLI

```bash title="Set the human destination"
vf agent update --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" < transfer.json
```

Read the agent back, confirm the return number, compile the test Draft and place a real call through RingCX. A successful PATCH or CLI exit does not prove the receiving queue answered.

### Understand what crosses the transfer

Test by calling through the RingCX test number and asking the AI for a person. Have a teammate answer the human queue; confirm two-way audio and that the AI stops speaking.

- **Queue selection:** RingCX's receiving flow chooses the queue. Call forward dials a phone number, not a RingCX queue ID.
- **Customer context:** this phone transfer does not deliver an automatic summary, transcript or RingCX interaction variables. Have the human confirm the case reference, or implement a separately authorized business-system context exchange.
- **Failures:** a rejected forward can end the call; this path does not expose an automatic Voiceflow busy/no-answer recovery branch. Test the destination's closed-hours and unavailable-agent behavior.

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

## Adding agent assist

Embed a staff-only assistant in a RingCX agent script for policy guidance and reply drafts.

This is an on-demand assistant, separate from the caller's phone session. Staff ask a question and review the suggestion before speaking or sending it to the customer. The recipe does not listen to calls, transcribe audio or send customer replies automatically.

### Prepare the staff assistant

#### Studio

Open a separate staff-assistant project in **Agent studio → Agent → Instructions**. Tell it to answer the staff member, use approved Knowledge and label suggested customer replies. Keep the assistant read-only; the application below does not propagate staff permissions into agent tool calls.

Staff assistant Instructions for policy guidance and reviewed customer reply drafts — Keep suggestions staff-facing and require human review before replying to the customer.

Publish to a dedicated test Environment. Give your integration developer the project ID and Environment alias, and provision a server credential through your team's secret-management process. Obtain the authenticated application URL and test-queue script assignment before continuing below.

#### Developer

Use a ready read-only staff assistant and its **Published** test Environment. Download [assist.mjs](/docs/examples/contact-center-assist/assist.mjs) and [client.mjs](/docs/examples/contact-center-assist/client.mjs). Mount the handler as a same-origin `POST /api/agent-assist` route in your Node.js 22+ staff application:

```js title="Authorize the staff member and selected case"
import { createAssistHandler } from './assist.mjs';

export const POST = createAssistHandler({
  projectID: process.env.VF_ASSIST_PROJECT_ID,
  environmentAlias: process.env.VF_ASSIST_ENVIRONMENT_ALIAS,
  apiKey: process.env.VF_ASSIST_API_KEY,
  requireStaff,
  loadCaseForStaff,
});
```

Implement `requireStaff(request)` with the application's verified staff session. Implement `loadCaseForStaff(staff, caseId)` against your trusted case service: return `{id: caseId, context: approvedText}` only if that staff member can read the case; otherwise return `null`. Set the allowed fields on the server. Opening a RingCX agent script or receiving a case ID from an iframe is not authorization. Apply your host's CSRF protection for cookie sessions.

The handler starts an isolated Voiceflow session, sends `launch`, then streams the staff question with the authorized context. Voiceflow credentials and runtime session keys stay on the server. Build a case picker from the staff member's authorized cases; a RingCX telephone transfer does not populate it automatically.

```js title="Request a suggestion from the embedded application"
import { askAssist } from './client.mjs';

let pending;
const clear = () => {
  pending?.abort();
  pending = undefined;
  output.textContent = '';
};
casePicker.addEventListener('change', clear);
window.addEventListener('pagehide', clear);
askButton.onclick = async () => {
  clear();
  const caseId = casePicker.value;
  if (!caseId) return;
  const active = pending = new AbortController();
  try {
    for await (const text of askAssist({
      caseId, question: questionInput.value, signal: active.signal,
    })) {
      if (pending === active && casePicker.value === caseId) output.textContent += text;
    }
  } catch {
    if (pending === active && !active.signal.aborted) {
      output.textContent = 'Assistance unavailable. Try again.';
    }
  }
};
```

`casePicker`, `questionInput`, `askButton` and `output` are elements in your application's UI. Populate the picker through an authenticated case-list endpoint; reauthorize each request in the handler. Clear its selection and any pending answer when staff finish or change the case. Render suggestions with `textContent`, not `innerHTML`.

### Embed the application in an agent script

### 1. Deploy the staff-only application

Host the authenticated staff application on HTTPS. Allow the exact approved RingCX agent origin in its Content Security Policy `frame-ancestors`, and verify that sign-in works inside the iframe. Keep Voiceflow and business-system credentials on the server. Obtain the HTTPS application URL from your integration developer before editing the script.

### 2. Add the iframe to Script Studio

In **RingCX Admin → Agent Tools → Script designer**, create or select a test script group and script. Open **Script Studio**, add a **Page** tool and connect it to the script's entry path. Edit the Page, select **Add Element → iFrame**, then open the element's settings. Set its URL to your authenticated application's address and size the element for the assistant. Preserve the URL field's existing `https://` prefix rather than adding the scheme twice. See RingCX's [Page tool elements](https://support.ringcentral.com/article-v2/Intro-to-the-RingCX-Script-Studio-Page-tool-and-its-elements.html?brand=RingCentral&product=RingCX&language=en_US) and [iframe example](https://developers.ringcentral.com/engage/voice/guide/users/agents/agent-script).

### 3. Assign and test the script

Use **Render** to check the script, then **Save** it and enable **Active** in the script's general settings. Open its **Queue Assignments** or **Campaign Assignments** tab and select the pilot queue/campaign. In the opened configuration, set **Agent Settings → Integrated Script** to this script and save; return to the assignment tab and save again. See RingCX's [script assignment procedure](https://support.ringcentral.com/article-v2/Assigning-a-script-to-a-queue-or-campaign.html?brand=RingCentral&product=RingCX&language=en_US). Take a test interaction as an assigned staff member, open the assistant, sign in, select an authorized case and request guidance. A script opened only from the Scripts study area is not an active-interaction test.

### Keep case access separate from the script

The recipe uses the application's own case picker. It does not derive an authorized case from RingCX's ANI or script model. If you add interaction-based selection, have your server verify staff access to the selected case; a browser-supplied phone number or ID is insufficient.

Test an allowed case, a forbidden case, no selection, sign-out and a changed case during streaming. Denied access must return no suggestion. Switching cases must cancel and clear the previous answer. The assistant provides on-demand text suggestions; it does not consume RingCX's gRPC live-audio stream or send replies to the customer automatically.

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

## Testing and launching

Prove the telephone and staff-assistance paths before routing customer traffic.

### Compile and call the test Draft

#### Studio

After changing the agent, run a test from **Agent → Run**. Keep the isolated phone line assigned to the test Environment's **Draft**, then place a real call through the RingCX test number. Studio's test conversation alone cannot verify external telephone routing.

#### Developer

Compile after agent or tool edits. The line assigned earlier must target this same Environment's Draft:

#### API

```bash title="Compile the test Draft"
curl --fail-with-body --request PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT_ALIAS/compile?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```bash title="Compile the test Draft"
vf environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS"
```

Confirm the compile succeeds, then call the RingCX test number. This is the phone path; creating a text runtime session is not an equivalent test.

### Exercise the complete journey

- **Self-service:** a policy question and a real test-order question reach the intended Playbook and produce spoken replies.
- **Human agent hand-off:** a request for a person reaches the human-only RingCX number, a teammate answers and both parties can hear each other. Confirm no route loops back to the AI branch.
- **Unavailable destination:** exercise the RingCX route's unsuccessful-transfer handling and the human queue's closed-hours handling separately.
- **Caller exit:** hang up during the AI conversation; verify the telephone leg ends. Check that the external destination does not leave a connected call leg behind.
- **Agent assist:** confirm sign-in, allowed/denied case access and clearing a pending answer when changing case inside the actual RingCX script iframe.

### Publish and retain rollback

#### Studio

In the test Environment, choose **Publish**, enter a release name and publish the tested configuration. Open **Phone numbers**, select the connected line's Environment assignment, change **Draft** to **Published** and save. Keep the intended Environment selected.

#### Developer

Publish only after the Draft telephone checks pass. This creates a release and updates that Environment's Published version:

#### API

```bash title="Publish the tested Environment"
curl --fail-with-body --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT_ALIAS/publish?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN" --header 'Content-Type: application/json' \
  --data '{"name":"RingCX phone pilot","description":"Verified AI entry and human return route."}'

jq '.version = "published"' assignment.json | \
  curl --fail-with-body --request PUT \
    "https://realtime-api.voiceflow.com/v1/stable/phone-number/$PHONE_NUMBER_ID/assign?workspaceID=$WORKSPACE_ID" \
    --header "Authorization: Bearer $VF_TOKEN" --header 'Content-Type: application/json' \
    --data-binary @-
```

#### CLI

```bash title="Publish the tested Environment"
vf environment publish --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" --name 'RingCX phone pilot' \
  --description '"Verified AI entry and human return route."'

vf phone-number assign --workspace-id "$WORKSPACE_ID" \
  --phone-number-id "$PHONE_NUMBER_ID" --project-id "$PROJECT_ID" \
  --target voice --environment-alias "$ENVIRONMENT_ALIAS" --version-param published
```

Check the returned release/Environment, then read the phone line back using the API or CLI **get** command above. Confirm `phoneNumber.voice.version` is `published` with the intended project and Environment alias. Publishing alone does not change a Draft line's assignment. The API procedure reuses `assignment.json` from **Routing calls to Voiceflow**.

Call the Published line again before changing the public RingCX number to the approved workflow. Retain the previous RingCX workflow assignment and the prior Voiceflow release so the administrator can restore routing if the live test fails.

Use the shared [Test and launch your integration](/docs/guides/integrations/contact-centers/test-connection) guide for the release handover.
