Constructs new call.

Methods

addEventListener(callevent, handler)

void

Add handler for specific event generated by call in specific application state

Example

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
   var out = VoxEngine.callUser("testUser", "String-to-display-as-a-caller-name");
   out.addEventListener(CallEvents.Connected, function(){
     // any logic, e.g. answering the call
   });
 });
  
Parameters
  • callevent: Event

    One of the CallEvents (e.g. CallEvents.Connected)

  • handler: Function

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

answer(extraHeaders, parameters)

void

Answer incoming call. Remember that you can use the startEarlyMedia method before answering a call.

Example

 //JS scenario receives a call from WEB SDK
 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
     var inc = e.call;
     inc.answer({}, {"key1":"value", "key2":"value"});
     //after that the Connected call event is triggered on WEB SDK side and
     //the optional parameters are passed into this event
   }

Parameters
  • extraHeaders: Object (optional)

    Optional custom parameters (SIP headers) that should be passed with answer 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'}

  • parameters: Object (optional)

    Optional custom parameters as a "key":"value" pair. They could be passed and handled into Connected call event in WEB SDK.

callerid()

String

Returns Caller ID of the calling user, that is displayed to the called user. Normally it's some phone number that can be used for callback. IMPORTANT: virtual numbers rented from Voximplant can't be used as CallerID, the values can be only real numbers.

Returns
  • String

customData(cData)

String

Set or get custom string associated with the particular call (e.g. Call object). Additionally, the customData value could be sent from WEB/iOS/Android SDKs and then it became the customData value in the Call object. Note that if you received some value from SDK, you could always replace it manually.

SDKs can pass customData in two ways: 1) when SDK calls to the Voximplant cloud 2) when SDK answers to the call from the Voximplant cloud. See the syntax and details in the appropriate references: WEB SDK call() / WEB SDK answer() / iOS callToUser / iOS answerWithSendVideo / Android callTo() / Android answer()
Example

     Call.customData("some information");  // set or replace the value
Parameters
  • cData: String|undefined

    Custom call data to set. Maximum size is 200 bytes.

Returns
  • String

decline(code, extraHeaders)

void

DEPRECATED - see the reject method || Reject an incoming call

Parameters
  • code: Number (optional)

    SIP status code

  • extraHeaders: Object (optional)

    Optional custom parameters (SIP headers) that should be passed with answer 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'}

detectProgressTone(detect)

void

Enables or disables progress tone detection. Calling this method without an argument is equal to the call with true. Can be used only for outgoing calls. If progress tone is detected, the ToneDetected event will be triggered for the call object. Note that event is triggered only if the CallEvents.Connected event was triggered before.

Parameters
  • detect: Boolean

    true/false enable/disable progress tone. It's false by default.

detectVoicemailTone(timeout, threshold)

void

Enables or disables Voicemail tone detection. Can be used only for outgoing calls. Tone signal is in the range 500 - 2000 Hz on the call. Right after the method’s call VoxEngine will start to scan a media stream. The scanning will stop after the timeout. If Voicemail tone is detected (or is not detected for some time), the VoicemailToneDetected or VoicemailToneNotDetected event will be triggered for the call object.

Parameters
  • timeout: Number (optional)

    Optional timeout in sec. 20 sec by default

  • threshold: Number (optional)

    Minimal detected tone duration. 100 ms by default

displayName()

String

Returns a name of the calling user, that is displayed to the called user. Normally it's a human-readable version of CallerID, e.g. a person's name.

Returns
  • String

handleMicStatus(handle)

void

Enables or disables detection of microphone status in the call. If detection is enabled, the MicStatusChange event will be triggered at each status' change.

Parameters
  • handle: Boolean

    Enable/disable microphone status analysis. It's false by default.

handleTones(doHandle)

void

Change DTMF processing mode. If it's true, each received signal triggers the ToneReceived.

Parameters
  • doHandle: Boolean

    Enable/disable DTMF analysis. It's false by default.

hangup(extraHeaders)

void

Start finishing a call. Firstly it triggers the Disconnected event immediately. If there are no other active calls and/or ACD requests in a call session the AppEvents.Terminating and AppEvents.Terminated events will be triggered in 60 seconds (see the details in VoxEngine session limits).

Parameters
  • extraHeaders: Object (optional)

    Optional custom parameters (SIP headers) that should be passed with hangup request. 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'}

id()

String

Returns call id. Each call in JavaScript session has its own unique id which is used to describe every action in the call logs.

Returns
  • String

incoming()

boolean

Returns true if the call is incoming, false if it was originated from script

Returns
  • boolean

number()

String

Returns a dialed number of inbound or outbound call.

Returns
  • String

playProgressTone(country)

void

Provides country-specific progress tones. The method sends a command to the Voximplant cloud to start playing progress tones in the call. So the progress tones totally depend on the Voximplant cloud. Note that in order to work properly in a call that is not connected yet, you need to call the startEarlyMedia method before using this function. IMPORTANT: each call object can send media to any number of other calls (media units), but can receive only one audio stream. A new incoming stream always replaces the previous one.

Example

Play Russian progress tone to the call

call.startEarlyMedia();
call.playProgressTone("RU");
Example

Play US progress tone to the call

call.startEarlyMedia();
call.playProgressTone("US");
Parameters
  • country: String (optional)

    2-digit country code. Currently supported values are US, RU

record(params)

void

Start recording call. Both incoming and outgoing streams are being recorded. The method triggers the RecordStarted event. For more details see the appropriate articles.

Example

Example with parameters:

 call.record({stereo: true, lossless: true});
Parameters

