Bandwidth Integration

​

Overview

Bandwidth is a CPaaS (Communications Platform as a Service) provider that offers programmable voice through its Voice API. VR3 AI’s Bandwidth integration uses the Voice API plus WebSocket media streaming to power your voice agents, and supports both inbound and outbound calling.

​

Prerequisites

Before setting up Bandwidth integration, you’ll need:

• A Bandwidth account with the Voice API enabled
• An Account ID from the Bandwidth Dashboard
• An API Username and API Password for an API credential that has the HttpVoice role
• A Voice Application (optional — leave the field blank in VR3 AI and we’ll auto-create one for you on save, with the inbound webhook URL pre-set)
• At least one phone number on your Bandwidth account
• A VR3 AI instance running and reachable from Bandwidth’s webhooks

​

Configuration

​

Step 1: Get Bandwidth Credentials

1. Log in to the Bandwidth Dashboard
2. Note your Account ID (shown in the dashboard / account settings)
3. Create (or copy) an API credential with the HttpVoice role, and note its API Username and API Password
4. (Optional) Navigate to Applications and create (or open) the Voice Application you’ll use with VR3 AI, then copy its Application ID. Skip this if you want VR3 AI to auto-create the Voice Application for you on save.
5. Make sure at least one phone number is assigned to the Voice Application you’ll use with VR3 AI (if you’re letting VR3 AI auto-create the application, do this after saving the configuration in Step 2)

​

Step 2: Configure in VR3 AI

1. Navigate to /telephony-configurations and click Add configuration
2. Select Bandwidth as your provider
3. Enter your credentials:
   • Account ID
   • API Username
   • API Password
   • Application ID — optional. Leave blank and VR3 AI will auto-create a Voice Application on save (with the inbound webhook URL already configured) and store its Application ID on this configuration. VR3 AI also generates and stores a callback username/password used for the application’s webhook Basic Auth.
4. Click Save Configuration
5. Open the configuration you just created and add at least one phone number (with country code in E.164 format, e.g. +1234567890). The default caller ID is used for outbound calls.
   If VR3 AI auto-created the Voice Application for you, you still need to assign your Bandwidth numbers to that application in the Bandwidth Dashboard under Applications. The auto-created application is named vr3-<random> — its Application ID is shown on the saved configuration.

​

Step 3: Test Your Configuration

1. Create a test workflow
2. Click “Call” to verify connection
3. Check call logs for successful connection

​

Inbound Calling Setup

Bandwidth delivers inbound webhooks at the Voice Application level — the callback URL is configured once on the application, and applies to every number assigned to it. When VR3 AI auto-creates the Voice Application on save, it sets the inbound webhook URL on the application automatically and stores the generated callback username/password used for webhook Basic Auth. If you supplied your own Application ID, point its callback URL at VR3 AI yourself (see below).

​

Step 1: Assign an Inbound Workflow to the Phone Number

1. Go to /telephony-configurations and open your Bandwidth configuration
2. In the Phone numbers section, edit the number that should receive inbound calls
3. Set its Inbound workflow to the agent that should answer
4. Save

​

Step 2: Verify the Callback URL on the Voice Application

1. Go to Applications in the Bandwidth Dashboard
2. Open the application whose Application ID you configured in VR3 AI
3. In the application’s Call Initiated / Callback settings, confirm:
   • Callback URL points to your VR3 AI backend, e.g. https://your-vr3ai-host/api/v1/telephony/inbound/run
   • HTTP Method is POST
   • Basic Auth username/password match the callback credentials stored on the configuration
4. Make sure the phone numbers you want to use for inbound are assigned to this application
   If VR3 AI auto-created the application during configuration save, the callback URL and Basic Auth credentials are already set and this step is a no-op. The same URL is shared across every number on the Voice Application — VR3 AI matches the inbound call to the right agent using the called number’s inbound workflow assignment. If you supplied your own Application ID, set the callback URL to your VR3 AI backend’s /api/v1/telephony/inbound/run endpoint, set the method to POST, and configure Basic Auth with the callback credentials shown on the saved configuration.

​

Step 3: Verify Setup

• Ensure your VR3 AI instance is reachable from Bandwidth’s webhooks
• Verify any firewalls allow Bandwidth’s IP ranges

​

Test Inbound Calling

1. Call your configured Bandwidth phone number from another phone
2. Verify your VR3 AI voice agent answers and responds
3. Check call logs in both your VR3 AI dashboard and the Bandwidth Dashboard

​

Troubleshooting

​

Best Practices

• Test your configuration with a single call before running campaigns
• Monitor the Bandwidth Dashboard for usage and billing
• Use a dedicated Voice Application for VR3 AI so the shared callback URL doesn’t conflict with other systems