For the purposes of this guide, we will walk you through the webrtc-hello-world-ts sample app in Node.js, but the idea is the same in all languages.
When you run
npm start and the the web page is loaded, the frontend code calls the backend route
Which returns some information about the application, but most importantly, creates the browser user as a WebRTC participant:
If you look deeper into the
createParticipant call, you can see we're using the Bandwidth WebRTC HTTP API
to create the participant with
AUDIO permissions and a tag of "hello-world-browser":
This API call returns a
participant object and a
token we can use to authorize a device. In this case, our WebRTC Browser SDK.
We also take our newly created
participant.id and add it to our WebRTC session:
A quick note on this: the
getSessionId() method is a convenience method in this example that will automatically create and keep track of a
sessionId that we use as a "conference" or "room" to
connect our participants.
Once that's all done, the
createParticipant call from
/connectionInfo (remember? that's where this all started!)
token and some other info to our frontend.
In the example above, you may have noticed that we pass in
sessionId when we add the participant to the session. But
sessionId is already a path param in the REST URL, so what gives?
By doing that, you're telling Bandwidth WebRTC to subscribe this participant to everyone else in the session, and subscribe everyone in the session to this participant! You could also include a list of explicit participants, if you wanted to only subscribe them to one or two other people.
This gives you lots of flexibility and control over what each participant receives and sends in a session. You can find more about sessions in our API documentation.
Once the frontend has a valid device token, we can use this to connect our WebRTC Browser SDK to the session:
deviceToken authorizes our browser as a participant in our WebRTC session. In this example, you can see
we want the participant to publish
audio but not
Side note: even if this browser set
video: true, they would not be able to publish video with this token! In our server's
createParticipant call, we set our
publishPermissions for this participant to only
This gives the server-side application total control over how participants interact in a WebRTC session.
Now that our browser is connected, whenever another participant joins the session and starts or stops publishing,
we will receive notifications via the
onStreamUnavailable events in our browser SDK:
In this example, we just keep track of the latest stream that's available. In more complicated applications, you may want to handle multiple streams from multiple participants.
Once a stream is available,
setRemoteStream will set state, and our
video component will render on the page
and play the media stream (which in this case, is just audio):
Now we're all ready to go, but there's only 1 participant in the session! That's not any fun. How can we add another participant so they can interact with this browser?
One way to add a participant is to support an inbound phone call, which creates an audio conference between the browser and phone.
Our sample app does just this, using Bandwidth's Voice API! Read more about how to create a Bandwidth Voice API application.
In our backend example code, we support the
/incomingCall callback from our Voice API application:
When we receive a phone call, we again call
createParticipant, which creates a new participant with
and adds them to our session.
Like the browser participant, this call returns a
token that authorizes the phone to publish and subscribe streams in our session.
But in the browser, we did this with our
onStreamAvailable methods. How do we publish and subscribe streams on a phone?
We use a handy feature of Bandwidth's Voice API called a
transfer. By returning the BXML from the
generateTransferBxml method, this
callback tells the API to transfer the call into the WebRTC session! All of the hard parts of transcoding and mixing streams is
handled by Bandwidth's WebRTC platform.
Once the transfer is made, the browser participant's
onStreamAvailable event will fire and connect the phone call's audio
to the browser's audio.
Go ahead and try it yourself! Again, this is a simple example, but you can see how you can extend this to create conference calls with multiple browsers and phones.
Another way to add a participant to this session is to have the browser make an outbound call to a phone. The browser will still be a participant, publishing and receiving audio, but this app will also use Bandwidth's Voice API to make an outbound call from the server and connect it into the session.
Our frontend code has a nice big button to make an outbound call (make sure you set
OUTBOUND_PHONE_NUMBER in your
.env file or this
won't work!). When you click it, it calls the
Aside from the excellent error handling, you can see we simply make a call to the server on the route
/callPhone. Lets see
what that does:
By now you should see a pattern -- we call
createParticipant again, just like we did for our browser, and just like we did for our
inbound call. Again, this call creates a participant and adds them into our session. Now we call the
Since we're initiating the call, we tell Bandwidth's Voice API to place a call and which routes we want our callbacks to go to. We associate
our participant we created earlier with the callId so we can tie these together in our callback
When Bandwidth's Voice API hits our callback, they will give us the
callId. We can look up our
participant object with that
and, much like our inbound call, we use the
participant.token to tell Bandwidth's Voice API to transfer the
call into our WebRTC session.
You should notice the
generateTransferBxml call works exactly like it did in our
/incomingCall route. Once the call is
transferred, Bandwidth's WebRTC platform makes the phone call look like another WebRTC participant in our
session and will trigger each browser's
onStreamAvailable method with the call's audio stream.
Since we've already got our code set up to stream audio, we don't have to do anything else.
Give it a try yourself!
Hopefully this tutorial was helpful to understand how Bandwidth's WebRTC and Voice API platforms can be combined to make powerful, real-time communication applications.
And it's not limited to just audio and phones! You can use the same
ideas to create web based video streaming or screen sharing applications.