Local Audio Connector Configuration

The local audio connector lets you validate a Webex Contact Center BYOVA setup before choosing or provisioning a voice-agent provider. It uses audio files from this repository, so it does not require AWS credentials, a vendor account, speech recognition, or text-to-speech services.

This is a good first connector when you already have a Webex Contact Center sandbox and want to prove that the gateway, BYODS registration, virtual-agent discovery, Flow Designer configuration, audio playback, DTMF handling, and agent transfer path work together.

Functional example only: The local audio connector is a deterministic test fixture, not a conversational voice agent or a production implementation.

What the Connector Does

During a call, the connector follows this fixed behavior:

Caller action	Connector behavior
Call enters the Virtual Agent V2 activity	Plays `welcome.wav`
Caller speaks	Accepts the audio but does not interpret or answer it
Caller presses 5	Plays `transferring.wav` and sends an agent-transfer event
Caller presses 6	Plays `goodbye.wav` and sends a conversation-end event
Caller presses another key	Continues waiting for input without a response

The connector disables barge-in for its prerecorded prompts. It can optionally record caller audio for development diagnostics.

Prerequisites

For a local gateway smoke test, you need:

Python 3.8 or later
Git
This repository cloned locally

For an end-to-end sandbox call, you also need:

A Webex Contact Center sandbox or organization with BYOVA enabled
Contact Center administrator access
A Webex Service App authorized by the sandbox organization
A BYODS data-source registration using the BYOVA schema
A publicly reachable HTTPS endpoint that supports HTTP/2 gRPC and routes to gateway port 50051
A test entry point and a published flow containing a Virtual Agent V2 activity

The Webex-side prerequisites are the same for any vendor connector. The local connector simply removes the vendor-specific account and bot setup from the first test.

Configuration Options

Optional

agent_id: Display name for the local agent (default: Local Playback)
audio_base_path: Directory containing prompt files (default: audio)
audio_files: File names for the supported prompt roles
record_caller_audio: Save caller audio for diagnostics (default: false)
audio_recording.output_dir: Destination for caller recordings (default: logs)

The advertised virtual-agent ID includes the connector prefix. With the default configuration, Flow Designer discovers:

Local Audio: Local Playback

Use agent_id, not an agents list, to change the name.

Example Configuration

Add or update this entry under connectors in config/config.yaml:

connectors:
  local_audio_connector:
    type: "local_audio_connector"
    class: "LocalAudioConnector"
    module: "connectors.local_audio_connector"
    config:
      agent_id: "Local Playback"
      audio_base_path: "audio"
      record_caller_audio: false
      audio_files:
        welcome: "welcome.wav"
        transfer: "transferring.wav"
        goodbye: "goodbye.wav"
        error: "error.wav"
        default: "default_response.wav"

The current scripted call path actively plays the welcome, transfer, and goodbye files. The error and default mappings are available for extending the example but are not played during its normal DTMF-driven flow.

You can remove other connector entries while evaluating the local connector. This avoids unrelated vendor credential or discovery errors in the startup logs.

Audio Files

The repository includes working prompt files in audio/. To replace them:

Add each file below audio/, or below your configured audio_base_path.
Keep the files as mono PCM WAV audio. The bundled converter supports the sample rates used by the examples and converts them to the 8 kHz, 8-bit mu-law WAV output required by Webex Contact Center.
Update audio_files if you changed any file names.
Restart the gateway after changing the configuration.

Run the gateway from the repository root so a relative path such as audio resolves to the expected directory. A misspelled directory or file name can result in an empty prompt; check logs/gateway.log for File not found or audio conversion errors.

For more detail, see the Audio Files Guide.

Test the Connector Locally

This smoke test confirms that the gateway loads the connector and advertises the expected virtual-agent ID. It does not place a Contact Center call.

1. Set up the gateway

From the repository root:

python -m venv venv

# macOS or Linux
source venv/bin/activate

# Windows PowerShell
# venv\Scripts\Activate.ps1

