Quick Start Guide

This is a brief guide to get you up and running with Bandwidth's In-App Calling solution. This guide will demonstrate using In-App Calling to place outbound voice calls to web and mobile devices.

Assumptions

• You have already created and set up your Bandwidth account.
  • If you have not already done so, please look here for our Account Setup guide.
• You are familiar with the basics of WebRTC and have a basic understanding of how to use the In-App Calling SDKs.
  • More information on our In-App Calling SDKs can be found here.

Credentials

danger

Access tokens are sensitive credentials and should be handled with care. Client-side javascript does not have a mechanism for hiding these credentials so do not place these directly in your client-side code.

The token should be retrieved from a server running in a secure environment and securely provided to clients.

Bandwidth accepts no responsibility for the loss of account credentials and any resulting network traffic, fraud, or undesired account access that results from failing to manage account access credentials in a completely secure manner.

In-App Calling utilizes OAuth2 to secure the connection between the client and the Bandwidth WebRTC Gateway. The OAuth2 token is used to authenticate the client and authorize the client to place calls on behalf of the account.

The credentials used to retrieve the OAuth2 token are the same credentials used to authenticate API requests to Bandwidth's Voice API and other services.

You will need to retrieve an OAuth2 token from Bandwidth's Identity Services endpoint. More information on generating credentials for an access token can be found here.

Creating a Phone Call

Assuming that you have already retrieved an OAuth2 token from Bandwidth's Identity Services endpoint, you can now use the In-App Calling SDK to place an outbound call.

import { BandwidthUA } from '@bandwidth/bw-webrtc-sdk';

const accountId = 'YOUR_BANDWIDTH_ACCOUNT_ID'; // This should be your Bandwidth account ID (ex. 5500000).
const authToken = 'YOUR_OAUTH_TOKEN'; // This token should be retrieved from a secure server and not hardcoded in your client-side code.
const destinationNumber = 'YOUR_DESTINATION_NUMBER'; // This should be a valid phone number that can receive calls, in E164 format (ex. +19195551234).

const serverConfig = {
      domain: 'gw.webrtc-app.bandwidth.com',
      addresses: ['wss://gw.webrtc-app.bandwidth.com:10081'],
      iceServers: [
        'stun.l.google.com:19302',
        'stun1.l.google.com:19302',
        'stun2.l.google.com:19302'
      ]
    };

const bandwidthInAppClient = new BandwidthUA();

bandwidthInAppClient.setServerConfig(
      serverConfig.addresses,
      serverConfig.domain,
      serverConfig.iceServers
    );
bandwidthInAppClient.checkAvailableDevices();
bandwidthInAppClient.setAccount(`${accountId}`, 'In-App Calling Sample', '');
bandwidthInAppClient.setOAuthToken(authToken);

let extraHeaders = [`User-to-User:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30;encoding=jwt;Y29ycmVjdC1ob3JzZS1iYXR0ZXJ5LXN0YXBsZQ==;encoding=base64`];

bandwidthInAppClient.makeCall(`${destinationNumber}`, extraHeaders).then((value) => {
      console.log('Call created');
    }).catch((error) => {
      console.log('Call failed');
    });

Receiving a Phone Call

The In-App client can also be used to handle inbound calls to a Bandwidth number. This is done by setting up a backend to receive and park the call via the Programmable Voice API, and then notifying the client to accept the call.

A simple flow for handling inbound calls is as follows:

1. Inbound call from the PSTN is received by Bandwidth and an Initiate Webhook is sent to the configured CallInitiatedCallbackUrl.
   1. The backend receives the webhook and parks the call by returning Ring or SpeakSentence BXML.
2. The backend notifies the client that a call is available to accept.
3. The client "accepts" the call by making an outbound call to a Bandwidth Programmable Voice number.
4. The backend receives the Initiate Webhook from the In-App Calling client and returns Bridge BXML to bridge the two calls together.

Resources

The following resources are available to aid in the development of quality solutions using Bandwidth In-App calling.

SDKs

SDKs exposing all key capabilities are available in raw and packaged form.

Environment	Documentation	Package
Web / Javascript	Javascript SDK	bw-webrtc-sdk
Android / Kotlin	Coming Soon	bandwidth-kotlin-webrtc
iOS / Swift	Coming Soon	swift-webrtc-sdk

Sample Applications

Getting started with Bandwidth's In-App Calling SDKs is simple using our sample applications to assist in the development process.

Name	Language	Description	Sample Application
Dialpad	React / Node	A simple dial pad application that demonstrates creating outbound calls using our WebRTC SDK.	in-app-calling-dialpad-node-react
Inbound Calling Demo	React / Python	A simple application demonstrating receiving inbound calls using In-App Calling.	in-app-calling-demo-python
Android / Kotlin Sample	Kotlin	A simple dial pad application that demonstrates creating outbound calls using our Android SDK.	in-app-calling-kotlin-sample
iOS / Swift Sample	Swift	A simple dial pad applicationthat demonstrates creating outbound calls using our iOS SDK.	in-app-calling-swift-sample