WebRTC API

WebRTC features

The WebRTC debug can be activated separately by the following method:

xc_webrtc.setDebug(sipml5level, event, handler)

Where: xc_webrtc.setIceUrls(urls) ————————–

Set a list of STUN/TURN servers, for example:

[{ url: 'stun:stun.l.google.com:19302'}, { url:'turn:turn.server.org’, username: ‘user’, credential:'myPassword'}]

webRTC Events

  • sipml5level refers to the SIPml5 library log level string as described on SIPml5 log level documentation,
  • event is a boolean value activating event logging (each event is prefixed by RE<<<),
  • handler is a boolean value activating logging of message handler subscription/unsubscription.

WebRTC on sample page

Once logged on the sample page, you can init the webRTC through the init button, follow events shown in the webRTC section and send and receive calls. You can terminate a call by the terminate button in the phone section. Attended transfer can be performed using xfer buttons. Hold and DTMF features are available via the webRTC API. You can receive or make up to 2 calls, answer and hold methods do their best to put other calls on hold when answering or hold the call which is not held (or resume the one which is held), but currently the SIPml5 session ids are not exposed, so you have to avoid getting in a situation where it’s not clear from the context what needs to be done, for example putting on hold two calls in the same time.

If really you want to interact between SIPml5 session and XUC calls, you can use SIP_CALL_ID which is exposed in xc_webrtc and also in PhoneEvent than can be received in XUC websocket. See Phone Events

Current browsers doesn’t allow media sharing without secure connections - https and wss. The xivoxc_nginx docker image contains the configuration required for loading the sample page over a secure connection using an auto-signed certificate. This certificate is automatically generated by the installation script. It is meant to be used only for test purposes, you should replace it by a signed certificate before switching to production. The sample page is available on the following address: https://MACHINE_IP:8443/sample

webRTC Methods

Once the cti login done, you can init the webRTC component by calling the xc_webrtc.init method.

xc_webrtc.init(name, ssl, websocketPort, token, remoteAudio, ip)

Legacy Init - it asks for line configuration and ICE configuration before starting webRTC connection.

  • name - user’s login to get the line details,
  • ssl - if set to true the wss is used,
  • websocketPort, ip - port and address for the webRTC websocket connection, when ip is not passed the xivo ip is used,
  • token - used when ssl is set to true, either reusing the CTI one, either create a new one, see Obtain authentication token
  • remoteAudio - id of the HTML5 audio element for remote audio player, if not passed ‘audio_remote’ is used. The element should look like:
<audio id="audio_remote" autoplay="autoplay"></audio>

xc_webrtc.initByLineConfig(lineCfg, name, ssl, websocketPort, token, remoteAudio, ip)

Same as legacy init, but without asking for line configuration as you pass it as pamameter.

  • lineCfg - user’s line associated retrieved through LineConfig object in Cti websocket
  • name - user’s login to get the line details,
  • ssl - if set to true the wss is used,
  • websocketPort, ip - port and address for the webRTC websocket connection, when ip is not passed the xivo ip is used,
  • token - used when ssl is set to true, either reusing the CTI one, either create a new one, see Obtain authentication token
  • remoteAudio - id of the HTML5 audio element for remote audio player, if not passed ‘audio_remote’ is used. The element should look like:
<audio id="audio_remote" autoplay="autoplay"></audio>

xc_webrtc.dial(destination)

Start a webRTC call to the destination.

xc_webrtc.answer(sipCallId)

Answer an incoming webRTC call. sipCallId is optional, but if you set it, you can explicitly answer a specific call.

Note

The library accepts as an optional parameter the SIP_CALL_ID, which are currently reported in events. See Phone Events

xc_webrtc.conference()

Can be called when there’s one call on hold and one active, then it resumes the call on hold and starts a 3-party conference hosted by the webrtc endpoint. It can be also used to resume a 3-party conference on hold.

xc_webrtc.hold(sipCallId)

Toggle hold on a webrtc call or a conference. A conference can be resumed either by new call of xc_webrtc.hold() or by a new call of xc_webrtc.conference().

sipCallId is optional, but if you set it, you can explicitly hold a specific call. At least one call will always be ongoing even if you try to have two established calls at a time.

Note

The library accepts as an optional parameter the SIP_CALL_ID, which are currently reported in events. See Phone Events

xc_webrtc.dtmf(key)

Send a DTMF.

xc_webrt.attendedTransfer(destination)

Start an attendedTransfer to the destination. This method designed to work with the AMI based transfer implemented by the XUC server, so it first puts current calls on hold and then starts a new call in an auto-answer mode.

xc_webrtc.compeleteTransfer()

Complete an attended transfer. It’s a simple wrapper of the Cti method introduced to complete the API of the xc_webrtc library.

xc_webrtc.setHandler(eventName, handler)

Set a handler for eventName from xc_webrtc.MessageType.

xc_webrtc.toggleMicrophone(sipCallId)

Disable or enable microphone for a specific call id

xc_webrtc.disableICE()

Disable ICE server use, only LAN addresses will be used in the SDP.

xc_webrtc.getIceUrls()

Sip Configuration

Get sip configuration

Retrieve the ice configuration currently applied.

Example:

[
    {
        "urls": [
            "stun:xivo-edge:3478"
        ]
    },
    {
        "urls": [
            "turn:xivo-edge:3478",
            "turns:xivo-edge:3478"
        ],
        "username": "1617284035",
        "credential": "1o...BeLqsBh9g="
    }
]

xc_webrtc.setIceUrls(urls)

Set a list of STUN/TURN servers, for example:

[{ url: 'stun:stun.l.google.com:19302'}, { url:'turn:turn.server.org’, username: ‘user’, credential:'myPassword'}]

webRTC Events

Set a list of STUN/TURN servers, for example:

[{ url: 'stun:stun.l.google.com:19302'}, { url:'turn:turn.server.org’, username: ‘user’, credential:'myPassword'}]

webRTC Events

There are four groups of events:

  • general,
  • register,
  • incoming,
  • outgoing.

List of associated events is defined in the xc_webrtc.General, xc_webrtc.Registration, xc_webrtc.Incoming, xc_webrtc.Outgoing. See the xc_webrtc.js on https://gitlab.com/xivo.solutions/xucserver/blob/master/app/assets/javascripts/xc_webrtc.js. The error state events contains a description in the reason field. Call establishment event contains caller or callee detail. Use the sample page to see some examples.