pip install -r requirements.txt
python -m grpc_tools.protoc \
  -I./proto \
  --python_out=src/generated \
  --grpc_python_out=src/generated \
  proto/*.proto

2. Temporarily disable JWT validation

For a localhost-only smoke test, update config/config.yaml:

jwt_validation:
  enabled: false

Do not use this setting when Webex Contact Center connects to the gateway. The end-to-end path below requires JWT validation.

3. Start and verify the gateway

python main.py

In a second terminal, verify the health and loaded connector:

curl http://localhost:8080/health
curl http://localhost:8080/api/config

The configuration response should include local_audio_connector and the agent Local Audio: Local Playback (or your customized name). The monitoring dashboard is available at http://localhost:8080; dashboard login requires the Webex OAuth settings described in the Authentication Quick Start, but the two API checks above do not require dashboard login.

Connect the Sandbox End to End

Once the local smoke test passes, use the same Webex setup that a real voice-agent connector will use.

1. Expose the gRPC endpoint over HTTPS

Deploy the gateway behind a public endpoint with a valid TLS certificate and HTTP/2 gRPC routing to port 50051. Keep the monitoring interface on port 8080 protected separately; BYODS registers the gRPC endpoint, not the dashboard.

See Security Configuration for an AWS load-balancer example. The gateway is sample code, so review the deployment and security controls before exposing it.

2. Enable JWT validation

Set the public endpoint in config/config.yaml:

jwt_validation:
  enabled: true
  enforce_validation: true
  datasource_url: "https://byova-gateway.example.com"
  datasource_schema_uuid: "5397013b-7920-4ffc-807c-e8a3e0a18f43"
  cache_duration_minutes: 60

The datasource_url must exactly match the URL used in the BYODS registration, including scheme, hostname, path, and any explicitly supplied port. Restart the gateway after changing it.

3. Register the BYOVA data source

Follow the Webex Bring Your Own Virtual Agent and Bring Your Own Data Source guides to:

Confirm BYOVA is enabled for the sandbox organization.
Create a Service App with the required data-source scopes and add the gateway hostname as an allowed domain.
Have a sandbox administrator authorize the Service App.
Register a data source with the BYOVA schema UUID 5397013b-7920-4ffc-807c-e8a3e0a18f43 and the exact URL configured above.
Save the returned data-source ID.

No vendor credentials are needed for the local connector.

4. Create the Contact Center virtual-agent feature

In Control Hub:

Go to Contact Center > Integrations > Features.
Create a virtual-agent feature using the authorized Service App.
Use the data-source ID as the resource identifier.
Give it a recognizable name such as BYOVA Local Audio Test.

5. Configure and publish the flow

The repository includes BYOVA_Gateway_Flow.json as a starting point.

Import the file into Flow Designer, or add a Virtual Agent V2 activity to an existing test flow.
Open the Virtual Agent V2 activity and reselect the virtual-agent feature you created. Do not rely on the connector identifier stored in the sample flow.
Select Local Audio: Local Playback as the virtual-agent ID. If it is not listed, use the troubleshooting steps below before continuing.
Confirm the activity’s escalated branch routes to a test queue if you want to verify DTMF 5 transfer.
Validate, publish, and assign the flow to a sandbox test entry point.

6. Place a test call

Call the sandbox entry point and verify:

You hear the welcome prompt.
Speaking does not produce a reply; this is expected for the local connector.
Pressing 5 plays the transfer prompt and follows the activity’s escalated path. Have a test agent signed in and available if the path routes to a queue.
On a separate call, pressing 6 plays the goodbye prompt and follows the handled/conversation-end path.
The gateway dashboard, logs/gateway.log, or /api/connections shows the call lifecycle.

At this point you have validated the vendor-neutral BYOVA plumbing. When you pick a voice-agent provider, add its connector configuration, confirm its advertised agent ID, and update the Virtual Agent V2 selection; the Service App, data-source, public endpoint, and surrounding flow can usually remain in place if their URL and schema requirements do not change.

Optional Caller Audio Recording

To confirm that caller audio reaches the connector, enable development recording:

connectors:
  local_audio_connector:
    type: "local_audio_connector"
    class: "LocalAudioConnector"
    module: "connectors.local_audio_connector"
    config:
      agent_id: "Local Playback"
      audio_base_path: "audio"
      record_caller_audio: true
      audio_recording:
        output_dir: "logs/local_audio_recordings"

Recordings may contain customer audio and personal data. Use only test calls, restrict access to the output directory, define retention, and turn recording off when the diagnostic is complete.

Troubleshooting

Gateway fails with `datasource_url is not configured`

JWT validation is enabled without a URL. For a localhost-only smoke test, set jwt_validation.enabled to false. For a sandbox call, configure the exact public BYODS URL and leave validation enabled.

The local agent does not appear in Flow Designer

Confirm /api/config lists Local Audio: Local Playback.
Confirm the public gRPC endpoint is reachable over HTTP/2 and reports SERVING.
Confirm the Service App is authorized and the data source is active.
Confirm the data-source URL exactly matches jwt_validation.datasource_url.
Reopen or refresh the Virtual Agent V2 activity after fixing discovery.

The call connects but the welcome prompt is silent

Run the gateway from the repository root.
Confirm the configured file exists below audio_base_path.
Use a mono PCM WAV file.
Search logs/gateway.log for file or conversion errors.

Speech gets no response

This is expected. The local connector does not perform speech recognition or generate conversational responses. Use DTMF 5 and 6 to exercise its scripted branches.

DTMF 5 does not reach an agent

The connector only emits the transfer event. Flow Designer must route the Virtual Agent V2 activity’s escalated branch to a queue, and a test agent must be signed in and available to receive the call.

Next Step: Choose a Voice-Agent Connector

After the local end-to-end test passes, compare or implement connectors using the Connectors Overview. If you choose Amazon Lex, use the AWS Lex Connector Configuration guide for the vendor-specific setup.