@ama-team/voxengine-definitions/lib/VoxEngine.js

Library for developing VoxImplant applications

/**
 * @namespace VoxEngine
 */

// callbacks first

/**
 * Please note that this is virtual member of {@link VoxEngine} and doesn't exist in reality
 *
 * @callback VoxEngine.onEstablishedCallback
 *
 * @param {Call} call1
 * @param {Call} call2
 */

/**
 * Please note that this is virtual member of {@link VoxEngine} and doesn't exist in reality
 *
 * @callback VoxEngine.eventCallback
 *
 * @param {Object} event
 */

// real members

/**
 * Add handler for specific event generated by application in specific state
 *
 * @function VoxEngine.addEventListener
 *
 * @param {function} appevent Event class specified in {@link AppEvents}
 * @param {VoxEngine.eventCallback} handler Handler function. A single parameter is passed - object with event information
 */

/**
 * Make a call to system-wide conference
 *
 * @function VoxEngine.callConference
 *
 * @param {string} conferenceId Id of the conference
 * @param {string} [callerid] CallerId
 * @param {string} [displayName] Optional printable name of callerid
 * @param {Object} [headers] Optional SIP headers to be passed with call to conference
 *
 * @return {Call}
 */

/**
 * Start outgoing call to specified PSTN number
 *
 * @function VoxEngine.callPSTN
 *
 * @param {string} number PSTN number to sart call to in international (E.164 format)
 * @param {string} [callerid] Caller ID that will be displayed to 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.
 *
 * @return {Call}
 */

/**
 * Start outgoing call to external SIP system
 *
 * @function VoxEngine.callSip
 *
 * @param {string} to SIP URI to make call to
 * @param {string} callerid CallerID that will be displayed to called user
 * @param {string} [displayName] Name of calling user, that will be displayed to called user
 * @param {string} [password] Password for SIP Authentication
 * @param {string} [authUser] Username for SIP Authentication. If not specified, callerid is used as username for
 *   authentication
 * @param {object} [extraHeaders] Optional custom parameters (SIP headers) that should be passed with call (INVITE)
 *   message. Parameter names must start with "X-" to be processed by application
 * @param {boolean} [video] Specifies if call should have video support. **Please note that price for audio-only and
 *   video calls is different!**
 * @param {string} [outProxy] Specifies outbound proxy
 *
 * @return {Call}
 */


/**
 * Start outgoing call to specified user
 *
 * @function VoxEngine.callUser
 *
 * @param {string} username Name of the user to call
 * @param {string} callerid CallerID that will be displayed to called user
 * @param {string} [displayName] Name of calling user, that will be displayed to called user
 * @param {object} [extraHeaders] Optional custom parameters (SIP headers) that should be passed with call (INVITE)
 *   message. Parameter names must start with "X-" to be processed by application
 * @param {boolean} [video] Specifies if call should have video support. **Please note that price for audio-only and
 *   video calls is different!**
 *
 * @return {Call}
 */

/**
 * Start outgoing call to specified user in P2P mode
 *
 * @function VoxEngine.callUserDirect
 *
 * @param {Call} incomingCall Incoming call that needs to be forwarded
 * @param {string} username Name of the user to call
 * @param {string} callerid CallerID that will be displayed to called user
 * @param {string} [displayName] Name of calling user, that will be displayed to called user
 * @param {object} [extraHeaders] Optional custom parameters (SIP headers) that should be passed with call (INVITE)
 *   message. Parameter names must start with "X-" to be processed by application
 *
 * @return {Call}
 */

/**
 * Set or get custom string associated with call session. It can be later obtained from Call History using HTTP API.
 *
 * @function VoxEngine.customData
 *
 * @param {string|undefined} cData Custom session data to set
 */

/**
 * Adds all default event listeners to pass signaling information between two calls
 *
 * @function VoxEngine.easyProcess
 *
 * @param {Call} call1 Incoming alerting call
 * @param {Call} call2 Newly created outgoing call
 * @param {VoxEngine.onEstablishedCallback} [onEstablishedCallback] Function to be called once call is established. Both
 *   call1 and call2 are passed to this function as parameters
 */

/**
 * Helper function to forward incoming call to PSTN.
 *
 * @function VoxEngine.forwardCallToPSTN
 *
 * @param {function} [numberTransform] Optional function used to transform dialed number to international format. This
 *   function accepts dialed number and must return phone number in E.164 format
 * @param {VoxEngine.onEstablishedCallback} [onEstablishedCallback] Optional function that is invoked after call is
 *   established. Both calls (incoming and outgoing) are passed to this function
 */

