A sample application demonstrating how to build a browser-based Bandwidth RTC dialer using the Bandwidth Real-Time Communications (BRTC) JavaScript SDK. This application showcases the BRTC product by allowing you to place calls to phone numbers of your choice. The connection to arbitrary call-ids and endpoints is in progress.
This sample application consists of two main components:
- Bandwidth RTC Integration: Uses the
bandwidth-rtcSDK to establish Bandwidth RTC connections - Media Controls: Capture and manage audio input/output devices
- Call Controls: Dial phone numbers, accept incoming calls, and manage call state
- Endpoint Management: Create and manage WebRTC endpoints for phone number connections
- Endpoint Management: Creates and manages Bandwidth RTC endpoints
- Call Orchestration: Handles inbound and outbound call routing via Bandwidth Voice API
- Callback Handling: Processes webhooks for call and endpoint events
- Token Management: Manages OAuth2 authentication with Bandwidth API
- Make outbound calls from browser to phone numbers
- Receive inbound calls on browser endpoints
- Real-time audio streaming via Bandwidth RTC
- Dynamic endpoint creation and management
- Call state management and event handling
- Audio device selection and control
- Connection to arbitrary call-ids and endpoints
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Browser Client │ ◄─────► │ Express Server │ ◄─────► │ Bandwidth API │
│ (React App) │ │ (Node.js) │ │ (Voice/BRTC) │
│ localhost:5000 │ │ localhost:3000 │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
Bandwidth RTC HTTPS
│
│ Webhooks
▼
┌──────────────────┐
│ ngrok/Public │
│ Callback URL │
└──────────────────┘
| Service | Port | Description |
|---|---|---|
| Express Server | 3000 | Backend API and webhook handler |
| React Dev Server | 5000 | Frontend development server |
- Node.js 16+ and npm
- A Bandwidth account with:
- Account ID
- API credentials (username/password or client ID/secret)
- A Bandwidth phone number
- A configured Voice Application
- Access to the BRTC role on your credentials
- ngrok or similar tunneling service for webhook callbacks
git clone <repository-url>cd javascript-brtc-sdk-sample-appnpm installCopy the example environment file and fill in your Bandwidth credentials:
cp .env.example .env.localEdit .env.local with your values:
# Bandwidth API ConfigurationHTTP_BASE_URL=https://api.bandwidth.com/v2# Bandwidth Account Credentials (use either username/password OR client credentials)ACCOUNT_ID=your_account_idBW_USERNAME=your_usernameBW_PASSWORD=your_password# OR# BW_ID_CLIENT_ID=your_client_id# BW_ID_CLIENT_SECRET=your_client_secret# Bandwidth Application SettingsAPPLICATION_ID=your_application_idFROM_NUMBER=+1XXXXXXXXXX# Bandwidth RTC Gateway URL# The Programmable Voice team will provide the customer with a gateway URL to connect toREACT_APP_WSS_URL=wss://your-webrtc-gateway-url# Public Callback URL (ngrok or similar)CALLBACK_BASE_URL=https://your-callback-url.ngrok-free.appStart ngrok to expose your local server:
ngrok http 3000Copy the ngrok URL and update CALLBACK_BASE_URL in .env.local.
Update your Bandwidth Voice Application settings:
- Callback URL:
https://your-ngrok-url.ngrok-free.app/callbacks/bandwidth - Call-initiated callback method:
POST - Status URL:
https://your-ngrok-url.ngrok-free.app/callbacks/bandwidth/status - Status callback method:
POST
The application requires two processes running simultaneously:
Terminal 1 - Start the Backend Server:
npm startThis starts the Express server on port 3000.
Terminal 2 - Start the React Development Server:
npm run reactThis starts the React app on port 5000.
Open your browser and navigate to:
http://localhost:5000
- Create an Endpoint: Click "Create Endpoint" to establish a Bandwidth RTC connection
- Select Audio Devices: Choose your microphone and speakers from the available devices
- Make a Call: Enter a phone number (with country code, e.g., +1234567890) and click "Call"
- Receive a Call: When someone calls your Bandwidth number, the call will be routed to your browser
- End Call: Click "Hang Up" to disconnect the call
- Delete Endpoint: Click "Disconnect & Delete Endpoint" when done
Note: Currently, the application supports calling phone numbers. Connection to arbitrary call-ids and endpoints is under development.
├── server/
│ ├── index.ts # Express server with API endpoints and webhook handlers
│ └── types.ts # TypeScript type definitions
├── src/
│ ├── components/
│ │ ├── CallController.tsx # Call control UI (dial, hang up)
│ │ ├── EndpointHandler.tsx # Endpoint creation and management
│ │ ├── MediaCapture.tsx # Audio input device selection
│ │ ├── MediaPlayer.tsx # Audio output device selection
│ │ └── Navbar.tsx # Navigation bar
│ ├── css/ # Styles
│ └── App.tsx # Main application component
├── .env.example # Example environment variables
└── package.json
GET /token- Create a new Bandwidth RTC endpoint and get JWTDELETE /api/endpoint/:endpointId- Delete an endpointPOST /simulate-incoming-call- Place a test call
POST /callbacks/bandwidth- BRTC endpoint events and incoming PSTN callsPOST /callbacks/bandwidth/status- Voice API status events (disconnect)POST /calls/answer- Outbound call answer BXML callbackPOST /calls/status- Call status updates
GET /health- Health checkGET /debug/endpoints- Inspect endpoint pool status
Issue: "Missing required environment variable"
- Solution: Ensure all required variables in
.env.localare set
Issue: Calls not connecting
- Solution: Verify your ngrok URL is set correctly and your Bandwidth Voice Application is configured with the correct callback URLs
Issue: No audio in calls
- Solution: Check browser permissions for microphone access and verify correct audio devices are selected
Issue: "Failed to fetch auth token"
- Solution: Verify your Bandwidth API credentials are correct
- Bandwidth RTC Endpoint API reference
- Bandwidth RTC Connect Verb spec
- bandwidth-rtc Javascript SDK
- Bandwidth Programmable Voice APIs
Reach out to support@bandwidth.com for any questions or feedback regarding this product.
See repository license file for details.