reject(code, extraHeaders)

void

Reject an incoming call. Firstly it triggers the Disconnected event immediately. The AppEvents.Terminating and AppEvents.Terminated events will be triggered in 60 seconds.

Parameters
  • code: Number (optional)

    SIP status code

  • extraHeaders: Object (optional)

    Optional custom parameters (SIP headers) that should be passed with answer 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'}

removeEventListener(callevent, handler)

void

Remove event handler for specific event generated by call in specific application state

Example

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
         var inc = e.call;
         var out = VoxEngine.callPSTN("+13115552368");
         inc.answer();
         inc.addEventListener(CallEvents.Connected, function(e) {
            inc.say("Hello, world!");
            inc.addEventListener(CallEvents.PlaybackFinished, firstPlaybackFinished);
            function firstPlaybackFinished() {
              inc.removeEventListener(CallEvents.PlaybackFinished, firstPlaybackFinished); // removes listener for CallEvents.PlaybackFinished
           }
        });
    });
Parameters
  • callevent: Event

    One of the CallEvents (e.g. CallEvents.Connected)

  • handler: Function (optional)

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

ring(extraHeaders)

void

Provides progress tones for the incoming call. The method sends a low-level command to the endpoint device to start playing progress tones in the call. So the progress tones depend on endpoint device's behavior rather than the Voximplant cloud. IMPORTANT: each call object can send media to any number of other calls (media units), but can receive only one audio stream. A new incoming stream always replaces the previous one.

Parameters
  • extraHeaders: Object (optional)

    Optional custom parameters (SIP headers) that should be passed with the 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'}

say(text, language, ttsoptions)

void

Say some text to the answered call. If text length exceeds 1500 characters the Call.PlaybackFinished event will be triggered with error description. IMPORTANT: each call object can send media to any number of other calls (media units), but can receive only one audio stream. A new incoming stream always replaces the previous one.

Example

 VoxEngine.addEventListener(AppEvents.CallAlerting, function(e) {
     var inc = e.call;
     var out = VoxEngine.callUser("test-user");
     out.addEventListener(CallEvents.Connected, function(e){
       out.say("The test is sucessful. Bye.", Language.UK_ENGLISH_FEMALE,  {pitch: "high", volume: "loud", rate: "x-slow"});
       out.addEventListener(CallEvents.PlaybackFinished, VoxEngine.terminate);
     });  
   });
Parameters
  • text: String

    Message that will be played to the call. To put an accent in specified syllabus, use tag <say-as stress='1'> </say-as>. Example with accent on first syllabus:

     call.say("<say-as stress='1'>something</say-as>", Language.UK_ENGLISH_FEMALE) 

  • language: String (optional)

    Language and voice to be used. List of all supported languages is available here. The default value is Language.UK_ENGLISH_FEMALE.

  • ttsoptions: VoxEngine.TTSOptions (optional)

    Optional parameters for TTS. SSML markup can be used to control aspects of speech such as pronunciation, volume, pitch, rate, etc.

sendDigits(digits)

void

Send DTMF digits to the remote peer

Parameters
  • digits: String

    Any combination of 0-9, *, #, p (pause) symbols

sendInfo(mimeType, body, headers)

void

Send Info (SIP INFO) message inside the call

Parameters
  • mimeType: String

    MIME type of the message

  • body: String

    Message content. Maximum size is 8192 bytes according to the limits.

  • headers: Object (optional)

    Optional headers to be passed with the 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'}

sendMediaTo(targetMediaUnit)

void

Start sending media (voice and video) from this call to media unit specified in targetMediaUnit. The target call has to be answered earlier. IMPORTANT: each call object can send media to any number of other calls (media units), but can receive only one audio stream. A new incoming stream always replaces the previous one.

Parameters

sendMessage(text)

void

Send text message during the call. See the similar methods in the WEB / iOS / Android SDKs.

Parameters
  • text: String

    Message text. Maximum size is 8192 bytes according to the limits.

startEarlyMedia(extraHeaders)

void

Informs call endpoint that early media will be sent before accepting the call. It allows playing voicemail prompt or music during establishing the connection. It doesn't allow to listen to call endpoint. Note that unanswered call can be in "early media" state only for 60 seconds, see the VoxEngine session limits for details.

Parameters
  • extraHeaders: Object (optional)

    Optional custom parameters (SIP headers) that should be passed with the 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'}

startPlayback(url, loop)

void

Starts to play audio file to the answered call. You can stop playing manually by using the stopPlayback method. IMPORTANT: each call object can send media to any number of other calls (media units), but can receive only one audio stream. A new incoming stream always replaces the previous one.

Parameters
  • url: String

    HTTP/HTTPS url of audio file. The file is cached after the first playing. Supported formats are: mp3, ogg & flac (mp3, speex, vorbis and flac codecs respectively). Maximum file size is 2 MBytes

  • loop: Boolean (optional)

    If it's true, playback will be looped.

state()

String

Returns current state of the call. Possible values are: TERMINATED | CONNECTED | PROGRESSING | ALERTING

Returns
  • String

stopMediaTo(targetMediaUnit)

void

Stop sending media (voice and video) from this call to media unit specified in targetMediaUnit.

Parameters
  • targetMediaUnit: Call|Conference

    media unit that will not receive media from this call anymore.

stopPlayback()

void

Stop audio playback that was started before by calling the startPlayback method.

toString()

String

Returns human-readable description of the call

Returns
  • String

vad()

Boolean

Returns VAD (Voice Activity Detection) status. The including of the ASR module also activates VAD so in that case vad() returns true.

Returns
  • Boolean