SIGN UP

VoxEngine

Methods

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

Add handler for specific event generated by application in specific state. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler will be called.

Parameters

Returns

  • Return:

    void

Examples

request:

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
  // your code
  });
callConference(conferenceId: String, callerid: String, displayName: String, headers: Object): Call

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

    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

callPSTN(number: String, callerid: String): Call

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

    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

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

Start outgoing call to the external SIP system or to 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:

    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

  • 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

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

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

    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

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

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

    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

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

Set 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.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|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

Adds all default event listeners to pass signaling information between two calls. The source code of the method is available on GitHub.

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

Helper 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

    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

Helper 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

    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

Helper 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

    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

Helper 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

    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

Helper function to play sound to incoming call. It also terminates a call in three cases: 1) playback is finished 2) call failed 3) call disconnected

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

Remove handler for specific event generated by application

Parameters

Returns

  • Return:

    void
sendMediaBetween(mediaUnit1: Call|Conference|ASR|Player|IVR|Recorder, mediaUnit2: Call|Conference|ASR|Player|IVR|Recorder): void

Start 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

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

Stop sending media from mediaUnit1 to mediaUnit2 and vice versa Is a shortcut for

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

Parameters

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

Terminates current JavaScript session. All audio/video streams will be disconnected and scenario's execution will also be terminated. Note that after the function call only the AppEvents.Terminating and AppEvents.Terminated events will be triggered; other events won't be tirggered (e.g., CallEvents.Disconnected).

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