VoxEngine
Methods
addEventListener(appevent: AppEvents, handler: Function): voidAdd handler for specific event generated by application in specific state
Parameters
appevent:
AppEventsOne of the AppEvents (e.g. AppEvents.CallAlerting)
handler:
FunctionHandler function. A single parameter is passed - object with event information
Returns
Return:
void
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
// your code
});
callConference(conferenceId: String, callerid: String, displayName: String, headers: Object): CallMake a call to a conference using Conference module. If there's no such conference, it'll be created in the first method's call. The method is designed to be called in simple incoming scenario, then it could trigger another special scenario which contains logic of the conference. See the details here. The method can trigger the Failed event after 60 sec, see the details in VoxEngine session limits.
Parameters
conferenceId:
StringId of the conference. The parameter has to be the same as a pattern in a rule so the method triggers appropriate rule with conference logic.
callerid:
StringCallerID of the calling user that will be displayed to the called user. Usage of whitespaces is not allowed. Normally it's some phone number that can be used for callback. IMPORTANT: virtual numbers rented from Voximplant can't be used as CallerID, use only real numbers.
displayName:
StringName of the calling user, that will be displayed to the called user. Normally it's a human-readable version of CallerID, e.g. a person's name.
headers:
ObjectOptional SIP headers to be passed with call to conference. Custom header names have to begin with the 'X-' prefix. The "X-" headers could be handled by a SIP phone or WEB SDK (e.g. see the incomingCall event). Example: {'X-header':'value'}
Returns
Return:
Call
callPSTN(number: String, callerid: String): CallStart outgoing call to the specified PSTN number. Calls more expensive than 20 cents per minute and calls to Africa are blocked by default for security reasons. Please contact us at support@voximplant.com to enable them. The method can trigger the CallEvents.Failed event after 60 sec, see the details in VoxEngine session limits.
Parameters
number:
StringPSTN number to start call to in international format (E.164)
callerid:
StringCallerID of the calling user that will be displayed to the called user. Usage of whitespaces is not allowed. Normally it's some phone number that can be used for callback. It can be 1) a phone number that is purchased from Voximplant 2) verified account's number 3) an incoming phone number (in case if a session was started with an incoming call). IMPORTANT: virtual numbers rented from Voximplant can't be used as CallerID, use only real numbers.
Returns
Return:
Call
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
var out = VoxEngine.callPSTN("+13115552368", "555000");
})
callSIP(to: String, options: callSIPParameters): CallStart outgoing call to the external SIP system or to the another user of the same application. The method can trigger the CallEvents.Failed event after 60 sec, see the details in VoxEngine session limits.
Parameters
to:
StringSIP URI to make call to. Format is: user-of-the-application@application-name.account-name.voximplant.com
options:
VoxEngine.callSIPParametersObject with callSIP parameters. Note that if this parameter is not an object, it is treated as "callerid". Further parameters will be treated as "displayName", "password", "authUser", "extraHeaders", "video", "outProxy" respectively.
Returns
Return:
Call
Examples
request:
Example with all possible parameters:
var call = VoxEngine.callSIP("user@app.accountname.voximplant.com", {
callerid: "6410",
displayName: "Chuck Spadina",
password: "qwerty",
authUser: "user",
extraHeaders: {foo: "bar"},
video: false,
outProxy: "69.167.178.6",
regId: 12345
});
callUser(username: String, callerid: String, displayName: String, extraHeaders: Object, video: Boolean, scheme: Object): CallStart outgoing call to the specified Voximplant user. The JavaScript scenario that uses this method and user being called should be both associated with the same Voximplant application. The method can trigger the CallEvents.Failed event after 60 sec, see the details in VoxEngine session limits.
Parameters
username:
StringName of the Voximplant user to call
callerid:
StringCallerID of the calling user that will be displayed to the called user. Usage of whitespaces is not allowed. Normally it's some phone number that can be used for callback. IMPORTANT: virtual numbers rented from Voximplant can't be used as CallerID, use only real numbers.
displayName:
StringName of the calling user, that will be displayed to the called user. Normally it's a human-readable version of CallerID, e.g. a person's name.
extraHeaders:
ObjectOptional custom parameters (SIP headers) that should be passed with call (INVITE) message. Custom header names have to begin with the 'X-' prefix except the 'VI-CallTimeout': '5' which hangs up if there is no answer after the timeout. The "X-" headers could be handled by a SIP phone or WEB SDK (e.g. see the incomingCall event). Example: {'X-header':'value'}
video:
BooleanSpecifies if call should have video support. Please note that prices for audio-only and video calls are different!
scheme:
ObjectInternal information about codecs from the AppEvents.CallAlerting event
Returns
Return:
Call
Examples
request:
Minimal example:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
var out = VoxEngine.callUser("username", "String-to-display-on-called-user-device-as-a-caller-name");
}
Example for video calls. It is strongly recommended to pass [AppEvents.CallAlerting] as an argument for every video call. It is strictly required in case of calling to Safari browser. For more details about schemes handling see the source code of the [VoxEngine.easyProcess] method.
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
var out = VoxEngine.callUser("username", "String-to-display-on-called-user-device-as-a-caller-name", "", {}, true, e.scheme);
}
Example with hang up if there is no answer after the timeout:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
var out = VoxEngine.callUser("username", "String-to-display-on-called-user-device-as-a-caller-name", "", {'VI-CallTimeout': '5'});
}
callUserDirect(incomingCall: Call, username: String, callerid: String, displayName: String, extraHeaders: Object): CallStart outgoing call to the specified Voximplant user in peer-to-peer mode. The JavaScript scenario that uses this method and user being called should be both associated with the same Voximplant application. Audio playback and recording will not make any effect. P2P mode is available only for calls between SDKs. The method can trigger the CallEvents.Failed event after 60 sec, see the details in VoxEngine session limits. IMPORTANT: calling this method makes impossible to use non-P2P mode for a new call and specified incomingCall. So the following methods couldn't be used: Call.say, Call.sendDigits, Call.sendMediaTo, Call.stopMediaTo.
Parameters
incomingCall:
CallIncoming call that needs to be forwarded
username:
StringName of the Voximplant user to call
callerid:
StringCallerID of the calling user that will be displayed to the called user. Usage of whitespaces is not allowed. Normally it's some phone number that can be used for callback. IMPORTANT: virtual numbers rented from Voximplant can't be used as CallerID, use only real numbers.
displayName:
StringName of the calling user, that will be displayed to the called user. Normally it's a human-readable version of CallerID, e.g. a person's name.
extraHeaders:
ObjectOptional custom parameters (SIP headers) that should be passed with call (INVITE) message. Custom header names have to begin with the 'X-' prefix. The "X-" headers could be handled by a SIP phone or WEB SDK (e.g. see the incomingCall event). Example: {'X-header':'value'}
Returns
Return:
Call
Examples
request:
Minimal example
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
var inc = e.call;
var out = VoxEngine.callUserDirect(inc, "Username", "someCallerId");
});
customData(cData: String): StringSet or get custom string associated with current JavaScript session. There are two kinds of the customData values: one is for JavaScript session (i.e. VoxEngine object), another is for the particular call (i.e. Call.html.customData and WEB SDK parameter of the method). It's possible to use them at the same time because they are independent entities. Remember that if you receive some value from WEB SDK, it doesn't overwrite the VoxEngine's value. Any of customData's type values can be later obtained from Call History using HTTP API or Control Panel.
Parameters
cData:
String|undefinedCustom session data to set. Maximum size is 200 bytes.
Returns
Return:
String
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
var inc = e.call;
var a = inc.customData();
VoxEngine.customData("VoxEngine customData");
inc.answer();
inc.addEventListener(CallEvents.Connected, function(e) {
Logger.write("Call object customdata : " + a); // undefined or value received from WEB SDK
Logger.write("VoxEngine.customData() : " + VoxEngine.customData()); // value specified on line 4
});
});
easyProcess(call1: Call, call2: Call, onEstablishedCallback: Function, direct: Boolean): voidAdds all default event listeners to pass signaling information between two calls. The source code of the method is available on GitHub.
Parameters
call1:
CallIncoming alerting call
call2:
CallNewly created outgoing call
onEstablishedCallback:
FunctionFunction to be called once call is established. Both call1 and call2 are passed to this function as parameters
direct:
BooleanIf it's true, P2P mode will be enabled. It's false by default.
Returns
Return:
void
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
var inc = e.call;
var out = VoxEngine.callPSTN("+13115552368");
VoxEngine.easyProcess(inc, out);
});
forwardCallToPSTN(numberTransform: Function, onEstablishedCallback: Function): voidHelper function to forward incoming call to PSTN. The method handles numbers only in E.164 format by default. If you need to handle a number in another format, pass additional function (as a parameter) to the method. For more details see the article about this method. The source code of the method is available on GitHub.
Parameters
numberTransform:
FunctionOptional function used to transform dialed number to international format. This function accepts dialed number and must return phone number in E.164 format
onEstablishedCallback:
FunctionOptional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function
Returns
Return:
void
Examples
request:
Case: client type in the number in E.164 format. Minimal example:
VoxEngine.addEventListener(AppEvents.CallAlerting, function (e) {
var newCall = VoxEngine.callPSTN(e.destination, e.callerid);
VoxEngine.easyProcess(e.call, newCall);
});
// so the method could do the same job
VoxEngine.forwardCallToPSTN();
forwardCallToSIP(onEstablishedCallback: Function, video: Boolean): voidHelper function to forward incoming call to dialed SIP URI. For more details see the article about this method. The source code of the method is available on GitHub.
Parameters
onEstablishedCallback:
FunctionOptional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function
video:
BooleanSpecifies if call should have video support. Please note that price for audio-only and video calls is different!
Returns
Return:
void
Examples
request:
Minimal example:
VoxEngine.addEventListener(AppEvents.CallAlerting, function (e) {
var newCall = VoxEngine.callSIP(e.toURI, e.callerid, e.displayName);
VoxEngine.easyProcess(e.call, newCall);
}
// so the method could do the same job
VoxEngine.forwardCallToSIP();
forwardCallToUser(onEstablishedCallback: Function, video: Boolean): voidHelper function to forward incoming call to user of current application. Dialed number is interpreted as username. For more details see the article about this method. The source code of the method is available on GitHub.
Parameters
onEstablishedCallback:
FunctionOptional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function
video:
BooleanSpecifies if call should have video support. Please note that price for audio-only and video calls is different!
Returns
Return:
void
Examples
request:
Case: client type in a correct username. Minimal example:
VoxEngine.addEventListener(AppEvents.CallAlerting, function (e) {
var newCall = VoxEngine.callUser(e.destination, e.callerid, e.displayName);
VoxEngine.easyProcess(e.call, newCall);
}
// so the method could do the same job
VoxEngine.forwardCallToUser();
forwardCallToUserDirect(onEstablishedCallback: Function): voidHelper function to forward incoming call to user of current application in P2P mode. Dialed number is interpreted as username. Due to P2P mode, audio playback and recording will not make any effect. For more details see the article about making calls between users. The source code of the method is available on GitHub.
Parameters
onEstablishedCallback:
FunctionOptional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function
Returns
Return:
void
Examples
request:
Minimal example:
VoxEngine.addEventListener(AppEvents.CallAlerting, function (e) {
var newCall = VoxEngine.callUserDirect(e.call, e.destination, e.callerid);
//note that 'direct parameter' is set to true to provide P2P mode
VoxEngine.easyProcess(e.call, newCall, null, true);
}
// so the method could do the same job
VoxEngine.forwardCallToUserDirect();
playSoundAndHangup(fileURL: String): voidHelper function to play sound to incoming call. It also terminate a call in three cases: 1) playback is finished 2) call failed 3) call disconnected
Parameters
fileURL:
StringURL of audio (mp3) file to play
Returns
Return:
void
Examples
request:
Minimal example:
var fileURL = "//path.to/the/file.mp3";
VoxEngine.addEventListener(AppEvents.CallAlerting, function (e) {
e.call.answer();
e.call.addEventListener(CallEvents.Connected, function (e) {
e.call.startPlayback(fileURL);
});
e.call.addEventListener(CallEvents.Failed, function (e) {
VoxEngine.terminate();
});
e.call.addEventListener(CallEvents.Disconnected, function (e) {
VoxEngine.terminate();
});
e.call.addEventListener(CallEvents.PlaybackFinished, function (e) {
VoxEngine.terminate();
});
// so the method could do the same job
VoxEngine.playSoundAndHangup("//path.to/the/file.mp3");
removeEventListener(appevent: AppEvents, handler: Function): voidRemove handler for specific event generated by application
Parameters
appevent:
AppEventsOne of the AppEvents (e.g. AppEvents.CallAlerting)
handler:
FunctionHandler function. If not specified, all event listeners are removed
Returns
Return:
void
sendMediaBetween(mediaUnit1: Call|Conference|ASR|Player|IVR|Recorder, mediaUnit2: Call|Conference|ASR|Player|IVR|Recorder): voidStart sending media from mediaUnit1 to mediaUnit2 and vice versa - the method binds two audio/video streams. Is a shortcut for
mediaUnit1.sendMediaTo(mediaUnit2); mediaUnit2.sendMediaTo(mediaUnit1);
Parameters
mediaUnit1:
Call|Conference|ASR|Player|IVR|RecorderFirst media unit
mediaUnit2:
Call|Conference|ASR|Player|IVR|RecorderSecond media unit
Returns
Return:
void
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
var inc = e.call;
var out = VoxEngine.callUser("user", "displayedName");
out.addEventListener(CallEvents.Connected, function(){
inc.answer();
VoxEngine.sendMediaBetween(inc, out);
});
});
stopMediaBetween(mediaUnit1: Call|Conference|ASR|Player|IVR|Recorder, mediaUnit2: Call|Conference|ASR|Player|IVR|Recorder): voidStop sending media from mediaUnit1 to mediaUnit2 and vice versa Is a shortcut for
mediaUnit1.stopMediaTo(mediaUnit2); mediaUnit2.stopMediaTo(mediaUnit1);
Parameters
mediaUnit1:
Call|Conference|ASR|Player|IVR|RecorderFirst media unit
mediaUnit2:
Call|Conference|ASR|Player|IVR|RecorderSecond media unit
Returns
Return:
void
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
var inc = e.call;
var out = VoxEngine.callUser("user", "displayedName");
out.addEventListener(CallEvents.Connected, function(){
inc.answer();
VoxEngine.sendMediaBetween(inc, out);
});
out.addEventListener(CallEvents.Disconnected, function(){
VoxEngine.stopMediaBetween(inc, out);
});
});
terminate(): voidTerminates current JavaScript session. All audio/video streams will be disconnected and scenario's execution will also be terminated. Note that after function call the AppEvents.Terminating and AppEvents.Terminated events will be triggered.
Returns
Return:
void
Examples
request:
VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
var inc = e.call;
var out = VoxEngine.callUser("user", "displayedName");
out.addEventListener(CallEvents.Connected, function(){
inc.answer();
VoxEngine.sendMediaBetween(inc, out);
});
out.addEventListener(CallEvents.Disconnected, function(){
VoxEngine.terminate();
});
});