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.
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, video)¶
Start a webRTC call to the destination.
Warning
The video call support is currently an experimental feature and the API can change any time.
The ‘video’ parameter is optional, if omitted it’s considered as false and allows you to start an audio/video call.
Currently, multiple concurrent video calls are not supported, all video calls reuse the same video elements. The local
video element has to be created by the user of the API with id video-local
and a second video element for remote
video stream with id video-remote
.
xc_webrtc.answer()¶
Answer an incoming webRTC call.
Note
The library accepts as an optional parameter the session id, but these ids are not currently reported in events. This parameter is currently reserved for internal use.
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()¶
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().
Note
The library accepts as an optional parameter the session id, but these ids are not currently reported in events. This parameter is currently reserved for internal use.
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.disableICE()¶
Disable ICE server use, only LAN addresses will be used in the SDP.
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.