{"id":41589885,"url":"https://github.com/webex/webex-byova-gateway-python","last_synced_at":"2026-01-24T09:12:28.577Z","repository":{"id":321298912,"uuid":"1032747400","full_name":"webex/webex-byova-gateway-python","owner":"webex","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-08T18:36:54.000Z","size":1192,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-09T11:35:51.818Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://webex.github.io/webex-byova-gateway-python/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.MD","dco":null,"cla":null}},"created_at":"2025-08-05T19:04:51.000Z","updated_at":"2025-12-08T18:36:59.000Z","dependencies_parsed_at":"2025-10-28T23:28:49.897Z","dependency_job_id":"d4ae89d4-3bc0-4ea4-b007-f865c228c82c","html_url":"https://github.com/webex/webex-byova-gateway-python","commit_stats":null,"previous_names":["webex/webex-byova-gateway-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/webex/webex-byova-gateway-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webex%2Fwebex-byova-gateway-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webex%2Fwebex-byova-gateway-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webex%2Fwebex-byova-gateway-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webex%2Fwebex-byova-gateway-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webex","download_url":"https://codeload.github.com/webex/webex-byova-gateway-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webex%2Fwebex-byova-gateway-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28722333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T08:27:05.734Z","status":"ssl_error","status_checked_at":"2026-01-24T08:27:01.197Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-24T09:12:28.017Z","updated_at":"2026-01-24T09:12:28.565Z","avatar_url":"https://github.com/webex.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Webex Contact Center BYOVA Gateway\n\n[![License: Cisco Sample Code](https://img.shields.io/badge/License-Cisco%20Sample%20Code-blue.svg)](LICENSE)\n\nA Python-based gateway for Webex Contact Center (WxCC) that provides virtual agent integration capabilities. This gateway acts as a bridge between WxCC and various virtual agent providers, enabling seamless voice interactions.\n\n## 📚 Documentation\n\n**Complete Setup Guide**: [BYOVA with AWS Lex Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex)\n\nThis comprehensive guide walks you through:\n- Setting up a Webex Contact Center sandbox\n- Configuring BYOVA and BYODS\n- Creating AWS Lex bots\n- Deploying and testing the gateway\n\n## Table of Contents\n\n- [Install](#install)\n- [Monitoring Dashboard](#monitoring-dashboard)\n- [Usage](#usage)\n- [API](#api)\n- [Security Configuration](docs/Security-Configuration.md)\n- [Maintainers](#maintainers)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Install\n\n### Prerequisites\n\n- Python 3.8 or higher\n- macOS, Linux, or Windows\n- Webex Contact Center environment for testing\n\n### Setup\n\n1. **Clone the Repository**\n   ```bash\n   git clone https://github.com/webex/webex-byova-gateway-python.git\n   cd webex-byova-gateway-python\n   ```\n\n2. **Create and Activate Virtual Environment**\n   ```bash\n   # Create virtual environment\n   python -m venv venv\n\n   # Activate virtual environment (REQUIRED before running any commands)\n   # On macOS/Linux:\n   source venv/bin/activate\n   # On Windows:\n   # venv\\Scripts\\activate\n\n   # Verify activation - you should see (venv) in your prompt\n   which python  # Should show path to venv/bin/python\n   ```\n\n3. **Install Dependencies** (Required)\n   ```bash\n   pip install -r requirements.txt\n   ```\n   \n   **Important**: All dependencies including JWT authentication libraries are required. The gateway will not start if dependencies are missing.\n\n4. **Generate gRPC Stubs**\n   ```bash\n   # Generate Python gRPC client and server stubs in the generated directory\n   python -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto\n   ```\n\n   Generated protobuf files are stored in the `src/generated` directory to separate auto-generated code from hand-written code.\n\n   **Important**: The generated protobuf files (`*_pb2.py` and `*_pb2_grpc.py`) are **NOT committed to the repository**. They must be generated locally after cloning the repository. The `__init__.py` file in the generated directory is committed to maintain the package structure.\n\n   **Note**: The generated files are automatically imported by the gateway. No manual import is required for normal operation.\n\n5. **Prepare Audio Files**\n\n   Place your audio files in the `audio/` directory. The default configuration expects:\n   - `welcome.wav` - Welcome message\n   - `default_response.wav` - Response messages\n   - `goodbye.wav` - Goodbye message\n   - `transferring.wav` - Transfer message\n   - `error.wav` - Error message\n\n## Monitoring Dashboard\n\nThe gateway includes a web-based monitoring interface for viewing gateway status, active sessions, and connection history. The dashboard is accessible at `http://localhost:8080` when the gateway is running.\n\nFor information about authentication and security for the monitoring dashboard, see:\n- [Monitoring README](src/monitoring/README.md) - Comprehensive monitoring and authentication documentation\n- [Authentication Quick Start](AUTHENTICATION_QUICKSTART.md) - Step-by-step authentication setup guide\n\n## Quick Start\n\nFor a quick test of the gateway:\n\n1. **Activate virtual environment** (if not already active):\n   ```bash\n   source venv/bin/activate\n   ```\n\n2. **Generate gRPC stubs** (if not already done):\n   ```bash\n   python -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto\n   ```\n\n3. **Start the server**:\n   ```bash\n   python main.py\n   ```\n\n4. **Access the monitoring interface**:\n   - Open http://localhost:8080 in your browser\n   - Check the status at http://localhost:8080/api/status\n\nThe gateway will start with the local audio connector by default, which uses the audio files in the `audio/` directory.\n\n## Usage\n\n### Configuration\n\nThe gateway is configured via `config/config.yaml`. Key configuration sections:\n\n```yaml\n# Gateway settings\ngateway:\n  host: \"0.0.0.0\"\n  port: 50051\n\n# Connectors configuration\nconnectors:\n  # Local Audio Connector - plays audio files from the audio/ directory\n  local_audio_connector:\n    type: \"local_audio_connector\"\n    class: \"LocalAudioConnector\"\n    module: \"connectors.local_audio_connector\"\n    config:\n      audio_files:\n        welcome: \"welcome.wav\"\n        transfer: \"transferring.wav\"\n        goodbye: \"goodbye.wav\"\n        error: \"error.wav\"\n        default: \"default_response.wav\"\n      agents:\n        - \"Local Playback\"\n\n  # AWS Lex Connector - integrates with Amazon Lex bots\n  aws_lex_connector:\n    type: \"aws_lex_connector\"\n    class: \"AWSLexConnector\"\n    module: \"connectors.aws_lex_connector\"\n    config:\n      region_name: \"us-east-1\"\n      # bot_alias_id: \"YOUR_BOT_ALIAS_ID\"  # Required for specific bot\n      # aws_access_key_id: \"YOUR_ACCESS_KEY\"  # Optional, uses env vars if not set\n      # aws_secret_access_key: \"YOUR_SECRET_KEY\"  # Optional, uses env vars if not set\n      initial_trigger_text: \"hello\"\n      barge_in_enabled: false\n      audio_logging:\n        enabled: true\n        output_dir: \"logs/audio_recordings\"\n        filename_format: \"{conversation_id}_{timestamp}_{source}.wav\"\n        log_all_audio: true\n        max_file_size: 10485760\n        sample_rate: 8000\n        bit_depth: 8\n        channels: 1\n        encoding: \"ulaw\"\n      agents: []\n\n# Monitoring interface\nmonitoring:\n  enabled: true\n  host: \"0.0.0.0\"\n  port: 8080\n  metrics_enabled: true\n  health_check_interval: 30\n\n# Web dashboard authentication\nauthentication:\n  enabled: true\n  environment: \"dev\"  # Options: \"dev\" or \"production\"\n  session:\n    timeout_hours: 24\n    secret_key_env: \"FLASK_SECRET_KEY\"\n  webex_oauth:\n    scopes: \"openid email profile\"\n    state: \"byova_gateway_auth\"\n\n# JWT validation for gRPC requests (REQUIRED when enabled)\njwt_validation:\n  # Enable/disable JWT validation (default: true for security)\n  enabled: true\n  \n  # Enforce validation - if false, invalid tokens are logged but allowed\n  enforce_validation: true\n  \n  # REQUIRED: Datasource URL - must match URL registered with Webex Contact Center\n  # Example: \"https://your-gateway-domain.com:443\"\n  datasource_url: \"\"  # Must be configured if enabled=true\n  \n  # Datasource schema UUID (default is standard BYOVA schema)\n  # This is the schema ID from https://github.com/webex/dataSourceSchemas\n  # Path: Services/VoiceVirtualAgent/5397013b-7920-4ffc-807c-e8a3e0a18f43/schema.json\n  # This value should not change unless there is a major modification to the BYOVA schema\n  datasource_schema_uuid: \"5397013b-7920-4ffc-807c-e8a3e0a18f43\"\n  \n  # Public key cache duration in minutes\n  cache_duration_minutes: 60\n\n# Logging configuration\nlogging:\n  gateway:\n    level: \"INFO\"  # DEBUG, INFO, WARNING, ERROR\n    format: \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n    file: \"logs/gateway.log\"\n    max_size: \"10MB\"\n    backup_count: 5\n  web:\n    level: \"WARNING\"\n    format: \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n    file: \"logs/web.log\"\n    max_size: \"5MB\"\n    backup_count: 3\n\n# Session management\nsessions:\n  timeout: 600  # Session timeout in seconds\n  max_sessions: 1000\n  cleanup_interval: 60\n  enable_auto_cleanup: true\n  max_session_duration: 3600\n\n# Audio processing\naudio:\n  supported_formats:\n    - \"wav\"\n    - \"mp3\"\n    - \"flac\"\n    - \"ogg\"\n```\n\n#### Important Configuration Notes\n\n**JWT Validation** (Required):\n- JWT validation is **enabled by default** for security\n- You **must** configure `datasource_url` before starting the gateway\n- The `datasource_url` must exactly match the URL you register with Webex Contact Center via the BYoDS API\n- If JWT validation is enabled without `datasource_url`, the gateway will **fail to start**\n- For development without JWT validation, explicitly set `jwt_validation.enabled: false`\n\n**Connector Configuration**:\n- Multiple connectors can be configured simultaneously\n- Each connector must have a unique identifier (e.g., `local_audio_connector`, `aws_lex_connector`)\n- Connectors are loaded dynamically based on the `module` and `class` specified\n\n**AWS Credentials**:\n- Prefer environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) over hardcoded credentials\n- Explicit credentials in config files should only be used for development/testing\n\nThe connector uses the standard AWS credential chain (in order of precedence):\n1. **Environment variables**: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`\n2. **AWS credentials file**: `~/.aws/credentials`\n3. **IAM roles**: For EC2, ECS, Lambda, and other AWS services\n4. **AWS SSO**: If configured\n5. **Other AWS credential sources**\n\n**Examples:**\n\n```bash\n# Using environment variables (recommended for local development)\nexport AWS_ACCESS_KEY_ID=your_access_key_id\nexport AWS_SECRET_ACCESS_KEY=your_secret_access_key\nexport AWS_DEFAULT_REGION=us-east-1\n\n# Or configure AWS CLI (recommended for persistent local setup)\naws configure\n\n# For production, use IAM roles attached to your EC2/ECS/Lambda resources\n# No credentials needed in config files!\n```\n\nYou can add these lines to your shell profile (e.g., `.bashrc`, `.zshrc`) or set them in your deployment environment. The gateway will automatically use these credentials if they are set.\n\n### JWT Authentication for gRPC Requests\n\nThe gateway supports JWT (JSON Web Token) validation for all gRPC requests to ensure secure communication with Webex Contact Center. This feature validates tokens from Webex identity broker endpoints and verifies all required claims.\n\n#### Overview\n\nJWT authentication provides:\n- **Signature Verification**: Validates tokens using RSA public keys from Webex JWKS endpoints\n- **Claims Validation**: Verifies issuer, audience, subject, JWT ID, and expiration\n- **Datasource Validation**: Ensures tokens are issued for the correct datasource URL and schema\n- **Caching**: Public keys are cached for 60 minutes to reduce endpoint load\n- **Optional Enforcement**: Can be configured to log violations without rejecting requests\n\n#### Configuration\n\nJWT validation is configured in the `jwt_validation` section of `config/config.yaml`. See the [Configuration](#configuration) section above for the complete configuration structure.\n\n**Key Points**:\n- JWT validation is **enabled by default** (`enabled: true`)\n- You **must** configure `datasource_url` or the gateway will fail to start\n- Set `enabled: false` to disable JWT validation for development/testing\n\n#### How to Obtain Your Datasource URL\n\nThe `datasource_url` must **EXACTLY match** (character-for-character) the URL you provide when registering your datasource via the [BYoDS (Bring Your Own Data Source)](https://developer.webex.com/webex-contact-center/docs/api/v1/data-sources) API.\n\n**Critical**: The JWT token from Webex Contact Center contains a `com.cisco.datasource.url` claim that must match this value exactly. Use the **exact same format** that you used in the BYoDS API registration.\n\n**Examples** (use whatever format YOU registered):\n\n```yaml\n# If you registered with explicit :443 port\ndatasource_url: \"https://your-gateway.example.com:443\"\n\n# If you registered without port (common for standard HTTPS)\ndatasource_url: \"https://your-gateway.example.com\"\n\n# Ngrok URLs (check your BYoDS registration for exact format)\ndatasource_url: \"https://abc123def456.ngrok-free.app\"\n```\n\n**How to verify**:\n1. Check your BYoDS datasource registration (via API or Control Hub)\n2. Copy the EXACT URL you registered (character-for-character)\n3. Paste it into `jwt_validation.datasource_url` in your config\n\n**Common mistakes**:\n- ❌ Registered: `https://example.com` → Config: `https://example.com:443` (MISMATCH!)\n- ❌ Registered: `https://example.com:443` → Config: `https://example.com` (MISMATCH!)\n- ✅ Registered: `https://example.com` → Config: `https://example.com` (MATCH!)\n- ✅ Registered: `https://example.com:443` → Config: `https://example.com:443` (MATCH!)\n\n#### Understanding the Datasource Schema UUID\n\nThe `datasource_schema_uuid` identifies the specific schema definition used for communication between Webex Contact Center and your gateway. This UUID comes from the [Webex dataSourceSchemas repository](https://github.com/webex/dataSourceSchemas).\n\n**For BYOVA (Voice Virtual Agent)**:\n- **Schema UUID**: `5397013b-7920-4ffc-807c-e8a3e0a18f43`\n- **Schema Location**: `Services/VoiceVirtualAgent/5397013b-7920-4ffc-807c-e8a3e0a18f43/schema.json`\n- **Proto Definitions**: Defined in the same directory structure\n- **Stability**: This UUID should **not change** unless there is a major modification to the BYOVA schema definition by Webex\n\n**What is it?**\nThe schema UUID defines the structure of request and response payloads, protocol (gRPC), and supported app types. It ensures that both Webex Contact Center and your gateway are using the same communication protocol and message formats.\n\n**Do I need to change it?**\nIn most cases, **no**. The default value is the standard BYOVA schema UUID and will work for all standard BYOVA implementations. You would only change this if:\n- Webex releases a new major version of the BYOVA schema\n- You're using a different Webex Contact Center service schema (not BYOVA)\n\n**Reference**: [Webex dataSourceSchemas Documentation](https://github.com/webex/dataSourceSchemas)\n\n#### Supported Webex Regions\n\nThe gateway validates tokens from these Webex identity broker issuers:\n- `https://idbrokerbts.webex.com/idb` (BTS US)\n- `https://idbrokerbts-eu.webex.com/idb` (BTS EU)\n- `https://idbroker.webex.com/idb` (Production US)\n- `https://idbroker-eu.webex.com/idb` (Production EU)\n- `https://idbroker-b-us.webex.com/idb` (B-US)\n- `https://idbroker-ca.webex.com/idb` (Canada)\n\n#### Token Format\n\nTokens are expected in the gRPC metadata `authorization` header:\n```\nauthorization: Bearer \u003cJWT_TOKEN\u003e\n```\n\n#### Deployment Recommendations\n\n**Development**:\n```yaml\njwt_validation:\n  enabled: false  # Or enabled: true with enforce_validation: false for testing\n```\n\n**Production**:\n```yaml\njwt_validation:\n  enabled: true\n  enforce_validation: true\n  datasource_url: \"https://your-production-url.com:443\"\n```\n\n#### Troubleshooting\n\n**Error: \"Missing JWT token in authorization metadata\"**\n- Ensure Webex Contact Center is configured to send JWT tokens with gRPC requests\n- Verify your datasource is properly registered with Webex Contact Center\n\n**Error: \"JWT token signature not valid\"**\n- Check that public keys can be fetched from Webex identity broker\n- Verify your network allows outbound HTTPS connections to Webex endpoints\n\n**Error: \"Invalid issuer\"**\n- The JWT token's issuer claim must be from a valid Webex identity broker\n- **Security**: Issuer is validated BEFORE fetching keys to prevent SSRF attacks\n- Supported issuers: \n  - `https://idbrokerbts.webex.com/idb` (BTS US)\n  - `https://idbrokerbts-eu.webex.com/idb` (BTS EU)\n  - `https://idbroker.webex.com/idb` (Production US)\n  - `https://idbroker-eu.webex.com/idb` (Production EU)\n  - `https://idbroker-b-us.webex.com/idb` (B-US)\n  - `https://idbroker-ca.webex.com/idb` (Canada)\n- Verify your datasource is properly configured in Webex Contact Center\n- If you see this error with a malformed issuer URL, it may indicate a security attack attempt\n\n**Error: \"Datasource URL mismatch\"** or \"Datasource claims validation failed\"\n- Your `datasource_url` in config must EXACTLY match (character-for-character) the URL you registered via BYoDS API\n- The JWT token contains a `com.cisco.datasource.url` claim that must match your config value exactly\n- Check if you registered with or without the port (`:443`) and match it exactly\n- Common issue: Config has `:443` but BYoDS registration doesn't (or vice versa)\n- **To debug**: Set log level to DEBUG and check the log message showing expected vs actual URL\n- **Solution**: Copy the exact URL from your BYoDS datasource registration and update your config\n\n**Error: \"JWT token is expired\"**\n- This indicates Webex Contact Center sent an expired token\n- Check system clock synchronization between your gateway and Webex services\n\nFor gradual rollout, start with `enforce_validation: false` to log validation results without rejecting requests, then enable enforcement after verification.\n\n### Running the Server\n\n#### Method 1: Manual Start (Recommended for Development)\n\n```bash\n# Ensure virtual environment is activated\nsource venv/bin/activate\n\n# Start the server\npython main.py\n```\n\nThe server will start both:\n- **gRPC Server**: `grpc://0.0.0.0:50051`\n- **Web Monitoring Interface**: `http://localhost:8080`\n\n#### Method 2: Background Start\n\n```bash\n# Start in background\npython main.py \u0026\n\n# Check if running\nps aux | grep \"python main.py\"\n\n# Stop the server\npkill -f \"python main.py\"\n```\n\n### Public URL Hosting with ngrok\n\nThe [Bring Your Own Data Source (BYODS) framework](https://developer.webex.com/create/docs/bring-your-own-datasource) requires a publicly accessible URL for data exchange with Webex Contact Center. For development and testing, you can use ngrok to create a public URL that tunnels to your local gateway.\n\n#### Prerequisites\n\n1. **Install ngrok**\n   - Download from [ngrok.com](https://ngrok.com/download)\n   - Or install via package manager:\n     ```bash\n     # macOS with Homebrew\n     brew install ngrok/ngrok/ngrok\n\n     # Or download directly from ngrok.com\n     ```\n\n2. **Sign up for ngrok account** (free tier available)\n   - Create account at [ngrok.com](https://ngrok.com)\n   - Get your authtoken from the dashboard\n\n3. **Configure ngrok**\n   ```bash\n   # Add your authtoken\n   ngrok config add-authtoken YOUR_AUTHTOKEN\n   ```\n\n#### Running with ngrok\n\n1. **Start the gateway** (in one terminal):\n   ```bash\n   # Activate virtual environment\n   source venv/bin/activate\n\n   # Start the gateway\n   python main.py\n   ```\n\n2. **Start ngrok tunnel** (in another terminal):\n   ```bash\n   # Create public tunnel to the gRPC server\n   ngrok http --upstream-protocol=http2 50051\n   ```\n\n   **Important**: Use the `--upstream-protocol=http2` flag as gRPC requires HTTP/2 protocol.\n\n3. **Access your public gateway**:\n   - ngrok will display a public URL like: `https://abc123.ngrok.io`\n   - This URL can be used by external services to connect to your gateway\n   - The monitoring interface will still be available locally at `http://localhost:8080`\n\n4. **Register with Webex Data Sources API**:\n   - Use the ngrok URL to register your data source with the [Webex Data Sources API](https://developer.webex.com/admin/docs/api/v1/data-sources/register-a-data-source)\n   - This registration is required for Webex Contact Center to establish the BYODS connection\n   - The registered URL will be used for all data exchange between Webex and your gateway\n\n#### ngrok Dashboard\n\n- Access the ngrok web interface at `http://localhost:4040` to monitor requests\n- View real-time traffic, request/response details, and connection status\n- Useful for debugging external connections to your gateway\n\n#### Security Considerations\n\n- **Development Only**: ngrok is intended for development and testing\n- **Temporary URLs**: Free ngrok URLs change each time you restart ngrok\n- **Public Access**: Anyone with the URL can access your gateway\n- **Credentials**: Never expose production credentials through ngrok\n\n#### Example Usage\n\n```bash\n# Terminal 1: Start gateway\nsource venv/bin/activate\npython main.py\n\n# Terminal 2: Start ngrok tunnel\nngrok http --upstream-protocol=http2 50051\n\n# Output example:\n# Forwarding  https://abc123.ngrok.io -\u003e http://localhost:50051\n#\n# Use this URL in your Webex Contact Center configuration:\n# https://abc123.ngrok.io\n```\n\n### Monitoring Interface\n\nOnce the server is running, access the web monitoring interface at:\n\n- **Main Dashboard**: `http://localhost:8080`\n- **Status API**: `http://localhost:8080/api/status`\n- **Connections API**: `http://localhost:8080/api/connections`\n- **Health Check**: `http://localhost:8080/health`\n- **Debug Info**: `http://localhost:8080/api/debug/sessions`\n\n#### Dashboard Features\n\n- **Real-time Status**: Gateway status and metrics\n- **Active Connections**: Live session tracking\n- **Connection History**: Recent connection events\n- **Available Agents**: List of configured virtual agents\n- **Configuration**: Gateway settings and connector info\n\n### Testing\n\n```bash\n# Test the monitoring interface\ncurl http://localhost:8080/api/status\n\n# Test connection tracking\ncurl http://localhost:8080/api/connections\n\n# Create a test session (for development)\ncurl http://localhost:8080/api/test/create-session\n```\n\n### gRPC Service Testing\n\nTest the gRPC services directly using either grpcurl or the provided Python test script.\n\n#### Using grpcurl\n\nIf you have grpcurl installed, you can test the gRPC services directly. Install grpcurl from the [releases page](https://github.com/fullstorydev/grpcurl/releases) for your platform.\n\n**Test gRPC services:**\n```bash\n# Test overall health\ngrpcurl -plaintext -import-path proto -proto health.proto localhost:50051 grpc.health.v1.Health/Check\n\n# Test gateway service health\ngrpcurl -plaintext -import-path proto -proto health.proto -d '{\"service\":\"byova.gateway\"}' localhost:50051 grpc.health.v1.Health/Check\n\n# Test VoiceVirtualAgent service health\ngrpcurl -plaintext -import-path proto -proto health.proto -d '{\"service\":\"byova.VoiceVirtualAgentService\"}' localhost:50051 grpc.health.v1.Health/Check\n\n# List available virtual agents\ngrpcurl -plaintext -import-path proto -proto voicevirtualagent.proto localhost:50051 com.cisco.wcc.ccai.media.v1.VoiceVirtualAgent/ListVirtualAgents\n```\n\n**Expected outputs:**\n```json\n# Health checks return:\n{\"status\": \"SERVING\"}\n\n# Virtual agents list returns:\n{\n  \"virtualAgents\": [\n    {\n      \"virtualAgentId\": \"Local Audio: Local Playback\",\n      \"virtualAgentName\": \"Local Playback\",\n      \"isDefault\": true\n    },\n    {\n      \"virtualAgentId\": \"aws_lex_connector: YourBotName\",\n      \"virtualAgentName\": \"YourBotName\"\n    }\n  ]\n}\n```\n\n#### Using Python Test Script\n\nAlternatively, use the provided Python test script:\n\n```bash\n# Run the health check test script\npython test_health.py\n```\n\n**Expected output:**\n```\nTesting gRPC Health Service:\n----------------------------------------\nOverall: SERVING (1)\nbyova.gateway: SERVING (1)\nbyova.VoiceVirtualAgentService: SERVING (1)\n```\n\n**Status codes:**\n- `SERVING (1)`: Service is healthy and operational\n- `NOT_SERVING (2)`: Service is unhealthy or unavailable\n- `SERVICE_UNKNOWN (0)`: Service status cannot be determined\n\n**Security Note:** gRPC reflection is disabled by default for security. This is why proto files are required for grpcurl commands.\n\n## API\n\n### gRPC Endpoints\n\n- **ListVirtualAgents**: Returns available virtual agents\n- **ProcessCallerInput**: Handles bidirectional streaming for voice interactions\n- **Health/Check**: Standard gRPC health checking service\n\n### HTTP Endpoints\n\n- `GET /`: Main dashboard\n- `GET /api/status`: Gateway status\n- `GET /api/connections`: Connection data\n- `GET /health`: Health check\n- `GET /api/debug/sessions`: Debug information\n\n## Features\n\n- **gRPC Server**: Handles communication with Webex Contact Center\n- **Virtual Agent Router**: Dynamically routes requests to different connector implementations\n- **Local Audio Connector**: Simulates virtual agents using local audio files\n- **AWS Lex Connector**: Integration with Amazon Lex v2 for production virtual agents\n- **Web Monitoring Interface**: Real-time dashboard for monitoring connections and status\n- **Session Management**: Tracks active sessions and connection events\n- **Extensible Architecture**: Easy to add new connector implementations\n\n## Connector Documentation\n\nThis gateway supports multiple virtual agent connectors. Each connector has its own documentation:\n\n- **[Connectors Overview](src/connectors/README.md)**: Complete guide to all available connectors and how to create new ones\n- **[Local Audio Connector](src/connectors/README.md#local-audio-connector-local_audio_connectorpy)**: Testing and development with local audio files\n- **[AWS Lex Connector](src/connectors/README.md#aws-lex-connector-aws_lex_connectorpy)**: Production integration with Amazon Lex v2\n- **[Audio Files Guide](audio/README.md)**: Audio file formats, organization, and configuration\n\n## Project Structure\n\n```\nwebex-byova-gateway-python/\n├── audio/                    # Audio files for local connector\n├── config/\n│   ├── config.yaml          # Main configuration file\n│   └── aws_lex_example.yaml # AWS Lex configuration example\n├── proto/                    # Protocol Buffer definitions\n├── src/\n│   ├── connectors/           # Virtual agent connector implementations\n│   │   ├── i_vendor_connector.py\n│   │   ├── local_audio_connector.py\n│   │   ├── aws_lex_connector.py\n│   │   └── README.md\n│   ├── core/                # Core gateway components\n│   │   ├── virtual_agent_router.py\n│   │   └── wxcc_gateway_server.py\n│   ├── generated/           # Generated gRPC stubs\n│   │   ├── byova_common_pb2.py\n│   │   ├── byova_common_pb2_grpc.py\n│   │   ├── voicevirtualagent_pb2.py\n│   │   └── voicevirtualagent_pb2_grpc.py\n│   ├── monitoring/          # Web monitoring interface\n│   │   ├── app.py\n│   │   └── templates/\n│   └── utils/               # Utility modules\n├── main.py                  # Main entry point\n├── requirements.txt          # Python dependencies\n└── README.md\n```\n\n## Development\n\n### Adding New Connectors\n\n1. Create a new connector class in `src/connectors/`\n2. Inherit from `IVendorConnector`\n3. Implement required abstract methods\n4. Add configuration to `config/config.yaml`\n5. Restart the server\n\n### gRPC Stub Generation\n\nThe protobuf definitions used in this gateway are sourced from the [Webex dataSourceSchemas repository](https://github.com/webex/dataSourceSchemas), specifically the Voice Virtual Agent schema. These definitions define the structure for BYOVA (Bring Your Own Virtual Agent) data exchange with Webex Contact Center.\n\nIf you modify the `.proto` files, you must regenerate the Python stubs:\n\n```bash\n# Regenerate stubs\npython -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto\n```\n\n**Note**: The generated files are automatically ignored by git (see `.gitignore`). After regenerating, the files will be available locally but won't be committed to the repository.\n\n## Troubleshooting\n\n### Port Conflicts\n\nIf port 8080 is in use:\n\n```bash\n# Check what's using the port\nlsof -i :8080\n\n# Kill the process\nkill \u003cPID\u003e\n\n# Or change the port in config/config.yaml\n```\n\n### Virtual Environment Issues\n\n**Problem**: `python: command not found` or import errors\n\n**Solution**: Ensure virtual environment is activated before running any Python commands:\n\n```bash\n# Check if virtual environment is activated\necho $VIRTUAL_ENV  # Should show path to venv directory\n\n# If not activated, activate it\nsource venv/bin/activate\n\n# Verify Python is from virtual environment\nwhich python  # Should show .../venv/bin/python\n\n# Recreate virtual environment if needed\nrm -rf venv\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n**Important**: Always activate the virtual environment before running `python main.py` or any other Python commands.\n\n### Logs\n\nThe server provides detailed logging:\n- **INFO**: General operation information\n- **DEBUG**: Detailed request/response tracking\n- **ERROR**: Error conditions and exceptions\n\nCheck the terminal output for real-time logs when running manually.\n\n## Maintainers\n\n[@adweeks](https://github.com/adweeks)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## License\n\n[Cisco Sample Code License v1.1](LICENSE) © 2018 Cisco and/or its affiliates\n\n---\n\n**Note**: This Sample Code is not supported by Cisco TAC and is not tested for quality or performance. This is intended for example purposes only and is provided by Cisco \"AS IS\" with all faults and without warranty or support of any kind.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebex%2Fwebex-byova-gateway-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebex%2Fwebex-byova-gateway-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebex%2Fwebex-byova-gateway-python/lists"}