Platform
VOICEVIDEOMESSAGING
SolutionsIndustries
Documentation
GETTING STARTEDPLATFORM REFERENCETUTORIALS
ShowcasePricing
BlogHelp
FAQDEVELOPER COMMUNITYCONTACT SUPPORT
About
PRESS & MEDIACAREERSSTATUS PAGEPRIVACY POLICYTERMS OF SERVICEACCEPTABLE USE POLICY
SIGN UP
SIGN UP

VoxEngine

Classes(5)

Methods(17)

Methods

addEventListener

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

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
  // your code
  });

callConference

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:

    String

    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: test numbers rented from Voximplant can't be used as CallerID, use only real numbers.

  • 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, e.g. a person's name.

  • headers:

    Object
    OPTIONAL

    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

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: test numbers can't be used.
    2. Any phone number that is verified via an automated call from Voximplant and confirmation code
    3. A phone number from an icoming call to the rented number. It can be retrieved as Caller ID.

Returns

Examples

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

callSIP

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

Start outgoing call to the external SIP system or to another user of the same application. Supported codecs are: G711 (u-law and a-law), Opus, ILBC, H.264, VP8. 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

  • 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

Examples

Example with all possible parameters:

 var call = VoxEngine.callSIP("sip:alice@example.org", {
  callerid: "6410",
  displayName: "Chuck Spadina",
  password: "qwerty",
  authUser: "user",
  headers: {"X-foo": "bar"},
  video: false,
  outProxy: "your.proxy.com"
});

Example with the regId parameter:

 var call = VoxEngine.callSIP("alice", {
  regId: 12345
});

callUser

callUser(username: String, callerid: String, displayName: String, extraHeaders: Object, video: Boolean, scheme: Object, maxVideoBitrate: Number): 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:

    String
    OPTIONAL

    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: test numbers rented from Voximplant can't be used as CallerID, use only real numbers.

  • 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, e.g. a person's name.

  • extraHeaders:

    Object
    OPTIONAL

    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:

    Boolean
    OPTIONAL

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

  • scheme:

    Object
    OPTIONAL

    Internal information about codecs from the AppEvents.CallAlerting event.

  • maxVideoBitrate:

    Number
    OPTIONAL

    Set the maximum possible video bitrate for the end user device in kbps.

Returns

Examples

Minimal example:

 VoxEngine.addEventListener(AppEvents.CallAlerting, e => {
   const 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, e => {
  const 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, e => {
   const out = VoxEngine.callUser("username", "String-to-display-on-called-user-device-as-a-caller-name", "", {'VI-CallTimeout': '5'});
 });

callUserDirect

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:

    String
    OPTIONAL

    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: test numbers rented from Voximplant can't be used as CallerID, use only real numbers.

  • 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, e.g. a person's name.

  • extraHeaders:

    Object
    OPTIONAL

    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

Minimal example

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

customData

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

 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

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:

    Function
    OPTIONAL

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

  • direct:

    Boolean
    OPTIONAL

    If it's true, P2P mode will be enabled. It's false by default.

Returns

  • Return:

    void

Examples

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

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:

    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

  • 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: test 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

forwardCallToSIP

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:

    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!

Returns

  • Return:

    void

forwardCallToUser

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:

    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!

Returns

  • Return:

    void

forwardCallToUserDirect

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:

    Function
    OPTIONAL

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

Returns

  • Return:

    void

playSoundAndHangup

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

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

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

Remove handler for specific event generated by application

Parameters

Returns

  • Return:

    void

sendMediaBetween

sendMediaBetween(mediaUnit1: Call|Conference|ASR|Player|Recorder, mediaUnit2: Call|Conference|ASR|Player|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

 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

stopMediaBetween(mediaUnit1: Call|Conference|ASR|Player|Recorder, mediaUnit2: Call|Conference|ASR|Player|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

 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

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

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