SIGN UP

Call

Constructs new call.

Methods

addEventListener

addEventListener(callevent: CallEvents, handler: Function): void

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

Parameters

  • callevent:

    CallEvents

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

  • handler:

    Function

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

Returns

  • Return:

    void

Examples

request:

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

answer

answer(extraHeaders: Object, parameters: AnswerParameters): void

Answer incoming call. Use it only for connecting non-P2P legs. Remember that you can use the Call.startEarlyMedia method before answering a call.

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 Connected event). Example: {'X-header':'value'}

  • parameters:

    AnswerParameters
    Optional

    Custom parameters for answering calls.

Returns

  • Return:

    void

Examples

request:

 //JS scenario receives a call from WEB SDK
 VoxEngine.addEventListener(AppEvents.CallAlerting, e => {
     const call = e.call;
     call.answer(null, {scheme: e.scheme});
     // after that the Connected call event is triggered on WEB SDK side and
     // the optional parameters are passed into this event
   }

answerDirect

answerDirect(extraHeaders: Object, parameters: AnswerParameters): void

Answer incoming call in peer-to-peer mode. Use it only for connecting P2P legs.

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 Connected event). Example: {'X-header':'value'}

  • parameters:

    AnswerParameters
    Optional

    Custom parameters for answering calls.

Returns

  • Return:

    void

callerid

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

  • Return:

    String

customData

customData(cData: String): 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()

Parameters

  • cData:

    String|undefined

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

Returns

  • Return:

    String

Examples

request:

     Call.customData("some information");  // set or replace the value

decline

decline(code: Number, extraHeaders: Object): void

DEPRECATED - see the Call.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'}

Returns

  • Return:

    void

detectProgressTone

detectProgressTone(detect: Boolean): 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 CallEvents.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.

Returns

  • Return:

    void

detectVoicemailTone

detectVoicemailTone(timeout: Number, threshold: Number): 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 CallEvents.VoicemailToneDetected or CallEvents.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

Returns

  • Return:

    void

displayName

displayName(): String

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

Returns

  • Return:

    String

handleMicStatus

handleMicStatus(handle: Boolean): void

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

Parameters

  • handle:

    Boolean

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

Returns

  • Return:

    void

handleTones

handleTones(doHandle: Boolean): void

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

Parameters

  • doHandle:

    Boolean

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

Returns

  • Return:

    void

hangup

hangup(extraHeaders: Object): void

Start finishing a call. Firstly it triggers the CallEvents.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'}

Returns

  • Return:

    void

id

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

  • Return:

    String

incoming

incoming(): boolean

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

Returns

  • Return:

    boolean

number

number(): String

Returns a dialed number of inbound or outbound call.

Returns

  • Return:

    String

playProgressTone

playProgressTone(country: String): 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 Call.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.

Parameters

  • country:

    String
    Optional

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

Returns

  • Return:

    void

Examples

request:

Play Russian progress tone to the call

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

Play US progress tone to the call

 call.startEarlyMedia();
 call.playProgressTone("US");

record

record(params: RecorderParameters): void

Start recording incoming and outgoing audio for this call. This method triggers the CallEvents.RecordStarted event. Please note that voice produced by the Call.say() is not recorded via this method. In order to record such voice, use the Player module as shown in the Call.say. The default quality is 8kHz / 32kbps; the format is mp3. See this article for details.

Parameters

Returns

  • Return:

    void

Examples

request:

Example with parameters:

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

reject

reject(code: Number, extraHeaders: Object): void

Reject an incoming call. Firstly it triggers the CallEvents.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'}

Returns

  • Return:

    void

removeEventListener

removeEventListener(callevent: CallEvents, handler: Function): void

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

Parameters

  • callevent:

    CallEvents

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

  • handler:

    Function
    Optional

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

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

ring

ring(extraHeaders: Object): 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'}

Returns

  • Return:

    void

say

say(text: String, language: String, ttsoptions: TTSOptions): void

Say some text to the CallEvents.Connected call. If text length exceeds 1500 characters the PlayerEvents.PlaybackFinished event will be triggered with error description. Voice generated via say is not recorded via the Recorder module. In order to record such voice, use the Player module as shown in the example below. 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

  • 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: Language. The default value is Language.UK_ENGLISH_FEMALE.

  • ttsoptions:

    TTSOptions
    Optional

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

Returns

  • Return:

    void

Examples

request:

   // Normal usage
   VoxEngine.addEventListener(AppEvents.Started, () => {
     const out = VoxEngine.callUser("test-user");
     out.addEventListener(CallEvents.Connected, () => {
       out.say(
         "The test is sucessful. Bye.",
         Language.UK_ENGLISH_FEMALE,
         {pitch: "high", volume: "loud", rate: "x-slow"});
       out.addEventListener(CallEvents.PlaybackFinished, VoxEngine.terminate);
     });  
   });

   // Recording say() results via createTTSPlayer()
   require(Modules.Player);
   VoxEngine.addEventListener(AppEvents.Started, () => {
     const out = VoxEngine.callUser("test-user");
     out.addEventListener(CallEvents.Connected, () => {
       const recorder = VoxEngine.createRecorder();
       const player = VoxEngine.createTTSPlayer(
         "The test is sucessful. Bye.",
         Language.UK_ENGLISH_FEMALE,
         {pitch: "high", volume: "loud", rate: "x-slow"});
       player.sendMediaTo(recorder);
       player.sendMediaTo(out);
       player.addEventListener(PlayerEvents.PlaybackFinished, VoxEngine.terminate);
     });  
   });

sendDigits

sendDigits(digits: String): void

Send DTMF digits to the remote peer

Parameters

  • digits:

    String

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

Returns

  • Return:

    void

sendInfo

sendInfo(mimeType: String, body: String, headers: Object): 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'}

Returns

  • Return:

    void

sendMediaTo

sendMediaTo(targetMediaUnit: Call|Conference): void

Start sending media (voice and video) from this call to media unit specified in targetMediaUnit. The target call has to be CallEvents.Connected 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

Returns

  • Return:

    void

sendMessage

sendMessage(text: String): 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.

Returns

  • Return:

    void

startEarlyMedia

startEarlyMedia(extraHeaders: Object): 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'}

Returns

  • Return:

    void

startPlayback

startPlayback(url: String, loop: Boolean): void

Starts to play audio file to the Call.answered call. You can stop playing manually by using the Call.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.

Returns

  • Return:

    void

state

state(): String

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

Returns

  • Return:

    String

stopMediaTo

stopMediaTo(targetMediaUnit: Call|Conference): 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.

Returns

  • Return:

    void

stopPlayback

stopPlayback(): void

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

Returns

  • Return:

    void

toString

toString(): String

Returns human-readable description of the call

Returns

  • Return:

    String

vad

vad(): Boolean

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

Returns

  • Return:

    Boolean