CallClient Class
The CallClient provides the entry point to the calling functionality of the Sinch SDK. A CallClient can be acquired via the SinchClient.
Note: Do not instantiate CallClient, rather use the getCallClient() method in SinchClient. See the example below.
Constructor
CallClient
-
sinch
Parameters:
-
sinch
SinchClientThe parent object
Example:
//Get callClient from sinchClient
var sinchClient = new SinchClient(...);
var callClient = sinchClient.getCallClient();
//Add event listener
callClient.addEventListener(...);
Item Index
Methods
addEventListener
-
eventListener
Add event listeners to the callClient, multiple listeners can be added with this method. Listeners are processed in the order they're added. Listeners can be removed, using the CallClient.removeEventListener method.
Parameters:
-
eventListener
ObjectAn object containing a set of listeners for various actions
-
[onIncomingCall]
Function optionalCallback for incoming calls
-
Returns:
undefined
Example:
var myListener = {
onIncomingCall: function(callClient, call) { console.info(call); },
};
var callClient = sinchClient.getCallClient();
callClient.addEventListener(myListener);
alreadyInCall
-
msgObj
Check whether we're already in a call.
Parameters:
-
msgObj
MXPMessageObjIncoming invite describing the call
Returns:
undefined
Example:
callConference
-
conferenceId
-
[headers]
-
[customStream]
Calls a conference room, all calls connected to the same room will exchange voice traffic and can also be reached from PSTN. (Voice only)
Note: Remember to play the audio in an audio element. When adding the incoming audio source, remember to play back the stream, or use the attribute "autoplay" on the audio element.
Parameters:
-
conferenceId
StringThe conference room to call.
-
[headers]
Object optionalHeader object (map key-value)
-
[customStream]
MediaStream optionalCustom audio stream to transmit. If none is specified, the stream from the mic will be used.
Returns:
Call instance for adding event handlers and/or interacting with this call.
Example:
var callClient = sinchClient.getCallClient();
var call = callClient.callConference('some-conference-uuid');
var callListener = {
onProgressing: function(call): { }, //Call is progressing
onEstablished: function(call): { //Call is established
$('audio').attr('srcObject', call.incomingStream); //Add audio stream to audio element.
//NOTE: Remember to ensure audio element play back audio or has the "autoplay" attribute (see sample app)
},
onCallEnded: function(call): { } //Call is ended
}
call.addEventListener(callListener);
callGroup
-
groupName
Beta: Join a call group, works with both video and audio. Currently only p2p conferencing works, where each participant is streaming to all other participants.
Note: Remember to play the media in a audio/video element. When adding the incoming media source, remember to play back the stream, or use the attribute "autoplay" on the audio element.
Note: Also requires the "multiCall" capability set to true. For video, also set the "video" capability to true.
Parameters:
-
groupName
StringThe name of the group to join
Returns:
Call Group for adding event handlers related to this group conversation.
Example:
var callClient = sinchClient.getCallClient();
var call = callClient.callGroup('someGroupName'); //When sinchClient has started
groupCall.addEventListener({
onGroupLocalMediaAdded: function(stream) { // Local media stream is available for consumption
$('video#me').attr('srcObject', stream);
},
onGroupRemoteCallAdded: function(call) { // A new participant is ready
$('video#other').attr('srcObject', call.incomingStream);
},
onGroupRemoteCallRemoved: function(call) {
$('video#other').attr('src', '');
},
})
callPhoneNumber
-
phoneNumber
-
[headers]
-
[customStream]
Calls a phone number and terminate the call to the PSTN-network (Publicly Switched Telephone Network).
Note: Remember to play the audio in an audio element. When adding the incoming audio source, remember to play back the stream, or use the attribute "autoplay" on the audio element.
Parameters:
-
phoneNumber
StringThe phone number to call. The phone number should be given according to E.164 number formatting (http://en.wikipedia.org/wiki/E.164) and should be prefixed with a '+'. E.g. to call the US phone number 415 555 0101, it should be specified as "+14155550101", where the '+' is the required prefix and the US country code '1' added before the local subscriber number.
-
[headers]
Object optionalHeader object (map key-value)
-
[customStream]
MediaStream optionalCustom audio stream to transmit. If none is specified, the stream from the mic will be used.
Returns:
Call instance for adding event handlers and/or interacting with this call.
Example:
var callClient = sinchClient.getCallClient();
var call = callClient.callPhoneNumber('+46000000000');
var callListener = {
onProgressing: function(call): { }, //Call is progressing
onEstablished: function(call): { //Call is established
$('audio').attr('srcObject', call.incomingStream); //Add audio stream to audio element.
//NOTE: Remember to ensure audio element play back audio or has the "autoplay" attribute (see sample app)
},
onCallEnded: function(call): { } //Call is ended
}
call.addEventListener(callListener);
callSip
-
sipAddress
-
[headers]
-
[customStream]
Calls the user with the given SIP identity.
Note: Remember to play the audio in an audio element. When adding the incoming audio source, remember to play back the stream, or use the attribute "autoplay" on the audio element.
Parameters:
-
sipAddress
StringThe specific SIP identity of the user to call. May not be null or empty.
-
[headers]
Object optionalHeader object, contains a map key-value. Only string values are supported in native clients. Prefix header names with "x-".
-
[customStream]
MediaStream optionalCustom audio stream to transmit. If none is specified, the stream from the mic will be used.
Returns:
Call instance for adding event handlers and/or interacting with this call.
Example:
var callClient = sinchClient.getCallClient();
var call = callClient.callSip('alice@example.com');
var callListener = {
onProgressing: function(call): { }, //Call is progressing
onEstablished: function(call): { //Call is established
$('audio').attr('srcObject', call.incomingStream); //Add audio stream to audio element.
//NOTE: Remember to ensure audio element play back audio or has the "autoplay" attribute (see sample app)
},
onCallEnded: function(call): { } //Call is ended
}
call.addEventListener(callListener);
callUser
-
userId
-
[headers]
-
[customStream]
Calls the user with the given userId.
Note: Remember to play the audio in an audio element. When adding the incoming audio source, remember to play back the stream, or use the attribute "autoplay" on the audio element.
Parameters:
-
userId
StringThe specific id of the user to call. May not be null or empty.
-
[headers]
Object optionalHeader object, contains a map key-value. Only string values are supported in native clients.
-
[customStream]
MediaStream optionalCustom audio stream to transmit. If none is specified, the stream from the mic will be used.
Returns:
Call instance for adding event handlers and/or interacting with this call.
Example:
var callClient = sinchClient.getCallClient();
var call = callClient.callUser('magnus');
var callListener = {
onProgressing: function(call): { }, //Call is progressing
onEstablished: function(call): { //Call is established
$('audio').attr('srcObject', call.incomingStream); //Add audio stream to audio element.
//NOTE: Remember to ensure audio element play back audio or has the "autoplay" attribute (see sample app)
},
onCallEnded: function(call): { } //Call is ended
}
call.addEventListener(callListener);
connect
-
userId
-
[headers]
Calls a data user and opens a data channel only. (beta)
Note: Only tested in Chrome. Not for production.
Parameters:
-
userId
StringThe specific id of the user to call. May not be null or empty.
-
[headers]
Object optionalHeader object, contains a map key-value. Only string values are supported in native clients.
Returns:
Call instance for adding event handlers and/or interacting with this call.
Example:
var callClient = sinchClient.getCallClient();
var call = callClient.connect(username);
var callListener = {
onProgressing: function(call): { }, // Call is progressing
onEstablished: function(call): { },
onCallEnded: function(call): { }, // Call is ended
onDataChannelAdded: function(call, channel): { channel.write('hello world'); } // Data Channel was opened for ongoing call
}
call.addEventListener(callListener);
handleIncomingCall
-
msgObj
Handle incoming call.
Parameters:
-
msgObj
MXPMessageObjIncoming invite describing the call
Returns:
undefined
Example:
initStream
()
Initialize media streams, this is used to create the stream from the microphone. The stream will be cached; in order to avoid a question when making / receiving a call, run initStream() once when it's a good time in the application flow.
Note: This can be used to initialize the stream before it's needed, for example, during application loading.
Returns:
promise which resolves into a media stream
Example:
callClient.initStream.then(function() {
//user has accepted sharing the microphone, now show the user interface
});
removeEventListener
-
eventListener
Remove event lister objects from the callClient. Pass the same object as was used when adding the listeners.
Parameters:
-
eventListener
ObjectAn object containing a set of listeners for various actions, that has previously been added to this callClient
Returns:
undefined
Example:
callClient.addEventListener(myListener);
callClient.removeEventListener(myListener);