AWL.client Class
AWL.client class instance provides access to all the following non-telephony and telephony APIs:
Item Index
Methods
- addVideo
- answerCall
- cancelCall
- createLoopBackConnection
- disableLogging
- doHold
- doMute
- doUnHold
- doUnMute
- dropCall
- enableLogging
- endLoopBackConnection
- generateAppInstanceID
- getAlternateServerConfig
- getDeviceList
- getLoopBackStats
- getSdkVersion
- getStats
- getStunConfiguration
- isloggedIn
- isWebRTCSupported
- logIn
- logOut
- makeCall
- pauseVideo
- playVideo
- rejectCall
- removeVideo
- sendDTMF
- setConfiguration
- setDeviceIds
- setDomElements
- setLogObject
- setMediaStream
- setStunConfiguration
- tokenLogIn
- transferCall
Properties
- AWL_MSG_CALL_CONNECTED
- AWL_MSG_CALL_DISCONNECTED
- AWL_MSG_CALL_FAILED
- AWL_MSG_CALL_FAREND_UPDATE
- AWL_MSG_CALL_HELD
- AWL_MSG_CALL_IDLE
- AWL_MSG_CALL_INCOMING
- AWL_MSG_CALL_MAXCAP_REACHED
- AWL_MSG_CALL_PROGRESSING
- AWL_MSG_CALL_RINGING
- AWL_MSG_CALL_TRANSFER_FAILED
- AWL_MSG_DEVICEACCESS_FAILURE
- AWL_MSG_DUPLICATE_LOGIN
- AWL_MSG_FAIL_BACK_FAILED
- AWL_MSG_FAIL_BACK_SUCCESS
- AWL_MSG_FAIL_OVER_FAILED
- AWL_MSG_FAIL_OVER_SUCCESS
- AWL_MSG_FAILING_BACK
- AWL_MSG_FAILING_OVER
- AWL_MSG_LINK_ISSUE_DETECTED
- AWL_MSG_LOGGEDOUT
- AWL_MSG_LOGIN_EMPTYPASSWORD
- AWL_MSG_LOGIN_EMPTYTOKEN
- AWL_MSG_LOGIN_EMPTYUSERNAME
- AWL_MSG_LOGIN_FAILED
- AWL_MSG_LOGIN_GW_NOTCONFIGURED
- AWL_MSG_LOGIN_INVALID_TOKENTYPE
- AWL_MSG_LOGIN_SUCCESS
- AWL_MSG_LOGIN_WEBSOCKET_FAILURE
- AWL_MSG_LOOPBACK_CONN_CLOSED
- AWL_MSG_LOOPBACK_CONN_FAILED
- AWL_MSG_LOOPBACK_CONN_LINK_ISSUE
- AWL_MSG_LOOPBACK_CONN_SUCCESSFULL
- AWL_MSG_LOOPBACK_STATS_FAILURE
- AWL_MSG_RECONNECTING
- AWL_MSG_RELOGGED_IN
- AWL_MSG_SET_STUN_CONFIG_FAILED
- AWL_MSG_SET_STUN_CONFIG_SUCCESS
- AWL_MSG_SETCONFIG_FAILED
- AWL_MSG_SETCONFIG_SUCCESS
- AWL_MSG_SETDOM_FAILED
- AWL_MSG_SETDOM_SUCCESS
- AWL_MSG_TOKEN_RENEW_FAILED
- AWL_MSG_TOKEN_RENEW_SUCCESS
- AWL_MSG_WEBRTC_NOTSUPPORTED
- AWL_MSG_WEBRTC_SUPPORTED
- ESNA
- RESILIENCY
Methods
addVideo
-
arg1
This API is used to upgrade an ongoing audio call stream to a audio+video stream.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
answerCall
-
arg1
This API Answers an incoming call by creating WebRTC PeerConnection, answer Sdp generation and other signalling messages. This Api takes care of answering the call either as a audio/video call based on the incoming calltype and whether video is enabled locally using setDomElements API.
Parameters:
-
arg1
String- callId parameter(obtained through the callback functions 'onNewIncomingCall' or 'onCallStateChange')
cancelCall
-
arg1
This API is to cancel a dialled call before the call is answered and also resets the call session object properties
Parameters:
-
arg1
String- callId parameter(this can be obtained using the call object which is returned with makeCall API call )
createLoopBackConnection
()
This API serves for network stablity asssessment and is accomplished by creating a webRTC loopback connection between the browser and the webRTC gateway for audio and data(if respective flags are set to TRUE) streams seperately. This provides an easy way to assess the ability of customer network by doing on demand network assessment as well as a long lived, constant check of the network. Pre-requisite to usage of this API relay audio tag id should be specified in API setDomElements and login(registration) should have been done successfully using logIn API.
Example:
myWebRTC.createLoopBackConnection();
Note: The createLoopBackConnection API call would invoke the callback function which was passed as 'callback_onCallStateChanged' earlier in setConfiguration API with result(either 'CONST.AWL_MSG_LOOPBACK_CONN_SUCCESSFULL' or 'CONST.AWL_MSG_LOOPBACK_CONN_FAILED' or 'AWL_MSG_LOOPBACK_CONN_LINK_ISSUE') and reason associated with it.
disableLogging
()
This API disables browser console logging for displaying SDK API logs
doHold
-
arg1
This API pushes a call to held state for a audio/video call.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
doMute
-
arg1
This API pushes the WebRTC mic to mute state.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
Returns:
true -> indicates the API call is successful. false -> indicates the API call failed
doUnHold
-
arg1
This API retrieves a call from held to active state for a audio/video call.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
doUnMute
-
arg1
This API pushes the WebRTC mic to unmute state from mute condition.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
Returns:
true -> indicates the API call is successful. false -> indicates the API call failed
dropCall
-
arg1
This API disconnects a connected existing audio/video call and resets the call session object properties.
Parameters:
-
arg1
String- callId parameter(obtained through the callback functions 'onNewIncomingCall' or 'onCallStateChange')
enableLogging
()
This API enables browser console logging for displaying SDK API logs
endLoopBackConnection
()
This API terminates the network assessment loop back connection towards the WebRTC gateway.
generateAppInstanceID
()
String
This is utility API used to generate the application instanceID.
Note:
a) This API generates new appInstanceID for each invocation.
b) SDK will not persist the generated appInstanceID.
Returns:
getAlternateServerConfig
()
Object
This API returns the alternate server details if resiliency is supported and enabled at the server.
Returns:
This return object contains the alternate server details like IP address, domain, port and server type. If the returned object is null, then resiliency is either not supported or not enabled at the server.
getDeviceList
-
callback_onDeviceListRequested
This API is used to get all the available media devices attached to the system.
Note: The getDeviceList API call would invoke the callback function which is passed as mandatory parameter of this API.
Parameters:
-
callback_onDeviceListRequested
Object- callBack function which will be invoked once all the devices information is found.
getLoopBackStats
()
Array
This API generates and updates the below statistical parameters based on which network analzyer application shall determine the network stability. These parameters are accessible using the returned array reference.
- 'nowPLoss' - packet lost count in each second
- 'totPSent' - Total Packets Sent
- 'totPLost' - Total Packets Lost
- 'nowRTT' - Current Round Trip delay(Rtt)
- 'totPLossPercent' - Percentage of packet lost so far
- 'maxRTT' - Peak Round trip delay
- 'minRTT' - Min Round trip delay
- 'avgRTT' - Average Round trip delay
- 'totJitter' - Jitter Received (total)
- 'nowPLossPercent' - Observed packet Loss percentage in each second
Returns:
getSdkVersion
()
String
This API returns the Avaya IP Office WebRTC SDK version number being used
Returns:
getStats
-
arg1
This API is used to get the CallStatistics of that particular call which can be accessed using the returned array reference.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
Returns:
getStunConfiguration
()
Object
This API returns the STUN server configurations
Returns:
This return object contains the STUN server details like Stun server IP address/FQDN and port.
isloggedIn
()
Boolean
This API is used to check if the client is currently registered or not
Returns:
true -> indicates that the WebRtc user extension is already registered to Avaya IP Office. false -> indicates that the WebRtc user extension is not registered to Avaya IP Office yet.
isWebRTCSupported
()
Boolean
This API returns a boolean result indicating whether the browser(on which this API is called) has WebRTC capability support or not.
Returns:
true -> indicates that the browser supports WebRTC APIs. false -> indicates that the browser does not support WebRTC APIs
logIn
-
arg1
-
arg2
-
arg3
-
arg4
The WebRTC gateway supports two types of authentications for login:
- Internal authentication
- External authentication
Internal Authentication: In this type of authentication, WebRTC gateway expects IP Office user name or extension and user’s password from the AWL SDK. The gateway sends authentication request to IP Office with the client provided credentials. The client will be notified about the result of the authentication request once it gets the response from IP Office. In this case, gateway acts as proxy for the client and initiates IP Office user authentication request on-behalf of client.
Notes:
- The IP Office user name refers to Name field in IP Office Manager
- The IP Office extension refers to Extension field under User section in IP Office Manager
- The Password refers to User’s password. Not Login Code.
External Authentication: In this type of authentication, gateway expects the IP Office user name and authentication token from the client. The client should obtain the authentication token from the one-x server for a user name (Please refer the one-x open API documentations for details). When client wants token based authentication, client should inform the gateway that the authentication request is of token based type. When gateway receives token based authentication request, gateway contacts one-x server to obtain the IP Office user’s password corresponding to the token. If gateway obtains the password, it initiates regular IP Office user authentication over SIP channel.
Notes:
- The client passes the authentication token via the password parameter of login JSON request
- The client should inform the gateway about external authentication by setting token authentication flag in the login JSON request
- The one-x server must be running and functional to achieve external authentication
- The external authentication support is added mainly to support single-sign-on feature of clients.
- There is no fail-back login mechanism in case gateway fails to obtain IP Office user’s password from one-x.
This API registers the WebRTC client as SIP user with the supplied arguments to Avaya IP Office and it takes the userextension(arg1) and password(arg2) as input arguments for internal authentication.
Note: The logIn API call would invoke the registration state change callback function which was passed as 'callback_onRegistrationStateChanged' earlier in setConfiguration API with the result and reason associated with it. If resiliency is supported and enabled, then after successful login, authentication token will be passed to registration state change callback function.
Parameters:
-
arg1
String- SIP user extension
-
arg2
String- Respective user(i.e., arg1) password
-
arg3
String- Flag to instruct the gateway that allow SIP login even if extension is taken over by other client of same service type. The value must be either "true" or "false". If "true", gateway proceeds for SIP login even if any logged in client for the same extension If "false", gateway checks if any already loggedin client, proceeds for SIP login only if no already loggedin client. If any already logged in client, gateway returns error code and reason string containing the already loggedin client's user agent.
-
arg4
String- Flag to instruct the gateway that the 'password'(arg2) is a 'token' not password. Pass this argument as 'true' if the password is a token. If this argument is 'true', gateway contacts token authentication server to get SIP user's password. If this argument is 'false', gateway treats the 'arg2' as password and initiates normal SIP login.
logOut
()
This API unregisters the WebRTC client(which is registered earlier as SIP user using logIn API) from Avaya IP Office
Note: The logIn API call would invoke the registration state change callback function which was passed as 'callback_onRegistrationStateChanged' earlier in setConfiguration API with the result and reason associated with it.
makeCall
-
arg1
-
arg2
This API is used to dial out by passing the terminating DN(arg1) and the call type being either audio or video(arg2) and is responsible for creating WebRTC PeerConnection, Offer generation and other call setup signalling.
Parameters:
-
arg1
String- extension number to be dialed
-
arg2
String- callType (whether "video" or "audio" call)
Returns:
This return object represents the current call session's call object using which below subsequent APIs can be invoked to retrieve various info at different phases during the call.
1. getCallId() - Returns the unique call id used in this particular call session
2. getCallState() - Returns the current call state
3. getFarEndNumber() - Returns the FarEnd's number
4. getFarEndName() - Returns the FarEnd's full-name
5. getSipUri() - Returns the SipUri in string format
Example of return string format:
"sip:4001@192.0.2.0:5060"
6. getSubject() - Returns the Subject of the call if provided in the meeting
7. isAutoAnswer() - indicates whether the call is auto answered(true) and this is meaningful only when the call object acts as recipient
8. isVideoCall() - indicates whether the call is video type(true) or not(false). This could be useful particularly when there is a incoming call.
Note: The farEndName returned via getFarEndName() API will henceforth not contain the subject of the call if any, as it can be obtained using getSubject() API. When resiliency is supported and enabled , if the client is either in failing over,failing back or reconnecting state, then call will not be made and make Call API returns null.
pauseVideo
-
arg1
This API is to pause the local video stream. Caution: Pausing local video stream will have video paused effect on all the video calls only on 9.1 version where as from 10.0 version it shall be controllable against each call param arg1 is mandatory if used with 10.0 and later build version
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
Returns:
true -> indicates the API call is successful. false -> indicates the API call failed
playVideo
-
arg1
This API is to play the previously paused local video stream. Caution: Playing local video stream will have video played effect on all the video calls only on 9.1 version where as from 10.0 version the local video stream shall be controllable against each call param arg1 is mandatory if used with 10.0 and later build version
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
Returns:
true -> indicates the API call is successful. false -> indicates the API call failed
rejectCall
-
arg1
This API is to reject a incoming call and also resets the call session object properties.
Parameters:
-
arg1
String- callId parameter(obtained through the callback functions 'onNewIncomingCall' or 'onCallStateChange')
removeVideo
-
arg1
This API is used to downgrade an ongoing audio+video call stream to a audio only stream.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
sendDTMF
-
arg1
-
arg2
This API generates a DTMF Tone based on ‘arg2’ value and sends it across to the connected peer. DTMF Tones will be generated only when DTMF support is negotiated during a call(i.e., Between Browser and the peer endpoint) only Chrome browser (latest version) supports DTMF tone generation.
Parameters:
-
arg1
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or using the call object which is returned with makeCall API call)
-
arg2
Char-
- It should be one of possible ITU-T supported DTMF Tones( which are ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’, ‘0’, ‘*’, ‘#’ ).
-
setConfiguration
-
arg1
-
callback_onConfigChanged
-
callback_onRegistrationStateChanged
-
callback_onCallStateChanged
-
callback_onAuthTokenRenewed
This API is used to set configurational parameters in a object literal notation pattern('cfg' parameter as in below example) and four callback functions which would triggered upon any configuration changes, registration/unregistration state changes, callstate changes and token renewal. This API should be called before doing logIn API call. FIRST FOUR ARGUMENTS TO BE PASSED ARE MANDATORY while invoking setConfiguration API. For the first argument to be passed, the serviceType("phone" or "agent"), enableVideo(true or false), Gateway IP address or FQDN(Mandatory), Stun/Turn(Optional) server details, Application Data and disableResiliency details are to be filled as in the following object literal notation template('cfg'), along with the four callback functions callback_onConfigChanged, callback_onRegistrationStateChanged, callback_onCallStateChanged and callback_onAuthTokenRenewed which would be triggered upon any configuration changes, registration/unregistration state changes, callstate changes and on token renewal respectively. Out of all these fields in arg1 template, mandatory data to be filled is the Gateway IP address inorder to setup communication with the Avaya IP Office WebRTC Gateway(i.e., Signal Gateway component).
For the serviceType property, if set as Phone service(i.e., "phone") it provides client to be used as Avaya IP Office extension, with its own UI whereas if set as agentservice(i.e., "agent") it is better suited for scenarios where the telephony operations are controlled by CTI application.
For the AppData, appInstanceID is the instance Id of the application and should be unique for each instantiation of application or AWL SDK. The appInstanceID can be obtained from AWL SDK utility API generateAppInstanceID(). The appInstanceID is a MUST configuration and should be done by every AWL SDK based applications. The applicationID and applicationUA are optional configurations to be used by third-party application developers using AWL SDK. The applicationUA represents application name registered with Avaya and applicationID represents the application identity key obtained from Avaya after application registered with Avaya.
Note:
- Equinox Select Client (or any Client) must set the remembered/persisted appInstanceID again, when AWL SDK is re-instantiated during Fail-over or Fail-back.
- These two configurations are reserved for future usage.
By default, resiliency is supported at SDK.To disable resiliency support at SDK,applications have to set the disableResiliency property to true while passing the configuration parameter to setConfiguration API.If disableResiliency is set true,then AWL SDK will not renew the authentication token before it expires.Also,autologin using token during failover and failback will not be supported and the applications have to go for manual login during failover and failback.
Example:
var cfg = {
serviceType: "phone",
enableVideo: false,
Gateway: {ip: "192.0.2.0", port: "9443"},
Stunserver: {ip: "", port: "3478"},
Turnserver: {ip: "", port: "3478", user: "", pwd: ""},
AppData: {applicationID : "", applicationUA : "", appInstanceID : "" },
disableResiliency : false
};
myWebRTC.setConfiguration(cfg, onConfigChanged, onRegistrationStateChanged, onCallListener, onAuthTokenRenewed);
// cfg: arg1
// onConfigChanged: callback_onConfigChanged
// onRegistrationStateChanged: callback_onRegistrationStateChanged
// onCallListener: callback_onCallStateChanged
// onAuthTokenRenewed: callback_onAuthTokenRenewed
Example of 'callback_onCallStateChanged' class template:
var onCallListener = function(){
var _onNewIncomingCall = function(callId, callObj, autoAnswer){
// application logic here
}
var _onCallStateChange = function(callId, callObj, event){
// application logic here
}
var _onCallTerminate = function(callId, reason){
// application logic here
}
var _onLoopBackNotification = function(notification){
}
var _onVideoStreamsAvailable = function(callId, localStream, remoteStream){
// application logic here
}
var _onAudioStreamsAvailable = function(callId, localStream, remoteStream){
// application logic here
}
return{
onNewIncomingCall: _onNewIncomingCall,
onCallStateChange: _onCallStateChange,
onCallTerminate: _onCallTerminate,
onLoopBackNotification: _onLoopBackNotification,
onVideoStreamsAvailable: _onVideoStreamsAvailable,
onAudioStreamsAvailable: _onAudioStreamsAvailable
};
}
var callback_onCallStateChanged = new _onNewIncomingCall();
Note: The setConfiguration API call would invoke the configuration change callback function which was passed as 'callback_onConfigChanged' earlier with the result and reason associated with it.
Parameters:
-
arg1
Object- object literal notation pattern as in above example 'cfg' var.
-
callback_onConfigChanged
Object- callback function that would get triggered whenever configurations are modified (In above example, 'onConfigChanged' represents this parameter)
-
callback_onRegistrationStateChanged
Object- callback function that would get triggered whenever there's a change in the registration state (In above example, 'onRegistrationStateChanged' represents this parameter)
-
callback_onCallStateChanged
Object- callback function object that would trigger 'onCallStateChange' function (when a callstate occurs) or 'onNewIncomingCall' function (when there is a new incoming call arrives) or 'onCallTerminate' function(to indicate the call terminate reason, when a established call terminates) or 'onLoopBackNotification' function(notifications and alarms to be handle at application logic) or 'onVideoStreamsAvailable' function (when both local and remote video streams are available) or 'onAudioStreamsAvailable' function (when both local and remote audio streams are available) and this requires a module reveal pattern template to be used as in above example showing 'callback_onCallStateChanged's class template.
-
callback_onAuthTokenRenewed
Object- callback function object that would trigger 'onAuthTokenRenewed' function when authentication token renewal succeeds or fails (In above example, 'onAuthTokenRenewed’ represents this parameter)
setDeviceIds
-
arg1
This API is used to set Media Devices obtained by getDeviceList API Call
Example:
var dIds = {
audioInputID : "", - should pass the audio input device id value here
videoInputID: "", - should pass the video input device id value here
audioOutputID: "", - should pass the audio output device id value here and this tag would be used to attach the remote audio stream to the user interface
defaultId : true
};
myWebRTC.setDeviceIds(dIds);
|
|
V
arg1
Parameters:
-
arg1
Object- object literal notation pattern as in above example 'dIds' var.
setDomElements
-
arg1
This API used to set html5 video media dom elements (i.e., video tag IDs passed in arg1) which would be used to attach WebRTC video streams of local and remote video by the SDK during a video call. __ALL THE PARAMETERS TO BE PASSED ARE MANDATORY.__This API should be used only when a pair of DOM elements (local & remote) is fixed across multiple calls to show local & remote video stream in it, i.e. DOM elements should be set before any call happens. At any point of call, the active call's stream will be attached to the DOM element and it will be re-used if the active call session changes. If the application requires dynamic video stream control to attach it to the DOM element on fly, "onVideoStreamsAvailable" callback approach should be used which works per call basis.
Example:
var cfg = {
localVideo : "", -should pass the video tag's id value here and this tag would be used to attach the local video stream to the user interface
remoteVideo : "" -should pass the video tag's id value here and this tag would be used to attach the remote video stream to the user interface
};
myWebRTC.setDomElements(cfg);
|
|
V
arg1
Note: The setDomElements API call invokes the configuration change callback function which was passed as 'callback_onConfigChanged' earlier in setConfiguration API with the result and reason associated with it.
Parameters:
-
arg1
Object- object literal notation pattern as in above example 'cfg' var.
setLogObject
-
arg1
This API enables SDK logging to use any JS framework provided logging object instead of console logging Unless this API is used, default logging will be console logging.
Example:
myWebRTC.setLogObject($log);
|
|
V
arg1
Parameters:
-
arg1
Object- Logging Object
setMediaStream
-
arg1
-
arg2
-
arg3
-
arg4
This API is to attach the video media streams with HTML5 video media Elements provided by the application. All the params are mandatory.It is mandatory for the application to call this API if DOM elements are not initially set using setDomElements API.
Parameters:
-
arg1
String- domElement parameter is HTML5 video media Element's ID or HTML5 video media Element to which the stream has to be attached
-
arg2
String- Stream parameter which is obtained by the call object which is returned with makeCall API call or using the stream parameter obtained by the call state change callback function ‘onVideoStreamsAvailable’
-
arg3
String- callId parameter(obtained by the call state change callback functions 'onNewIncomingCall' or 'onCallStateChange' or 'onVideoStreamsAvailable' or using the call object which is returned with makeCall API call)
-
arg4
String- domType parameter which indicates the stream type i.e "localVideo" or "remoteVideo"
setStunConfiguration
-
arg1
This API is used to configure STUN server details by the application any-time after call to login(). Subsequent calls shall use new STUN server details.
Example:
var stunServer = {ip: "example.com", port: "3478"};
var result = myWebRTC.setStunConfiguration(stunServer);
if(result === "AWL_MSG_SET_STUN_CONFIG_SUCCESS"){
console.log("Successfully configured STUN settings");
}else{
console.log("Could not configure STUN settings. Re-check the values");
}
Parameters:
-
arg1
Object- object literal notation pattern as in above example 'stunServer' var.
Returns:
Possible results that could be passed are: AWL_MSG_SET_STUN_CONFIG_SUCCESS AWL_MSG_SET_STUN_CONFIG_FAILED
tokenLogIn
-
arg1
-
arg2
-
arg3
-
arg4
This API registers the WebRTC client as SIP user with the supplied arguments to Avaya IP office and it takes userextension(arg1), authentication token(arg2), type of authentication token(arg3) as mandatory arguments. The authentication token can be of two types: ESNA and RESILIENCY. The client should obtain esna token from the one-x server for a user name (Please refer the one-x open API documentations for details). When gateway receives esna token based authentication request, gateway contacts one-x server to obtain the IP Office user’s password corresponding to the token. If gateway obtains the password, it initiates regular IP Office user authentication over SIP channel. The client can obtain resiliency token from AWL SDK.It first obtains the resiliency token from the response object passed in the registration state change callback function 'callback_onRegistrationStateChanged' when it successfully logs in to resilient server with user password via the logIn API. The client has to update the resiliency token whenever it is renewed. It can obtain the renewed token via the response object passed in authentication token renewed callback function 'callback_onAuthTokenRenewed'.
Parameters:
-
arg1
String- SIP user extension
-
arg2
String- Authentication token
-
arg3
String- Type of the authentication token. The supported token types are "RESILIENCY" and "ESNA".
-
arg4
String- Flag to instruct the gateway that allow SIP login even if extension is taken over by other client of same service type. The value must be either "true" or "false". If "true", gateway proceeds for SIP login even if any logged in client for the same extension If "false", gateway checks if any already loggedin client, proceeds for SIP login only if no already loggedin client. If any already logged in client, gateway returns error code and reason string containing the already loggedin client's user agent.
transferCall
-
arg1
-
arg2
-
arg3
This API is used to transfer call by dialing out a new call or merging two existing calls.
Parameters:
-
arg1
String- extension or callId of the call to be transferred
-
arg2
String- CallId of the exsiting call
-
arg3
String- type of transfer (attended/UnAttended)
Properties
AWL_MSG_CALL_CONNECTED
String
final
indicates that the call is currently in CONNECTED state
AWL_MSG_CALL_DISCONNECTED
String
final
indicates that the call is currently in DISCONNECTED state
AWL_MSG_CALL_FAILED
String
final
indicates that the call has FAILED for some reason
AWL_MSG_CALL_FAREND_UPDATE
String
final
indicates that during a call, farend's number is UPDATED
AWL_MSG_CALL_HELD
String
final
indicates that the call is currently in HELD state
AWL_MSG_CALL_IDLE
String
final
indicates that a call object current state is IDLE and is available for dialing outgoing call or receiving a incoming call
AWL_MSG_CALL_INCOMING
String
final
indicates a INCOMING call state
AWL_MSG_CALL_MAXCAP_REACHED
String
final
indicates that the current call is denied due to maximum allowed concurrent call limit of three is reached already
AWL_MSG_CALL_PROGRESSING
String
final
indicates that the call is progressing with early media. when early media received from gateway, call is connected temporarily and User may need to enter account code in this state.
AWL_MSG_CALL_RINGING
String
final
indicates that the far end is in RINGING state
AWL_MSG_CALL_TRANSFER_FAILED
String
final
indicates that the call TRANSFER FAILED and Existing call connection will be retained.This is same as AWL_MSG_CALL_CONNECTED state except the transfer failure notifcation.
AWL_MSG_DEVICEACCESS_FAILURE
String
final
indicates logIn(arg1, arg2) API call failure due to audio(Mic) or video(Camera) device access failure and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_DUPLICATE_LOGIN
String
final
indicates a duplicate logIn(arg1, arg2) request is received when the SIP extension is already registered and this could be a possible result value of the response object(i.e., resp.result) passed in the registration state change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_FAIL_BACK_FAILED
String
final
indicates that fail-back is not successful and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_FAIL_BACK_SUCCESS
String
final
indicates that client has successfully failed back and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_FAIL_OVER_FAILED
String
final
indicates that fail-over is not successful and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_FAIL_OVER_SUCCESS
String
final
indicates that client has successfully failed over and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_FAILING_BACK
String
final
indicates that client is failing back to alternate server and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_FAILING_OVER
String
final
indicates that client is failing over to alternate server and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LINK_ISSUE_DETECTED
String
final
indicates there is a link issue between the SDK and WebRTC Gateway(i.e., no keepalive message received for about 180seconds from WebRTC Gateway) and this could be a possible result value of the response object(i.e., resp.result) passed in the registration state change callback function 'callback_onRegistrationStateChanged'. This shall be further used in UI to display link issue and also let take corrective action.
AWL_MSG_LOGGEDOUT
String
final
indicates logOut() API call is successfull and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_EMPTYPASSWORD
String
final
indicates logIn(arg1, arg2) API call failure due to empty password and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_EMPTYTOKEN
String
final
indicates tokenLogIn(arg1, arg2, arg3) API call failure due to empty token and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_EMPTYUSERNAME
String
final
indicates logIn(arg1, arg2) or tokenLogIn(arg1, arg2, arg3) API call failure due to empty username and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_FAILED
String
final
indicates logIn(arg1, arg2) API call failure and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_GW_NOTCONFIGURED
String
final
indicates logIn(arg1, arg2) API call failure due to gateway ipaddress not configured correctly and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_INVALID_TOKENTYPE
String
final
indicates tokenLogIn(arg1, arg2, arg3) API call failure due to invalid token type and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_SUCCESS
String
final
indicates logIn(arg1, arg2) API call is successfull and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOGIN_WEBSOCKET_FAILURE
String
final
indicates logIn(arg1, arg2) API call failure or registration failure due to websocket connectivity failure and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_LOOPBACK_CONN_CLOSED
String
final
indicates that the loop back is closed
AWL_MSG_LOOPBACK_CONN_FAILED
String
final
indicates that the loop back connection to WebRTC gateway failed
AWL_MSG_LOOPBACK_CONN_LINK_ISSUE
String
final
indicates that a established loop back connection has link issue detected
AWL_MSG_LOOPBACK_CONN_SUCCESSFULL
String
final
indicates that the loop back connection to WebRTC gateway is created succesfully
AWL_MSG_LOOPBACK_STATS_FAILURE
String
final
indicates failure while fetching stats on the loop back connection
AWL_MSG_RECONNECTING
String
final
indicates that connection to the server is lost and the client is attempting to reconnect to the server.This could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_RELOGGED_IN
String
final
indicates that client is re-logged in to the server and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onRegistrationStateChanged'.
AWL_MSG_SET_STUN_CONFIG_FAILED
String
final
indicates API call of setStunConfiguration(arg1) failed.
AWL_MSG_SET_STUN_CONFIG_SUCCESS
String
final
indicates API call of setStunConfiguration(arg1) is successful.
AWL_MSG_SETCONFIG_FAILED
String
final
indicates API call of setConfiguration(arg1, arg2, arg3, arg4) has failed and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onConfigChanged'.
AWL_MSG_SETCONFIG_SUCCESS
String
final
indicates API call of setConfiguration(arg1, arg2, arg3, arg4) is successful and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onConfigChanged'.
AWL_MSG_SETDOM_FAILED
String
final
indicates API call of setDomElements(arg1) has failed and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onConfigChanged'.
AWL_MSG_SETDOM_SUCCESS
String
final
indicates API call of setDomElements(arg1) is successful and this could be a possible result value of the response object(i.e., resp.result) passed in the configuration change callback function 'callback_onConfigChanged'.
AWL_MSG_TOKEN_RENEW_FAILED
String
final
indicates failure while renewing the authentication token and this could be a possible result value of the response object (i.e., resp.result) passed in the configuration change callback function 'callback_onAuthTokenRenewed’.
AWL_MSG_TOKEN_RENEW_SUCCESS
String
final
indicates that authentication token is successfully renewed and this could be a possible result value of the response object (i.e., resp.result) passed in the configuration change callback function 'callback_onAuthTokenRenewed’.
AWL_MSG_WEBRTC_NOTSUPPORTED
String
final
indicates that the browser does not support WebRTC APIs and this could be a possible return value for isWebRTCSupported API call
AWL_MSG_WEBRTC_SUPPORTED
String
final
indicates that the browser does support WebRTC APIs and this could be a possible return value for isWebRTCSupported API call
ESNA
String
final
this could be a possible argument value of the authentication type (i.e., authType) passed in the tokenLogIn(arg1, arg2, arg3) API.
RESILIENCY
String
final
this could be a possible argument value of the authentication type (i.e., authType) passed in the tokenLogIn(arg1, arg2, arg3) API.
Events
callback_onAuthTokenRenewed
This callback function parameter(as arg5 parameter) used in setConfiguration API and this has to be implemented at the application level. This would be invoked when resiliency is enabled (resiliency support is enabled at server and not disabled by the client application) and renewal of authentication token succeeds or fails.If the it fails, then auto login using token will not be supported during failover and failback and the applications have to either relogin or go for manual login during failover and failback.This callback function will be triggered with response object(arg1) containing a result(arg1.result) and reason(arg1.reason). The response object will also contain the authentication token(arg1.authToken) when the token renewal succeeds. The authentication token is an object containing the token(arg1.authToken.token) and its expiration time(arg1.authToken.expiry).Possible result(string constants - resp.result) that could be passed in this callback function are
AWL_MSG_TOKEN_RENEW_SUCCESS
AWL_MSG_TOKEN_RENEW_FAILED
Below example is a sample implementation of 'callback_onAuthTokenRenewed' (i.e., onAuthTokenRenewed) function at the application level:
function onAuthTokenRenewed(resp){
console.log('\n onAuthTokenRenewed :: RESULT = ' + resp.result);
console.log('\n onAuthTokenRenewed :: reason = ' + resp.reason);
if(resp.result === "AWL_MSG_TOKEN_RENEW_SUCCESS"){
if(typeof(resp.authToken)!=="undefined" && resp.authToken!== null){
var token = resp.authToken.token;
var expiry = resp.authToken.expiry;
//logic code
}
}else{
//logic code
}
}
Event Payload:
-
resp
Object- this object could be used to retrieve result and reason properties further. These two properties are string constants. When token renewal is successful, this resp object will also contain 'authToken' property. 'authToken' is an object which can be used to retrieve token and expiry properties.
callback_onCallStateChanged
This is the callback function's instance that is used in setConfiguration API(as arg4 parameter) and this has to be implemented at the application level. This callback function's instance would be used to invoke onNewIncomingCall function by the SDK itself whenever there is a new incoming call or if any change in the call state happens the SDK would invoke onCallStateChange function. This implementation has to follow the revealing Model Pattern as in the below example implementation to implement the following functions.
1. onNewIncomingCall(arg1, arg2, arg3)
2. onCallStateChange(arg1, arg2, arg3)
3. onCallTerminate(arg1, arg2)
4. onLoopBackNotification(arg1)
5. onVideoStreamsAvailable(arg1, arg2, arg3)
6. onAudioStreamsAvailable(arg1, arg2, arg3)
onNewIncomingCall(arg1, arg2, arg3) This application level implemented function would be invoked by the SDK whenever there's a incoming call to this client and this function's parameters are described below.
arg1 - this is the unique callId used in the current call session. This has to be stored at the application level inorder to track a call session and this has to be passed as an argument in all the telephony APIs(except makeCall API) further.
arg2 - this is the call object used in the current call session. With this, application can get additional call information like callId, current call state, farend's number, farend's full-name, farend's SipUri, subject of the call if any, whether the call is auto answered by the SDK itself and whether a videocall is attempted or received with below APIs respectively.
1. getCallId()
2. getCallState()
3. getFarEndNumber()
4. getFarEndName()
5. getSipUri()
6. getSubject()
7. isAutoAnswer()
8. isVideoCall()
arg3 - this is the autoAnswer flag, if setup to true indicates the call is autoanswered by the SDK itself and
if set to false, it is left to the application to take the control of the call session further.
onCallStateChange(callId, callObject, currentCallState) This application level implemented function would be invoked by the SDK whenever there's a change in the call state and this function's parameters are described below.
arg1 - this is the unique callId used in the current call session. This has to be stored at the application level inorder to track a call session and this has to be passed as an argument in all the telephony APIs(except makeCall API) further.
arg2 - this is the call object used in the current call session. With this, application can get additional call information like callId, current call state, farend's number, farend's full-name, farend's SipUri, subject of the call if any, whether the call is auto answered by the SDK itself and whether a videocall is attempted or received with below APIs respectively.
1. getCallId()
2. getCallState()
3. getFarEndNumber()
4. getFarEndName()
5. getSipUri()
6. getSubject()
7. isAutoAnswer()
8. isVideoCall()
arg3 - this reflects the current call state of that particular call.
Below are possible call state values(String constant) that this parameter 'arg3' can hold:
AWL_MSG_CALL_IDLE
AWL_MSG_CALL_CONNECTED
AWL_MSG_CALL_DISCONNECTED
AWL_MSG_CALL_FAILED
AWL_MSG_CALL_INCOMING
AWL_MSG_CALL_RINGING
AWL_MSG_CALL_HELD
AWL_MSG_CALL_FAREND_UPDATE
AWL_MSG_CALL_MAXCAP_REACHED
onCallTerminate(arg1, arg2) This application level implemented function would be invoked by the SDK whenever a call disconnects and this function takes following parameters:
arg1 - this is the call-id of the call object used in the current call session.
arg2 - string indicating the call termination reason.
Application shall clean up objects for this call after receiving this onCallTerminate event.
onLoopBackNotification(arg1) This application level implemented function would be invoked by the SDK during relay service and notifies any of the below predefined alarms(string)
arg1 - this is a notification alarm parameter. With this, application can get information about the loopback connection status
Below are possible predefined alarm values(String constant) that this parameter 'arg1' can hold: AWL_MSG_LOOPBACK_CONN_SUCCESSFULL AWL_MSG_LOOPBACK_CONN_FAILED AWL_MSG_LOOPBACK_CONN_LINK_ISSUE AWL_MSG_LOOPBACK_CONN_CLOSED AWL_MSG_LOOPBACK_STATS_FAILURE
onVideoStreamsAvailable(callId, localStream, remoteStream) This application level implemented function will be invoked by the SDK whenever local and remote video streams are available and the application has registered for this event. This callback function is invoked only once per call i.e. when the call is connected for the first time. After retrieving the media streams, it is mandatory for the application to attach the streams to the respective DOM elements using setMediaStream API. This event is not triggered if setDomElements API is called initially as WebRTC video streams of local and remote video would be attached to the respective DOM elements (set in setDomElements API) by the SDK.The application should register to this callback if it requires dynamic video stream control to attach it to the DOM element on fly i.e., DOM elements need not be fixed across multiple calls to show local and remote video streams. But if the application requires a pair of DOM elements(local & remote) to be fixed across multiple calls i.e., to have the active call’s stream to be attached to the DOM element at any point of call, then the application shall use setDomElements API to set the HTML5 video media DOM elements.
callId - this is the call id of the call object used in the current call session.
localStream - local video stream
remoteStream - remote video stream
onAudioStreamsAvailable(callId, localStream, remoteStream) This application level implemented function will be invoked by the SDK whenever local and remote audio streams are available and the application has registered for this event.The audio streams are already attached to the DOM elements by the SDK.This callback is provided for notification purpose only and not for audio play.This callback function is invoked only once per call i.e. when the call is connected for the first time.
callId - this is the call id of the call object used in the current call session.
localStream - local audio stream
remoteStream - remote audio stream
Below example is a sample implementation of 'callback_onCallStateChanged(i.e., onCallListener)' function at the application level:
Example:
var CallListener = function () {
var _onNewIncomingCall = function (callId, callObj, autoAnswer) {
console.log("onNewIncomingCall : getFarEndNumber = "+callObj.getFarEndNumber());
console.log("onNewIncomingCall : getSipUri = "+callObj.getSipUri());
console.log("onNewIncomingCall : autoAnswer = "+autoAnswer);
if (callObj1 === null) {
callObj1 = callObj;
callmap[callObj1.getCallId()] = callObj1;
}
};
var _onCallStateChange = function (callId, callObj, event) {
if (typeof(callmap[callObj.getCallId()]) === 'undefined') {
if (callObj1 === null) {
callObj1 = callObj;
callmap[callObj1.getCallId()] = callObj1;
}
}
if (callObj.getCallId() === callObj1.getCallId()) {
switch (callObj1.getCallState()) {
case "AWL_MSG_CALL_IDLE":
// state specific handling code
break;
case "AWL_MSG_CALL_CONNECTED":
// state specific handling code
break;
case "AWL_MSG_CALL_RINGING":
// state specific handling code
break;
case "AWL_MSG_CALL_DISCONNECTED":
// state specific handling code
break;
case "AWL_MSG_CALL_FAILED":
// state specific handling code
break;
case "AWL_MSG_CALL_INCOMING":
// state specific handling code
break;
case "AWL_MSG_CALL_HELD":
// state specific handling code
case "AWL_MSG_CALL_FAREND_UPDATE":
// state specific handling code(For example update far end DN and sipUri information)
break;
default:
}
}
}
var _onCallTerminate = function(callId, reason){
//application logic to display call terminate reason
}
var _onLoopBackNotification = function(notification){
//application logic to handle notifications and alarms from the loopback connection
}
var _onVideoStreamsAvailable = function(callId, localStream, remoteStream){
//application logic to handle the retrieved streams
}
var _onAudioStreamsAvailable = function(callId, localStream, remoteStream){
//application logic to handle the retrieved streams
}
return{
onNewIncomingCall: _onNewIncomingCall,
onCallStateChange: _onCallStateChange,
onCallTerminate: _onCallTerminate,
onLoopBackNotification: _onLoopBackNotification,
onVideoStreamsAvailable: _onVideoStreamsAvailable,
onAudioStreamsAvailable: _onAudioStreamsAvailable
};
};
var onCallListener = new CallListener();
callback_onConfigChanged
This callback function parameter(as arg2 parameter) used in setConfiguration API and this has to be implemented at the application level. This would be invoked whenever config change or DOM Element change is attempted using setConfiguration API and this callback function will be triggered with response object(arg1) containing a result(arg1.result) and reason(arg1.reason) for the configuration change attempted with setConfiguration API call. Possible result(string constants - resp.result) that could be passed in this callback function are
AWL_MSG_SETCONFIG_SUCCESS
AWL_MSG_SETCONFIG_FAILED
AWL_MSG_SETDOM_SUCCESS
AWL_MSG_SETDOM_FAILED
Below example is a sample implementation of 'callback_onConfigChanged'(i.e., onConfigChanged) function at the application level:
function onConfigChanged(resp){
console.log('\n onConfigChanged :: RESULT = ' + resp.result);
console.log('\n onConfigChanged :: reason = ' + resp.reason);
}
Event Payload:
-
resp
Object- this object could be used to retrieve result and reason properties further. All the properties are string constants.
callback_onDeviceListRequested
This callback function parameter(as arg1 parameter) is used in getDeviceList API and this has to be implemented at the application level. This would be invoked whenever information of all the devices is found as requested using getDeviceList API and this callback function will be triggered with response object(arg1) containing a list of media devices and their information i.e. ID and label of all the media devices.
Below example is a sample implementation of 'callback_onDeviceListRequested’ (i.e., onDeviceListRequested)' function at the application level:
Event Payload:
-
resp
Object- this object could be used to retrieve the ID and label of all the media devices.
Example:
function onDeviceListRequested(deviceList){
if(deviceList.length !== 0){
$.each(deviceList, function (index, value) {
if(value[0] === "audioinput"){
//logic code
}else if(value[0] === "videoinput"){
//logic code
}else if(value[0] === "audiooutput"){
//logic code
}
});
}
}
callback_onRegistrationStateChanged
This callback function is the parameter(as arg3 parameter) used in setConfiguration API and this has to be implemented at the application level. This callback function will be triggered whenever there's a change in the registration/unregistration state or when there is a websocket connectivity failure. The response object(arg1) would contain a result(arg1.result) and reason(arg1.reason). When resiliency is enabled and supported, the response object would also contain authentication token(arg1.authToken) on successful login or fail-over or fail-back. Possible result(string constants - resp.result) that could be passed in this callback function are
AWL_MSG_LOGIN_EMPTYUSERNAME
AWL_MSG_LOGIN_EMPTYPASSWORD
AWL_MSG_LOGIN_EMPTYTOKEN
AWL_MSG_LOGIN_GW_NOTCONFIGURED
AWL_MSG_LOGIN_SUCCESS
AWL_MSG_LOGIN_FAILED
AWL_MSG_LOGIN_WEBSOCKET_FAILURE
AWL_MSG_LINK_ISSUE_DETECTED
AWL_MSG_DEVICEACCESS_FAILURE
AWL_MSG_LOGGEDOUT
AWL_MSG_FAILING_OVER
AWL_MSG_FAILING_BACK
AWL_MSG_FAIL_OVER_SUCCESS
AWL_MSG_FAIL_BACK_SUCCESS
AWL_MSG_FAIL_OVER_FAILED
AWL_MSG_FAIL_BACK_FAILED
AWL_MSG_RECONNECTING
AWL_MSG_RELOGGED_IN
AWL_MSG_LOGIN_INVALID_TOKENTYPE
Below example is a sample implementation of 'callback_onRegistrationStateChanged'(i.e., onRegistrationStateChanged) function at the application level:
function onRegistrationStateChanged(resp){
console.log('\n onRegistrationStateChange :: RESULT = ' + resp.result);
console.log('\n onRegistrationStateChange :: reason = ' + resp.reason);
if(resp.result === "AWL_MSG_LOGIN_SUCCESS") {
var authToken = resp.authToken.token;
var expiryTime = resp.authToken.expiry;
//logic code
}
else{
//logic code
}
}
Event Payload:
-
resp
Object- this object could be used to retrieve result and reason properties further. These two properties are string constants. When resiliency is enabled and supported, the resp object will have authToken property on successful login or fail-over or fail-back. 'authToken' is an object which can be used to retrieve token and expiry properties.