#Make and receive WebRTC calls

#Prerequisites

1. An OAuth 2.0 client
2. An access token

#Overview

This API makes it possible to register a WebRTC terminal (or just Terminal) with our (voice) core, and then use it to make and receive calls just like a mobile phone does.

In other words, the API enables development of a software phone fully integrated with our core.

To access this API, your credentials must include call.control.answer_and_initiate scope.

#The API

The API is implemented as a gRPC service exchanging a specific set of Protocol Buffer messages with your Terminal.

To register your Terminal with our core, you can use one of the two methods:

• Pipe()
• MultiPipe()

Both methods serve the same purpose, but there is also a difference.

• If you want to handle multiple ongoing calls simultaneously, use MultiPipe()
• For a single call at a time, use Pipe()

Both methods receive and/or return a stream of WebTerminalMessages (two-way streaming).

A WebTerminalMessage is a structure used to exchange messages between a Terminal and our core (see proto).

For example, if you:

1. register your Terminal (by calling either Pipe or MultiPipe)
2. initiate a call by pushing a WebTerminalMessage that contains an Offer to our core
3. receive a WebTerminalMessage from our core containing Ringing followed by an Answer

then

4. your Terminal will know that the callee's phone¹ was first ringing, and then the callee answered the call.

¹ or another Terminal

In this manner, you are able to build quite a sophisticated application with the help of this API.

#Example code

The examples below merely demonstrate how to consume this API without prying into the logic of your application.

In other words, they demonstrate how to

• create a Terminal
• push an Offer to the core
• receive messages from the core

For Java example, click here.

# Access token must be obtained via the client credentials flow
grpcurl \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"\
  -import-path . \
  -proto wgtwo/webterminal/v0/webterminal.proto \
  -d '
  {
      call_id = "b5289ac4-d254-4d75-8b45-a8c5f5cf47b0"
      offer = {
          sdp="",
          msisdn = {
              e164 = "+1234567890"
          }
      }
  }
  ' \
  api.wgtwo.com:443 \
  wgtwo.webterminal.v0.WebTerminalService/Pipe

package com.wgtwo.examples.thirdpartydev.webterminal

import com.wgtwo.api.common.Environment
import com.wgtwo.api.v0.common.PhoneNumberProto
import com.wgtwo.api.util.auth.Channels
import com.wgtwo.api.util.auth.BearerToken
import com.wgtwo.api.v0.webterminal.WebTerminalMessage
import com.wgtwo.api.v0.webterminal.WebTerminalServiceGrpcKt
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.onCompletion
import kotlinx.coroutines.runBlocking
import java.util.*

private val channel = Channels.createChannel(Environment.SANDBOX)
private val credentials =
    BearerToken { "MY_ACCESS_TOKEN" } // Add your _client credentials_ access token (not user access token)
private val stub = WebTerminalServiceGrpcKt.WebTerminalServiceCoroutineStub(channel)
    .withCallCredentials(credentials)

@ExperimentalCoroutinesApi
fun main() {
    // your calles's MSISDN goes here
    val to = "1234567890"

    // your SDP goes here
    val sdp = ""

    // Pipe() ignores callId, but it's mandatory for MultiPipe()
    val callId = UUID.randomUUID().toString()

    // building Offer
    val toPhone = PhoneNumberProto.PhoneNumber.newBuilder().setE164(to).build()
    val offer = WebTerminalMessage.newBuilder().apply {
        offerBuilder.also {
            it.msisdn = toPhone
            it.sdp = sdp
        }
        this.callId = callId
    }.build()

    val requests = flow<WebTerminalMessage> {
        emit(offer)
    }

    runBlocking {
        stub.pipe(requests).onCompletion {
            println("stream closed")
        }.catch { t ->
            println("got error $t")
        }.collect {
            println("got message $it")
        }
    }
}

#Common scenarios

Depending on the method used to register a WebRTC terminal, call_id in the scenarios below is either ignored (Pipe) or mandatory (MultiPipe).

call_id is basically a random UUID either created by Terminal or by the core.

#Initiating a call from a WebRTC terminal

#Receiving an incoming call from the core

#Observing status

Pipe(): call_id in Idle is empty as these messages are about the associated msisdn.

MultiPipe(): call_id indicates the call in question, for your Terminal to know which particular call has started/ended

#Transferring call to Terminal

Upon reception of an InCall notification, Terminal can transfer the call to itself by sending a new Offer to the core

#Transferring call to the mobile terminal

Whenever in a call, Terminal can transfer it to the associated mobile phone by sending {Action{ToPhone{}} message to the core.

#ICE

Terminal may send its candidates to the core within an SDP of Offer or Answer. WG2 media servers are on public Internet and will report its candidates in SDP.

#Renegotiating SDP

During an ongoing call, Terminal must be prepared to receive (and handle) Offer with a new SDP even though the Offer/Answer exchange has completed.

#Concepts

• WebRTC basics
• gRPC concepts
• Kotlin gRPC tutorial
• Java gRPC stubs