/**
 * Helper function to forward incoming call to dialed SIP URI.
 *
 * @function VoxEngine.forwardCallToSIP
 *
 * @param {VoxEngine.onEstablishedCallback} [onEstablishedCallback] Optional function that is invoked after call is
 *   established. Both calls (incoming and outgoing) are passed to this function
 * @param {boolean} [video] Specifies if call should have video support. **Please note that price for audio-only and
 *   video calls is different!**
 */

/**
 * Helper function to forward incoming call to user of current application. Dialed number is interpreted as username.
 *
 * @function VoxEngine.forwardCallToUser
 *
 * @param {VoxEngine.onEstablishedCallback} [onEstablishedCallback] Optional function that is invoked after call is
 *   established. Both calls (incoming and outgoing) are passed to this function
 * @param {boolean} [video] Specifies if call should have video support. **Please note that price for audio-only and
 *   video calls is different!**
 */

/**
 * Helper function to forward incoming call to user of current application. Dialed number is interpreted as username.
 * Call is forwarded in P2P mode, so audio playback and recording will not make any effect.
 *
 * @function VoxEngine.forwardCallToUserDirect
 *
 * @param {VoxEngine.onEstablishedCallback} [onEstablishedCallback] Optional function that is invoked after call is
 *   established. Both calls (incoming and outgoing) are passed to this function
 */

/**
 * Helper function to play sound to incoming call
 *
 * @function VoxEngine.playSoundAndHangup
 *
 * @param {string} fileUrl URL of audio (mp3) file to play
 */

/**
 * Remove handler for specific event generated by application.
 *
 * @function VoxEngine.removeEventListener
 *
 * @param {function} appevent Event class specified in {@link AppEvents}
 * @param {VoxEngine.eventCallback} handler Handler function. If not specified, all event listeners are removed
 */

/**
 * Start sending media from mediaUnit1 to mediaUnit2 and vice versa
 *
 * Is a shortcut for
 * ```
 * mediaUnit1.sendMediaTo(mediaUnit2); mediaUnit2.sendMediaTo(mediaUnit1);
 * ```
 *
 * @function VoxEngine.sendMediaBetween
 *
 * @param {Call|Conference} mediaUnit1 First media unit
 * @param {Call|Conference} mediaUnit2 Second media unit
 */

/**
 * Stop sending media from call1 to call2 and vice versa
 * Is a shortcut for
 *
 * ```
 * call1.stopMediaTo(call2); call2.stopMediaTo(call1);
 * ```
 *
 * @function VoxEngine.stopMediaBetween
 *
 * @param {Call} call1
 * @param {Call} call2
 */

/**
 * Terminates current call control session
 *
 * @function VoxEngine.terminate
 */

/**
 * Conference parameters
 *
 * @class VoxEngine.ConferenceParameters
 *
 * @property {boolean} hd_audio Wideband audio mode
 */

/**
 * Recorder parameters
 *
 * @class VoxEngine.RecorderParameters
 *
 * @property {boolean} hd_audio If set to false (default), 8 KHz / 32 kbps mp3 file will be generated. Otherwise,
 * "wideband audio" 48 KHz / 192 kbps mp3 file will be generated
 * @property {ASRLanguage} language ASR language ASRLanguage.* are possible value
 * @property {boolean} secure Restrict access to the record w/o HTTP API authorization (available only in
 *   {@link VoxEngine.createRecorder})
 * @property {boolean} stereo Write stereo audio file instead of mono, not available for Recorder, can be used in the
 *   {@link Call.record record} method of the {@link Call} class.
 * @property {boolean} transcribe Create the call record transcription
 * @property {boolean} video Record video stream if present, not available for Recorder, can be used in the
 *   {@link Call.record record} method of the {@link Call} class.
 */

/**
 * Options for Text-to-speech usage
 *
 * @class VoxEngine.TTSOptions
 *
 * @property {Number} pitch Voice pitch. Acceptable range: 0.5..2
 * @property {('default'|'x-slow'|'slow'|'medium'|'fast'|'x-fast')} rate Speech speed. Possible values are: x-slow,
 *   slow, medium, fast, x-fast, default.
 * @property {('default'|'silent'|'x-soft'|'soft'|'medium'|'loud'|'x-loud')} volume Speech volume. Possible values
 *   are: silent, x-soft, soft, medium, loud, x-loud, default.
 */