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

# Cisco Webex Contact Center integration

> Connect Voiceflow AI agents to Cisco Webex Contact Center call flows, human support queues and Agent Desktop.

## Overview

Voiceflow integrates with **Cisco Webex Contact Center** so you can answer selected calls with an AI agent, transfer callers to your contact-center team and give staff an on-demand assistant. Keep your existing Webex number and queues; choose which calls reach Voiceflow in Flow Designer.

The phone route uses a Voiceflow phone number and a separate Webex number for human support. Agent assist uses an authenticated application embedded in Agent Desktop. These are separate connections: a phone transfer does not install the assistant or copy Webex contact variables into Voiceflow.

### Examples of when to use Webex Contact Center

- **[Answer inbound calls](#routing-calls)** — send a selected menu branch to a Voiceflow voice agent while retaining your public number.
- **[Human agent hand-off](#human-agent-hand-off)** — transfer callers to a Webex entry point that reaches a staffed queue.
- **[Add agent assist](#agent-assist)** — let staff request policy guidance and reply drafts in Agent Desktop.
- **[Test the complete journey](#testing-and-launch)** — verify speech, transfer failures and the human destination before changing public routing.

### What you need

- A Webex administrator who can edit and publish flows, assign a test entry point and configure its telephone number and queue.
- A Voiceflow **phone agent**, an editable test [Environment](/docs/documentation/deploy/environments/overview) and a connected [phone number](/docs/documentation/deploy/phone/connect-a-phone-number).
- A **different Webex number** for the human route. It must bypass the AI branch and reach the receiving 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` for the examples. 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 Webex administration.

### Phone routing and Bring Your Own Virtual Agent

Choose the connection contract before configuring a Webex virtual-agent activity.

This manual uses Webex telephone transfers. **Bring Your Own Virtual Agent (BYOVA)** is a different Webex media contract, with its own service application, authentication and gRPC or WebSocket gateway. Webex's protocol is not Voiceflow's Socket.IO voice protocol. Do not paste a Voiceflow runtime URL into a BYOVA connection or treat the two as interchangeable. A BYOVA route needs a separately implemented and tested media adapter; see [Webex BYOVA](https://developer.webex.com/webex-contact-center/docs/bring-your-own-virtual-agent).

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

## Preparing your voice agent

Resolve the supported customer requests before transferring callers to Webex 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 Webex 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 Webex 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 Webex number and send a selected call-flow branch to the AI agent.

### Assign the Voiceflow destination

Use a dedicated test line first. Your Webex administrator needs its full E.164 number and a reachable human fallback before changing Flow Designer.

#### 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 Webex AI entry line — Use this Voiceflow line as the external destination of the Webex 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 Webex.

Voiceflow phone-line assignment selecting Main Draft for an isolated Webex 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 Webex 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 Webex 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 Webex administrator. The Webex flow changes below use Webex administration, not the Voiceflow credential.

### Configure the Webex flow

Have your Webex administrator copy the inbound flow and assign the copy to an isolated test entry point and number. Keep the previous flow assignment for rollback. Choose one of these [Flow Designer transfer activities](https://help.webex.com/article/nhovcy4):

#### Blind transfer

### 1. Add the external transfer

In the selected AI branch, add **Blind Transfer**. Set **Transfer Dial Number → Specific Dial Number** to the tested Voiceflow number. Keep the human branch separate.

### 2. Handle rejected transfers

Wire the activity's **Undefined Error** handling to an announcement and the existing human route. Validate and publish the copied flow, then call the Webex test number. Confirm the intended branch reaches Voiceflow.

Blind Transfer hands the call to the external number; it is not a resumable AI activity. Use the separate Webex return number in **Human agent hand-off** for callers who ask for a person.

#### Bridged transfer

Use **Bridged Transfer** only when you want Webex to retain the call and resume its flow after the external party disconnects. It requires Webex's Next Generation voice media platform with a supported VPOP or Webex Calling setup.

### 1. Place the activity before queueing

Add **Bridged Transfer** before the contact is parked, queued or assigned. Set **Transfer Dial Number → Specific Dial Number** to the Voiceflow line and configure the answer timeout for your route.

### 2. Define continuation and failure routes

Connect the normal continuation and the activity's failure handling deliberately. Webex resumes when the external party disconnects; this is not a Voiceflow human-hand-off signal. Test a normal completion, caller hang-up and failed external destination before publishing the test flow.

Webex does not support this activity in outbound or event flows. Do not combine it with the blind-transfer human-return recipe without testing the resulting call legs. For the AI-to-human journey documented here, start with **Blind transfer**.

### Preserve the routing boundary

- **Contact variables:** Blind Transfer does not pass Webex flow variables to Voiceflow. Do not expect a Webex task ID, case reference or transcript to appear in the AI session.
- **Caller identity:** caller ID is not proof of identity. Authenticate account-specific actions through your own backend.
- **SIP:** Webex's custom transfer headers require its supported Local Gateway configuration. A telephone-number route does not establish a SIP trunk or a Voiceflow variable mapping. Use the [Telephony documentation](/docs/guides/integrations/phone-messaging) for an independently verified SIP design.

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

## Human agent hand-off

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

### Prepare the Webex return route

Have the Webex administrator configure a different dialed number and entry point. Its published flow must route directly through **Queue Contact** to the intended staffed queue, bypassing the AI branch. Verify staffing and closed-hours behavior with the receiving team before enabling Voiceflow transfers.

### Configure Call forward

#### 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 Webex 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 Webex human-support number — Forward to the human-only Webex entry point, never to the public number's AI branch.

### 3. Test with an answered call

Call through the Webex 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 Webex 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": "+14165550145",
    "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 Webex. A successful PATCH or CLI exit does not prove the receiving queue answered.

### Understand what crosses the transfer

- **Queue selection:** Webex's receiving flow chooses the queue. Call forward dials a phone number, not a Webex queue ID.
- **Customer context:** this phone transfer does not deliver an automatic summary, transcript or Webex contact 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 Webex Agent Desktop 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-team desktop layout 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 Agent Desktop 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 Webex 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`.

### Add the application to Agent Desktop

### 1. Deploy the authenticated application

Host the staff application on HTTPS. Set its Content Security Policy `frame-ancestors` to the exact approved Webex Desktop origin for your region. Verify that sign-in works inside the iframe; a working standalone URL is insufficient. Webex's [custom-widget guide](https://developer.webex.com/webex-contact-center/docs/desktop-custom-widgets) describes its iframe hosting requirements.

### 2. Add a test-team navigation widget

Have the Webex administrator download the current default Desktop Layout JSON and preserve its existing navigation. Add the [Voiceflow navigation entry](/docs/examples/webex-contact-center/desktop-navigation.json) to `agent.area.navigation`, replacing the sample URL with your application's HTTPS URL. The fragment uses Webex's `agentx-wc-iframe` widget; it is not a complete replacement layout.

### 3. Assign and verify the layout

Create a test desktop layout in **Control Hub → Services → Contact Center → Desktop Experience → Desktop Layouts**, upload the modified JSON and assign the test team. See [Manage desktop layouts](https://help.webex.com/article/60x9ji). Sign in as a member of that team, open **Voiceflow assist**, choose an authorized test case and request guidance. Confirm the suggestion stays staff-only.

### Keep contact access explicit

This iframe recipe uses the application's own case picker. It does not access Webex's Desktop SDK or automatically receive the active task. If you build a Web Component instead, use Webex's [Desktop SDK](https://developer.webex.com/webex-contact-center/docs/desktop-sdk-getting-started) and server-side authorization for the selected interaction; do not scrape Desktop's DOM or trust browser-supplied contact data.

Test an allowed case, a forbidden case, no selection, sign-out and a changed case during streaming. Denied access must return no suggestion. Closing the case or switching selection must cancel and clear the previous answer.

<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 Webex 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 Webex 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 Webex entry point, a teammate answers and both parties can hear each other. Confirm no route loops back to the AI branch.
- **Unavailable destination:** exercise the Webex transfer's error route and the human queue's closed-hours handling separately.
- **Caller exit:** hang up during the AI conversation; verify the telephone leg ends. If using Bridged Transfer, check its Webex continuation as a separate route.
- **Agent assist:** confirm sign-in, allowed/denied case access and clearing a pending answer when changing case inside the actual Desktop 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":"Webex 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 'Webex 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 assigning the approved Webex flow to a public entry point. Retain the previous Webex flow 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.
