Functions

VoxEngine.addEventListener(appevent, handler)

void

Add handler for specified event generated by application

Example

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
  // your code
  });
Parameters
  • appevent: Function

    Event type from the 'AppEvents' namespace, ex AppEvents.CallAlerting

  • handler: Function

    Handler function. A single parameter is passed - object with event information

VoxEngine.callConference(conferenceId, callerid, displayName, headers)

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.

Parameters
  • conferenceId: String

    Id of the conference. This value has to be used as a pattern in the application's rule.

  • callerid: String (optional)

    CallerId

  • displayName: String (optional)

    Optional printable name of callerid

  • headers: Object (optional)

    Optional SIP headers to be passed with call to conference

Returns

VoxEngine.callPSTN(number, callerid)

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.

Example

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
    var out = VoxEngine.callPSTN("+13115552368", "Purchased number");
  }
Parameters
  • number: String

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

  • callerid: String (optional)

    Caller ID that will be displayed to the called user. Can be only one of the phone numbers that were bought in the VoxImplant. If not specified, default system Caller ID is used

Returns

VoxEngine.callSIP(to, callerid, displayName, password, authUser, extraHeaders, video, outProxy)

Call

Start outgoing call to the external SIP system. Optional parameters can be specified as positional arguments or as a single object with property names corresponding to parameter names. If object syntax is used, following additional parameters are available:

  • regId, identifier of a Voximplant SIP registration to use for this outbound call
  • Example

     var call = VoxEngine.callSIP("+71234567890", {regId: 12345});
    
    Parameters
    • to: String

      SIP URI to make call to

    • callerid: String (optional)

      CallerID that will be displayed to the called user. If not specified, "anonymous@appname.accname.voximplant.com" string will be sent, where "appname" is the Voximplant application name and "accname" is the Voximplant account name.

    • displayName: String (optional)

      Name of calling user, that will be displayed to the called user

    • password: String (optional)

      Password for SIP Authentication

    • authUser: String (optional)

      Username for SIP Authentication. If not specified, callerid is used as username for authentication

    • extraHeaders: Object (optional)

      Optional custom parameters (SIP headers) that should be passed with call (INVITE) message. Parameter names must start with "X-" to be processed by application

    • video: Boolean (optional)

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

    • outProxy: String (optional)

      Specifies outbound proxy

    Returns

    VoxEngine.callUser(username, callerid, displayName, extraHeaders, video)

    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.

    Example

    Minimal example:

     VoxEngine.addEventListener(AppEvents.CallAlerting, function(e){
       var out = VoxEngine.callUser("username", "String-to-display-on-called-user-device-as-a-caller-name");
     }
    
    Parameters
    • username: String

      Name of the Voximplant user to call

    • callerid: String

      CallerID of the calling user, that will be displayed to the called user. Note that usage of whitespaces is not allowed. Normally it's some phone number that can be used to call back.

    • displayName: String (optional)

      Name of the calling user, that will be displayed to the called user. Normally it's a human-readable version of CallerID, ex a person name.

    • extraHeaders: Object (optional)

      Optional custom parameters (SIP headers) that should be passed with call (INVITE) message. Parameter names must start with "X-" to be processed by application

    • video: Boolean (optional)

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

    Returns

    VoxEngine.callUserDirect(incomingCall, username, callerid, displayName, extraHeaders)

    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.

    Example

    Minimal example

     VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
        var inc = e.call;
        var out = VoxEngine.callUserDirect(inc, "Username", "someCallerId");
      }
    
    Parameters
    • incomingCall: Call

      Incoming call that needs to be forwarded

    • username: String

      Name of the Voximplant user to call

    • callerid: String

      CallerID of calling user, that will be displayed to the called user. Note that usage of whitespaces is not allowed. Normally it's some phone number that can be used to call back.

    • displayName: String (optional)

      Name of the calling user, that will be displayed to the called user. Normally it's a human-readable version of CallerID, ex a person name.

    • extraHeaders: Object (optional)

      Optional custom parameters (SIP headers) that should be passed with call (INVITE) message. Parameter names must start with "X-" to be processed by application

    Returns

    VoxEngine.customData(cData)

    void

    Set or get custom string associated with 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 object method 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.

    Example

     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
         });
       });
    
    Parameters
    • cData: String|undefined

      Custom session data to set

    VoxEngine.easyProcess(call1, call2, onEstablishedCallback, direct)

    void

    Connects two calls and adds all default event listeners to pass signaling information between two calls. You could check what is inside this method.

    Example

    VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
        var inc = e.call;
        var out = VoxEngine.callPSTN("+13115552368");
        VoxEngine.easyProcess(inc, out);
     });
    
    Parameters
    • call1: Call

      Incoming alerting call

    • call2: Call

      Newly created outgoing call

    • onEstablishedCallback: Function (optional)

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

    • direct: Boolean

      If one of the passed calls was made with peer-to-peer mode the parameter have to be true. It is false by default.

    VoxEngine.forwardCallToPSTN(numberTransform, onEstablishedCallback)

    void

    Helper function to forward incoming call to PSTN. Calling this function will subscribe to the CallAlerting event, then use callPSTN to call the 'destination' property of the incoming call (or number returned by the transform function). Then it will use easyProcess to connect both calls, with optional callback passed to 'easyProcess'. 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.

    Parameters
    • numberTransform: Function (optional)

      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: Function (optional)

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

    VoxEngine.forwardCallToSIP(onEstablishedCallback, video)

    void

    Helper function to forward incoming call to dialed SIP URI. Calling this function will subscribe to the CallAlerting event, then use callSIP with the SIP URI specified in the 'destination' property of the incoming call. Then it will use easyProcess to connect both calls, with optional callback passed to 'easyProcess'.

    Parameters
    • onEstablishedCallback: Function (optional)

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

    • video: Boolean (optional)

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

    VoxEngine.forwardCallToUser(onEstablishedCallback, video)

    void

    Helper function to forward incoming call to user of current application. Calling this function will subscribe to the CallAlerting event, then use callUser with the user name specified in the 'destination' property of the incoming call. Then it will use easyProcess to connect both calls, with optional callback passed to 'easyProcess'.

    Parameters
    • onEstablishedCallback: Function (optional)

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

    • video: Boolean (optional)

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

    VoxEngine.forwardCallToUserDirect(onEstablishedCallback)

    void

    Helper function to forward incoming call to user of current application. Calling this function will subscribe to the CallAlerting event, then use callUserDirect with the user name specified in the 'destination' property of the incoming call. Then it will use easyProcess to connect both calls, with optional callback passed to 'easyProcess'. Call is forwarded in peer-to-peer mode, so audio playback and recording will not make any effect. P2P mode is available only for calls between SDKs.

    Parameters
    • onEstablishedCallback: Function (optional)

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

    VoxEngine.playSoundAndHangup(fileURL)

    void

    Helper function to play sound to incoming call

    Parameters
    • fileURL: String

      URL of audio (mp3) file to play

    VoxEngine.removeEventListener(appevent, handler)

    void

    Remove handler for specified event generated by application

    Parameters
    • appevent: Function

      Event class (i.e. AppEvents.CallAlerting)

    • handler: Function (optional)

      Handler function. If not specified, all event listeners are removed

    VoxEngine.sendMediaBetween(mediaUnit1, mediaUnit2)

    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);
    Example

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

    VoxEngine.stopMediaBetween(call1, call2)

    void

    Stop sending media from mediaUnit1 to mediaUnit2 and vice versa

    Is a shortcut for
    mediaUnit1.stopMediaTo(mediaUnit2); mediaUnit2.stopMediaTo(mediaUnit1);
    Example

     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);
         });
    });
    
    Parameters
    • call1: Call

      First call

    • call2: Call

      Second call

    VoxEngine.terminate()

    void

    Terminates current JavaScript session. All audio/video streams will be disconnected and scenario's execution will also be terminated. Note that after function call AppEvents.Terminating and AppEvents.Terminated events will be triggered.

    Example

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