Quick Start

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 BRTC SDKs.
  • More information on our BRTC SDKs can be found here.
• You are familiar with the basics of Programmable Voice and have a basic understanding of how to use BXML.
  • More information on Programmable Voice and BXML can be found here.
• You have a publicly accessible URL to use as your webhook URL.
  • If you do not have a publicly accessible URL, you can use a tool like ngrok to create one.

Register an Endpoint

To use the Endpoints API, first familiarize yourself with our documentation on API Credentials and Authentication, which can be found here.

To make or receive a call using BRTC, you must first register an endpoint. An endpoint is any device that can make or receive a call. Currently, BRTC supports WebRTC endpoints.

To register an endpoint, you can use the Endpoints API to create an endpoint and obtain a device token. This token is required to connect a device to Bandwidth's BRTC platform.

Currently, BRTC only supports WebRTC Endpoints, but we plan to support additional types of endpoints in the future. When you create an endpoint, you can specify the type of endpoint and any related metadata that may be required for Bandwidth to communicate with that endpoint.

WebRTC

For in-depth examples and code samples of building a WebRTC application using BRTC, check out our sample apps.

For the purposes of this quick start guide, we will cover the basics of handling inbound and outbound calls with a WebRTC endpoint.

Handle Inbound Calls

Register a WebRTC Endpoint

To register a WebRTC endpoint, you can use the Endpoints API to create an endpoint and obtain a device token. This token is required to connect a device to Bandwidth's BRTC platform.

Handle the Inbound PSTN Call

1. The Device establishes a connection with the BRTC websocket using a WebRTC Endpoint token
2. The customer receives an eligible notification that the Endpoint has negotiated with BRTC
3. Bandwidth receives an unsolicited inbound Call to a PSTN number associated with an application.
4. The customer receives an initiate event for this Call
5. The customer identifies an eligible Endpoint to <Connect> the Call with
   1. The customer is responsible for applying routing behaviors to pick an eligible Endpoint. BRTC will assist by communicating state changes, but the choice of which Endpoint is up to the customer.
6. Bandwidth connects the Call with the requested Endpoint
7. The WebRtc Device receives a stream available event which it may accept

Create an Outbound Call

1. The Device establishes a connection with the BRTC websocket using a WebRTC Endpoint token
2. The customer receives an eligible notification that the Endpoint has negotiated with BRTC
3. The WebRtc Device requests an outbound connection to PHONE_NUMBER +19191111111
4. The customer receives an outbound connection request containing
   1. The destination type: PHONE_NUMBER
   2. The destination id: +19191111111
   3. The Endpoint ID
   4. The Device ID
5. The customer approves of the outbound connection request by placing a Call using the Bandwidth calls API
   1. The customer picks a suitable from number and all related metadata and callback URLs
   2. The customer is responsible for keeping track of the relation between the created Call and the Endpoint that requested it by using the ids of both
   3. When creating a call, you can set the tag value to the Endpoint ID or Device ID that requested the call, or you can keep track of the association in your own database using the Call ID returned in the response of the Create Call API call
6. The outbound call is answered
7. The customer receives the answer event for the Call, which includes the Call ID and any metadata associated with the call, including the tag value if it was set during call creation
8. The customer looks up the association of this call id with the endpoint that requested it, and issues a <Connect> BXML verb with a destination of the Endpoint id that requested the Call.
9. Bandwidth connects the Call with the requested Endpoint
10. The WebRtc Device receives a stream available event which it may accept

note

An Endpoints ability to decline a stream available event is in progress, but upon implementation, will cause the PSTN leg to move on to the next BXML verb after <Connect> in the BXML document that issued the connect command. For this reason, a <Redirect> is advised to follow any <Connect> so that the customer will be prompted for the next verb again in reaction to the Endpoint's choice to accept or reject the media stream.

Ex:

<Response>
    <Connect>
        <Endpoint>e-12345678-90ab-cdef-1234-567890abcdef</Endpoint>
    </Connect>
    <Redirect>https://myapp.com/nextVerb</Redirect>
</Response>

In this example, if the Endpoint accepts the stream available event, the call will be connected to the Endpoint as normal.

If the Endpoint rejects the stream available event, the call will be redirected to https://myapp.com/nextVerb where the customer can issue new BXML commands to direct the call elsewhere.

If the endpoint accepts the stream available event but then disconnects, the call will also be redirected to https://myapp.com/nextVerb after the conversation between endpoint and PSTN caller, allowing the customer to direct the call elsewhere or end it as they see fit.

Your application logic can be used to determine how to handle each of these scenarios, but the use of a <Redirect> after a <Connect> is recommended to ensure that the customer has control over the call flow in each case.