VoxEngine

addEventListener(appevent: AppEvents, handler: Function): void

Parameters

• appevent:

  AppEvents

  One of the AppEvents (e.g. AppEvents.CallAlerting)

• handler:

  Function

  Handler 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): Call

Parameters

• conferenceId:

  String

  Id 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:

  StringOptional

  CallerID 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:

  StringOptional

  Name 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

  Optional 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): Call

Parameters

• number:

  String

  PSTN number to start call to in international format (E.164)

• callerid:

  String

  CallerID of the calling user that will be displayed to the called user. Whitespaces are not allowed. A valid phone number that can be used to call back is required. Following phone numbers can be used:

  1. A real phone number that is rented from Voximplant. IMPORTANT: virtual numbers can't be used.
  2. Any phone number that is verified via an automated call from Voximplant and confirmation code
  3. An incoming call phone number if a cloud JavaScript scenario is started with an incoming call.

Returns

• Return:

  Call

Examples

request:

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
    const callerId = "+1234567890"; // Purchased or confirmed phone number
    var out = VoxEngine.callPSTN("+13115552368", callerId);
  })

callSIP(to: String, options: callSIPParameters): Call

Parameters

• to:

  String

  SIP URI to make call to. Example for an external call: sip:alice@example.org. The format for calls to another user of the same Voximplant application: user-of-the-application@application-name.account-name.voximplant.com

• options:

  callSIPParameters

  Object 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",
  headers: {"X-foo": "bar"},
  video: false,
  outProxy: "69.167.178.6",
  regId: 12345
});

callUser(username: String, callerid: String, displayName: String, extraHeaders: Object, video: Boolean, scheme: Object): Call

Parameters

• username:

  String

  Name of the Voximplant user to call

• callerid:

  StringOptional

  CallerID 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:

  StringOptional

  Name 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

  Optional 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:

  BooleanOptional

  Specifies if call should have video support. Please note that prices for audio-only and video calls are different!

• scheme:

  ObjectOptional

  Internal 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): Call

Parameters

• incomingCall:

  Call

  Incoming call that needs to be forwarded

• username:

  String

  Name of the Voximplant user to call

• callerid:

  StringOptional

  CallerID 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:

  StringOptional

  Name 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

  Optional 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): String

Parameters

• cData:

  String|undefined

  Custom 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): void

Parameters

• call1:

  Call

  Incoming alerting call

• call2:

  Call

  Newly created outgoing call

• onEstablishedCallback:

  FunctionOptional

  Function to be called once call is established. Both call1 and call2 are passed to this function as parameters

• direct:

  BooleanOptional

  If 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;
    const callerId = "+1234567890"; // Purchased or confirmed phone number
    var out = VoxEngine.callPSTN("+13115552368", callerId);
    VoxEngine.easyProcess(inc, out);
 });

forwardCallToPSTN(numberTransform: Function, onEstablishedCallback: Function, Options: Object): void

Parameters

• numberTransform:

  FunctionOptional

  Optional 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

  Optional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function

• Options:

  Object

  An object with a number used as callerid that will be displayed to the called user. Example:

  {callerid: number}

  . Whitespaces are not allowed. A valid phone number that can be used to call back is required. Following phone numbers can be used:

  1. A real phone number that is rented from Voximplant. IMPORTANT: virtual numbers can't be used.
  2. Any phone number that is verified via an automated call from Voximplant and confirmation code
  3. An incoming call phone number if a cloud JavaScript scenario is started with an incoming call.

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): void

Parameters

• onEstablishedCallback:

  FunctionOptional

  Optional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function

• video:

  BooleanOptional

  Specifies 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): void

Parameters

• onEstablishedCallback:

  FunctionOptional

  Optional function that is invoked after call is established. Both calls (incoming and outgoing) are passed to this function

• video:

  BooleanOptional

  Specifies 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): void

Parameters

• onEstablishedCallback:

  FunctionOptional

  Optional 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): void

Parameters

• fileURL:

  String

  URL 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): void

Parameters

• appevent:

  AppEvents

  One of the AppEvents (e.g. AppEvents.CallAlerting)

• handler:

  FunctionOptional

  Handler 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): void

mediaUnit1.sendMediaTo(mediaUnit2); mediaUnit2.sendMediaTo(mediaUnit1);

Parameters

• mediaUnit1:

  Call|Conference|ASR|Player|IVR|Recorder

  First media unit

• mediaUnit2:

  Call|Conference|ASR|Player|IVR|Recorder

  Second 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): void

mediaUnit1.stopMediaTo(mediaUnit2); mediaUnit2.stopMediaTo(mediaUnit1);

Parameters

• mediaUnit1:

  Call|Conference|ASR|Player|IVR|Recorder

  First media unit

• mediaUnit2:

  Call|Conference|ASR|Player|IVR|Recorder

  Second 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(): void

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();
     });
});