Call | Voximplant Voice AI

The Call object represents one audio or video call leg in a VoxEngine scenario. It is typically received from call events or returned by dialing APIs, then methods such as answer, sendMediaTo, record, and addEventListener are called on that call instance. Related event names, event payloads, and parameter objects are documented on this page because they describe the same call lifecycle.

Calls and sessions

Understand call legs, sessions, and media units in VoxEngine.

Inbound calls

Start from the standard inbound call pattern.

Outbound calls

Start from the standard outbound call pattern.

SIP calling

Route calls through SIP trunks, SIP users, and SIP registrations.

Methods: answer, reject, bridge media, record, play audio, and control call state.
CallEvents: event names and callback payload fields for the call lifecycle.
Parameter types: option objects used by Call methods.

Methods

addEventListener

Adds a handler for the specified CallEvents event. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler is called.

1 addEventListener(event: CallEvents | string, callback: (event: object) => any): void

Parameters

Parameter	Type	Req.	Description
`event`	`CallEvents \| string`	✓	Event constant or event name to subscribe to.
`callback`	`(event: object) => any`	✓	Function called when the event is emitted.

Returns

Type	Description
`void`	Does not return a value.

answer

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

1 answer(extraHeaders?: { [header: string]: string }, parameters?: CallAnswerParameters): void

Parameters

Parameter	Type	Req.	Description
`extraHeaders`	`{ [header: string]: string }`	✗
`parameters`	`CallAnswerParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

answerDirect

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

1 answerDirect(peerCall: Call, extraHeaders?: { [header: string]: string }, parameters?: CallAnswerParameters): void

Parameters

Parameter	Type	Req.
`peerCall`	`Call`	✓
`extraHeaders`	`{ [header: string]: string }`	✗
`parameters`	`CallAnswerParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

callerid

Returns the callerID of the caller, which is displayed to the callee. Normally it is some phone number that can be used for callback. IMPORTANT: test numbers rented from Voximplant cannot be used as CallerIDs, the values can be only real numbers.

1 callerid(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

clientType

Returns a type of the client. The possible values are: ‘pstn’, ‘sip’, ‘user’, ‘wab’.

1 clientType(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

customData

Sets or gets a custom string associated with the particular call (the Call object). The customData value could be sent from WEB/iOS/Android SDKs, and then it becomes the customData value in the Call instance. Note that if you receive a value from an SDK, you can always replace it manually. SDKs can pass customData in two ways:

when SDK calls the Voximplant cloud
when SDK answers the call from the Voximplant cloud. See the syntax and details in the corresponding references: WEB SDK call() / WEB SDK answer() / iOS call:settings: / iOS answerWithSettings / Android call() / Android answer()

1 customData(customData?: string): string

Parameters

Parameter	Type	Req.	Description
`customData`	`string`	✗

Returns

Type	Description
`string`	The requested string value.

decline

Deprecated

Use Call.reject instead

Rejects the incoming call.

1 decline(code: number, extraHeaders?: { [header: string]: string }): void

Parameters

Parameter	Type	Req.	Description
`code`	`number`	✓
`extraHeaders`	`{ [header: string]: string }`	✗

Returns

Type	Description
`void`	Does not return a value.

disableBeepDetection

Disables beep detection in a call.

1 disableBeepDetection(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

displayName

Returns the name of the caller, which is displayed to the callee. Normally it is a human-readable version of Call.callerid, e.g. a person’s name.

1 displayName(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

enableBeepDetection

Enables beep detection in a call. The beep detection is used to detect beeps in the call audio stream.

1 enableBeepDetection(parameters: CallEnableBeepDetectionParameters): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`CallEnableBeepDetectionParameters`	✓

Returns

Type	Description
`void`	Does not return a value.

handleBlindTransfer

Whether to enable blind transfers. When enabled, the CallEvents.BlindTransferRequested event is triggered to request for the third call leg within an existing session and notify the transfer initiator of the result.

1 handleBlindTransfer(handle: boolean): void

Parameters

Parameter	Type	Req.	Description
`handle`	`boolean`	✓

Returns

Type	Description
`void`	Does not return a value.

handleMicStatus

Whether to enable detection of microphone status in the call. If detection is enabled, the CallEvents.MicStatusChange event is triggered at each status’ change.

1 handleMicStatus(handle: boolean): void

Parameters

Parameter	Type	Req.	Description
`handle`	`boolean`	✓

Returns

Type	Description
`void`	Does not return a value.

handleTones

Changes DTMF processing mode (in-band DTMF, RFC 2833 DTMF and DTMF over SIP INFO) telephony signals. If true, each received DTMF signal triggers the CallEvents.ToneReceived and removes from audio stream.

1 handleTones(doHandle: boolean, supportedDtmfTypes?: DTMFType): void

Parameters

Parameter	Type	Req.	Description
`doHandle`	`boolean`	✓
`supportedDtmfTypes`	`DTMFType`	✗

Returns

Type	Description
`void`	Does not return a value.

hangup

Attempts finishing the current call. Triggers one of the following events:

CallEvents.Disconnected if the call is active before hangup.
CallEvents.Failed if it is an outgoing call that is not connected previously. If there are no other active calls and/or SmartQueue requests in the call session, the AppEvents.Terminating and AppEvents.Terminated events are triggered in 60 seconds (see the session limits for details).

1 hangup(extraHeaders?: { [header: string]: string }): void

Parameters

Parameter	Type	Req.	Description
`extraHeaders`	`{ [header: string]: string }`	✗

Returns

Type	Description
`void`	Does not return a value.

id

Returns the call’s id. Each call in a JavaScript session has its own unique id.

1 id(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

incoming

Whether the call is incoming.

1 incoming(): boolean

Parameters

This method does not accept parameters.

Returns

Type	Description
`boolean`	The requested `boolean` value.

monitorMediaStatistics

Enables the retrieval of multimedia statistics during a call. When enabled, the CallEvents.MediaStatisticsReceived event is triggered and retrieves multimedia statistics during a call.

1 monitorMediaStatistics(parameters: MonitorMediaStatisticsParameters): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`MonitorMediaStatisticsParameters`	✓

Returns

Type	Description
`void`	Does not return a value.

notifyBlindTransferFailed

Sends a notification about a failed call transfer with an error code and reason.

1 notifyBlindTransferFailed(code: number, reason: string): void

Parameters

Parameter	Type	Req.	Description
`code`	`number`	✓
`reason`	`string`	✓

Returns

Type	Description
`void`	Does not return a value.

notifyBlindTransferSuccess

Sends a notification of a successful call transfer with the 200 OK message.

1 notifyBlindTransferSuccess(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

number

Returns a dialed number of the incoming or outgoing call.

1 number(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

playProgressTone

Provides country-specific dial tones. The method sends a command to the Voximplant cloud to start playing dial tones in the call. The dial tones fully 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.

1 playProgressTone(country: string): void

Parameters

Parameter	Type	Req.	Description
`country`	`string`	✓

Returns

Type	Description
`void`	Does not return a value.

record

Starts recording the incoming and outgoing audio for this call. This method triggers the CallEvents.RecordStarted event. The default quality is 8kHz / 32kbps; the format is mp3.

1 record(parameters: CallRecordParameters): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`CallRecordParameters`	✓

Returns

Type	Description
`void`	Does not return a value.

reject

Rejects the incoming call. First it triggers the CallEvents.Disconnected event immediately. The AppEvents.Terminating and AppEvents.Terminated events are triggered in 60 seconds.

1 reject(code: number, extraHeaders?: { [header: string]: string }): void

Parameters

Parameter	Type	Req.	Description
`code`	`number`	✓
`extraHeaders`	`{ [header: string]: string }`	✗

Returns

Type	Description
`void`	Does not return a value.

removeEventListener

Removes a handler for the specified CallEvents event.

1 removeEventListener(event: CallEvents | string, callback?: (event: object) => any): void

Parameters

Parameter	Type	Req.	Description
`event`	`CallEvents \| string`	✓	Event constant or event name to subscribe to.
`callback`	`(event: object) => any`	✗	Function called when the event is emitted.

Returns

Type	Description
`void`	Does not return a value.

ring

Plays dial tones for the incoming call. The method sends a low-level command to the endpoint device to start playing dial tones for the call. So the dial tones depend on endpoint device’s behavior rather than on 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.

1 ring(extraHeaders?: { [header: string]: string }): void

Parameters

Parameter	Type	Req.	Description
`extraHeaders`	`{ [header: string]: string }`	✗

Returns

Type	Description
`void`	Does not return a value.

say

Say some text to the CallEvents.Connected call. If text length exceeds 1500 characters the PlayerEvents.PlaybackFinished event is 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.

1 say(text: string, parameters?: CallSayParameters): void

Parameters

Parameter	Type	Req.	Description
`text`	`string`	✓
`parameters`	`CallSayParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

sendDigits

Sends DTMF digits to the remote peer.

1 sendDigits(digits: string): void

Parameters

Parameter	Type	Req.	Description
`digits`	`string`	✓

Returns

Type	Description
`void`	Does not return a value.

sendInfo

Sends info (SIP INFO) message to the call.

1 sendInfo(mimeType: string, body: string, headers?: { [header: string]: string }): void

Parameters

Parameter	Type	Req.
`mimeType`	`string`	✓
`body`	`string`	✓
`headers`	`{ [header: string]: string }`	✗

Returns

Type	Description
`void`	Does not return a value.

sendMediaTo

Starts sending media (voice and video) from the call to the media unit. The target call has to be CallEvents.Connected earlier. IMPORTANT: each call object can send media to any number of the media units, but can receive only one audio stream. A new incoming stream always replaces the previous one.

1 sendMediaTo(mediaUnit: VoxMediaUnit, parameters?: SendMediaParameters): void

Parameters

Parameter	Type	Req.	Description
`mediaUnit`	`VoxMediaUnit`	✓
`parameters`	`SendMediaParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

sendMessage

Sends a text message to the call.

1 sendMessage(text: string): void

Parameters

Parameter	Type	Req.	Description
`text`	`string`	✓

Returns

Type	Description
`void`	Does not return a value.

startEarlyMedia

Informs the call endpoint that early media is sent before accepting the call. It allows playing voicemail prompt or music before establishing the connection. It does not allow to listen to call endpoint. Note that unanswered call can be in “early media” state only for 60 seconds, see the session limits for details.

1 startEarlyMedia(extraHeaders?: { [header: string]: string }, scheme?: string, maxVideoBitrate?: number, audioLevelExtension?: boolean, conferenceCall?: boolean, disableDtxForAudio?: boolean): void

Parameters

Parameter	Type	Req.
`extraHeaders`	`{ [header: string]: string }`	✗
`scheme`	`string`	✗
`maxVideoBitrate`	`number`	✗
`audioLevelExtension`	`boolean`	✗
`conferenceCall`	`boolean`	✗
`disableDtxForAudio`	`boolean`	✗

Returns

Type	Description
`void`	Does not return a value.

startPlayback

Starts to play an audio file to the answered call. You can stop playback manually via the Call.stopPlayback method. You can attach media streams later via the Call.sendMediaTo method etc. 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.

1 startPlayback(url: string, parameters?: StartPlaybackParameters): void

Parameters

Parameter	Type	Req.	Description
`url`	`string`	✓
`parameters`	`StartPlaybackParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

state

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

1 state(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

stopMediaTo

Stops sending media (voice and video) from the call to media unit.

1 stopMediaTo(mediaUnit: VoxMediaUnit): void

Parameters

Parameter	Type	Req.	Description
`mediaUnit`	`VoxMediaUnit`	✓

Returns

Type	Description
`void`	Does not return a value.

stopPlayback

Stops audio playback started before via the Call.startPlayback method.

1 stopPlayback(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

toString

Returns the human-readable description of the call’s status.

1 toString(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

transferTo

Transfers a SIP call to a 3rd party provider which supports the REFER command. If the transfer is successful, Voximplant disconnects from handling this call and the CallEvents.TransferComplete event is triggered. Otherwise, the CallEvents.TransferFailed event is triggered.

1 transferTo(parameters: TransferToParameters): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`TransferToParameters`	✓

Returns

Type	Description
`void`	Does not return a value.

vad

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

1 vad(): boolean

Parameters

This method does not accept parameters.

Returns

Type	Description
`boolean`	The requested `boolean` value.

CallEvents

Subscribe with Call.addEventListener. Each event callback receives an object with the fields documented below.

AudioStarted

Triggers after remote peer answered the call or set the call into the Call.startEarlyMedia state. Note that event is not triggered in P2P mode.

This event occurs after receiving the 183 Session Progress SIP message regardless of receiving actual media packets.

Event constant: CallEvents.AudioStarted

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)

AudioIdentificationStarted

Triggers when voicemail detection system connects to the VMD/AMD server and starts detecting voicemail.

Event constant: CallEvents.AudioIdentificationStarted

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

AudioIdentificationResult

Triggers when voicemail detection ends detecting voicemail and the audio identification result is received.

Event constant: CallEvents.AudioIdentificationResult

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`audioType`	`AMD.ResultClass`	✓
`audioSubType`	`AMD.ResultSubtype`	✓
`confidence`	`number`	✓

AudioIdentificationStopped

Triggers when voicemail detection stops detecting voicemail.

Event constant: CallEvents.AudioIdentificationStopped

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

AudioIdentificationError

Triggers when voicemail detection occurs an error.

Event constant: CallEvents.AudioIdentificationError

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

BlindTransferRequested

Triggered when blind transfers are enabled by Call.handleBlindTransfer.

Event constant: CallEvents.BlindTransferRequested

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`transferTo`	`string`	✓	Username

Connected

Triggers after an incoming/outgoing call is connected. For incoming call, it happens after the Call.answer is called. For outgoing call, it happens when a remote peer answers the call.

Event constant: CallEvents.Connected

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`customData`	`string`	✗	Custom data that was passed from the client with call accept command
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`scheme`	`{ [id: string]: { audio: any, video: any } }`	✗	Internal information about codecs.

Forwarding

Triggers on an incoming/outgoing call forwarding.

Event constant: CallEvents.Forwarding

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

Disconnected

Triggered when a call is terminated.

Most frequent status codes (returned when a call is terminated before being answered):

CodeDescription

408Call is not answered within 60 seconds 603Call is rejected 486Destination number is busy 487Request terminated

You can find the complete list of rfc3261 response codes on Wikipedia.

Note that this event does not mean the end of the JavaScript session. The session without calls and/or ACD requests are automatically terminated after some time (see the session limits for details). It is a good idea to explicitly terminate the session with VoxEngine.terminate(/docs/references/voxengine/voxengine/terminate) after it is no longer needed.

Event constant: CallEvents.Disconnected

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`internalCode`	`number`	✓	Status code of the call (i.e., 486)
`reason`	`string`	✓	Reason of the call failure
`duration`	`number`	✓	Total call duration in seconds
`cost`	`number`	✓	Call cost in account currency
`direction`	`string`	✓	Call direction type according to billing

Failed

Triggered when an outgoing call is terminated before connection. Most frequent status codes:

CodeDescription

486Destination number is busy 487Request terminated 404Invalid number 480Destination number is unavailable 402Insufficient funds 603Call was rejected 408Call was not answered within 60 seconds

Event constant: CallEvents.Failed

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`code`	`number`	✓	Status code of the call (i.e., 486)
`reason`	`string`	✓	Status message of call failure

InfoReceived

Triggered when an INFO message is received.

Event constant: CallEvents.InfoReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`mimeType`	`string`	✓	MIME type of INFO message
`body`	`string`	✓	Content of the message

MessageReceived

Triggered when a text message is received.

Event constant: CallEvents.MessageReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`text`	`string`	✓	Content of the message

MicStatusChange

Triggers each time when microphone status changes. There is the method for enabling status analyzing - Call.handleMicStatus.

Event constant: CallEvents.MicStatusChange

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`active`	`boolean`	✓	Whether the microphone is active

OffHold

Triggered when a call is taken off hold.

Event constant: CallEvents.OffHold

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

OnHold

Triggered when a call is put on hold.

Event constant: CallEvents.OnHold

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

PlaybackFinished

Triggered when the audio/voice playback is completed. Note that the Call.stopPlayback method finishes any media**, so the CallEvents.PlaybackFinished event is not triggered. The playback may be started by the Call.say or Call.startPlayback methods.

Event constant: CallEvents.PlaybackFinished

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`error`	`string`	✗	Error that occurred during the playback

PlaybackReady

Triggers by the Call.startPlayback and Call.say methods when:

the audio file download to the Voximplant cache is finished;
the audio file is found in the cache (i.e., it is in the cache before).

Event constant: CallEvents.PlaybackReady

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

PlaybackStarted

Triggers by the Call.startPlayback and Call.say methods when audio/voice playback is started.

Event constant: CallEvents.PlaybackStarted

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`duration`	`number`	✓	Playback duration

PushSent

Triggered when a push notification is sent.

Event constant: CallEvents.PushSent

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`result`	`string`	✓

ReInviteAccepted

Triggered when the Voximplant cloud receives the ReInviteAccepted message. This message means that a call received video from the other participant.

Event constant: CallEvents.ReInviteAccepted

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`mimeType`	`string`	✓	MIME type of INFO message
`body`	`string`	✓	Content of the message

ReInviteReceived

Triggered when the Voximplant cloud receives the ReInviteReceived message. This message means that a caller:

started sending video;
started/stopped screensharing;
put a call on hold / took a call off hold.

Event constant: CallEvents.ReInviteReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`mimeType`	`string`	✓	MIME type of INFO message
`body`	`string`	✓	Content of the message

ReInviteRejected

Triggered when the Voximplant cloud receives the ReInviteRejected message. This message means that a call does not receive video from the other participant.

Event constant: CallEvents.ReInviteRejected

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)

RecordStarted

Triggered when call recording is started. The recording may be started by the Call.record method.

Event constant: CallEvents.RecordStarted

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`url`	`string`	✓	Link to the record file.

RecordStopped

Triggered when call recording is stopped. This happens after the CallEvents.Disconnected event is triggered.

Event constant: CallEvents.RecordStopped

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`url`	`string`	✓	Link to the record file.
`cost`	`string`	✓	Record cost (in the account’s currency: USD, EUR or RUB)
`duration`	`number`	✓	Record duration (sec)

RecordError

Triggers in case of errors during the recording process.

Event constant: CallEvents.RecordError

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`error`	`string`	✓	Triggers in case of errors during the recording process

Ringing

Triggers after outgoing call receives progress signal from a remote peer.

Event constant: CallEvents.Ringing

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)

StateChanged

Triggered when a call status is changed.

Event constant: CallEvents.StateChanged

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`oldState`	`string`	✓
`newState`	`string`	✓

Statistics

Triggered when call statistics change.

Event constant: CallEvents.Statistics

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

ToneDetected

Triggered when a call dial tone is detected (either dial tone or busy tone). There is the deprecated method for enabling the tone detection - ‘Call.detectProgressTone’. Note that:

triggers only if the CallEvents.Connected event is triggered;
the event is only triggered once in a call session.

Event constant: CallEvents.ToneDetected

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`ProgressTone`	`boolean`	✓	Whether the detected tone is a dial tone.
`VoicemailTone`	`boolean`	✓	Whether the detected tone is a voicemail tone.

ToneReceived

Triggered when a DTMF signal is received. Note that by default DTMF signals do not trigger this event, this behavior needs to be set explicitly via the Call.handleTones method.

Event constant: CallEvents.ToneReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`tone`	`string`	✓	Tone received in this event. The possible values are: 0-9,*,#
`type`	`string`	✓	Type of the received tone. The possible values are: 1 (rfc 2833), 2 (Inband), 3 (SipInfo)

TransferComplete

Triggered when a call transfer is complete.

Event constant: CallEvents.TransferComplete

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`role`	`’transferor’ \| ‘target’ \| ‘transferee’`	✗	The transfer roles.

TransferFailed

Triggered when a call transfer is failed.

Event constant: CallEvents.TransferFailed

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`headers`	`{ [header: string]: string }`	✗	SIP headers received with the message (the ones starting with “X-”)
`role`	`’transferor’ \| ‘target’ \| ‘transferee’`	✗	The transfer roles.
`code`	`number`	✓	Failed transfer’s status (e.g., 486)
`reason`	`string`	✓	Failed transfer’s status message

VideoTrackCreated

Triggers after the video track is created. This could happen only if the Call.record method with {video: true} parameters is called.

Event constant: CallEvents.VideoTrackCreated

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`url`	`string`	✓	Record URL

FirstAudioPacketReceived

Triggers after the first audio packet is received.

Event constant: CallEvents.FirstAudioPacketReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

FirstVideoPacketReceived

Triggers after the first video packet is received.

Event constant: CallEvents.FirstVideoPacketReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

RtpStopped

Triggers within 7 seconds after the RTP/RTCP has stopped. Applies to all types of calls (users, SIP, and PSTN).

Event constant: CallEvents.RtpStopped

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

RtpResumed

Triggers after the RTP resumed.

Event constant: CallEvents.RtpResumed

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID

BeepDetectionComplete

Triggers after the beep detection is complete. The beep detection may be started by the Call.enableBeepDetection method.

Event constant: CallEvents.BeepDetectionComplete

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`frequencies`	`number[]`	✗	Array of frequencies detected during the beep detection in Hz.
`timeout`	`boolean`	✗	Whether the timeout occurred during beep detection.

BeepDetectionError

Error during beep detection.

Event constant: CallEvents.BeepDetectionError

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`reason`	`string`	✓	Beep detection failure reason.

AudioQualityDetected

Triggers after the audio quality detected.

Event constant: CallEvents.AudioQualityDetected

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`quality`	`CallAudioQuality`	✓	The audio quality. Allowed values are listed in `CallAudioQuality`: `HD`, `STANDARD`.

MediaStatisticsReceived

Triggers after media statistics has been recieved. To enable, call the Call.monitorMediaStatistics method.

Event constant: CallEvents.MediaStatisticsReceived

Payload

Field	Type	Req.	Description
`call`	`Call`	✓	Call that triggered the event
`name`	`string`	✓	The name of the event
`id`	`string`	✓	The call’s ID
`audio`	`CallMediaStatistics`	✓	Statistical information about the audio channels. Contains metrics for both incoming and outgoing streams.

Parameter types

CallAnswerParameters

The parameters can be passed as arguments to the Call.answer method.

Property	Type	Req.	Description
`conferenceCall`	`boolean`	✗	inherited from BaseCallParameters Whether the call is coming from a conference. The default value is false.
`disableDtxForAudio`	`boolean`	✗	inherited from BaseCallParameters Disables DTX for audio. The default value is false.
`disableExtPlayoutDelay`	`boolean`	✗	inherited from BaseCallParameters Whether to disable the RTP header extension to control playout delay if provided.
`disableExtVideoOffset`	`boolean`	✗	inherited from BaseCallParameters Whether to disable the RTP header extension for transmission offset if provided.
`disableExtVideoOrientation`	`boolean`	✗	inherited from BaseCallParameters Whether to disable the RTP header extension for video orientation, 3gpp:video-orientation, if provided. Browsers that do not support that extension display the video correctly, however, the battery consumption is higher.
`disableExtVideoTiming`	`boolean`	✗	inherited from BaseCallParameters Whether to disable the RTP header extension for video timing if provided.
`displayName`	`string`	✗	inherited from BaseCallParameters Name of the caller that is displayed to the user. Normally it is a human-readable version of CallerID, e.g. a person’s name.
`maxVideoBitrate`	`number`	✗	inherited from BaseCallParameters Sets the maximum possible video bitrate for the customer device in kbps.
`scheme`	`{ [id: string]: { audio: any, video: any } }`	✗	inherited from BaseCallParameters Internal information about codecs.

CallEnableBeepDetectionParameters

Parameters for the Call.enableBeepDetection method.

Property	Type	Req.	Description
`frequencies`	`number[]`	✗	Array of frequencies to detect in Hz.
`timeout`	`number`	✗	Timeout in milliseconds to wait for the beep detection.

CallRecordParameters

The parameters can be passed as arguments to the Call.record method.

Property	Type	Req.	Description
`dict`	`ASRDictionary \| string[]`	✗	Transcription dictionary. Array of words that are possible values. Note that dict does not limit the transcription to the specific list. Instead, words in the specified list have a higher chance to be selected. Note that the parameter does not affect the Recorder module because the transcription is not available for it.
`expire`	`RecordExpireTime`	✗	inherited from BaseRecorderParameters Storage time for recorded files. The default value is `RecordExpireTime.THREEMONTHS`(/docs/references/voxengine/recordexpiretime#threemonths).
`format`	`string`	✗	Transcription format. Could be specified as “json”. In that case the transcription result is saved in JSON format. The parameter is not available for the Recorder module.
`hd_audio`	`boolean`	✗	inherited from BaseRecorderParameters Whether to use the HD audio. The default value is false. If set to false, 8 KHz / 32 kbps mp3 file is generated. If set to true, “wideband audio” 48 KHz / 192 kbps mp3 file is generated. Note that transcription’s quality does not depend on this parameter. The parameter is not compatible with lossless: true parameter.
`labels`	`string[]`	✗	An array of two strings. Each string names the label in resulting transcription: the first string names a call/stream that initiated recording, the second string names the other call. If there is only one string in the array or the parameter is not specified at all, the recording’s initiate call has the “Left” name and the second stream has the “Right” name. The parameter requires the transcribe: true parameter. The parameter is not available for the Recorder module.
`language`	`ASRLanguage`	✗	inherited from BaseRecorderParameters Transcription language. The parameter uses ASRLanguage from the ASR module as possible values. Note that it is necessary to include the ASR module in the scenario to use the language constants. The parameter is not available for the Recorder module.
`lossless`	`boolean`	✗	inherited from BaseRecorderParameters Whether to save the record in flac format. The default value is false. The parameter is not compatible with hd_audio: true parameter.
`provider`	`TranscriptionProvider`	✗	Transcription provider.
`recordNamePrefix`	`string`	✗	inherited from BaseRecorderParameters The prefix to add to the record names when storing to your S3 storage. Works only for custom S3-compatible storages.
`secure`	`boolean`	✗	inherited from BaseRecorderParameters Whether to restrict access to the record without management API authorization (available only in the `VoxEngine.createRecorder` method).
`stereo`	`boolean`	✗	Whether the sound is stereo. The default value is false. The parameter does not change anything for the Recorder module: it records stereo with mixed streams in both channels. For the `Call.record` method it works in another way: 1. if it is False, it records stereo with mixed streams in both channels 2. if it is True, the Audio stream from a call endpoint to voximplant cloud is recorded into left channel. Audio stream from voximplant cloud to a call endpoint is recorded into right channel.
`transcribe`	`boolean`	✗	inherited from BaseRecorderParameters Whether to create the call record transcription. Note that transcription is not available for the Recorder module. See the details in the article.
`video`	`boolean`	✗	inherited from BaseRecorderParameters Whether to record video. The default value is false.
`videoParameters`	`RecorderVideoParameters`	✗	inherited from BaseRecorderParameters Recorder video parameters.

CallSayParameters

The parameters can be passed as arguments to the Call.say method.

Property	Type	Req.	Description
`progressivePlayback`	`boolean`	✗	Whether to use progressive playback. If true, the generated speech is delivered in chunks which reduces delay before a method call and playback. The default value is false. Available for providers: Amazon, Google, IBM, Microsoft, SaluteSpeech, T-Bank, Yandex.
`request`	`Object`	✗	Provide the TTS parameters directly to the provider in this parameter. Find more information in the `documentation`(/docs/guides/speech/tts#passing-parameters-directly-to-the-provider). Available for providers: Google, SaluteSpeech, T-Bank, YandexV3.
`ttsOptions`	`TTSOptions`	✗	Parameters for TTS. Note that support of the `TTSOptions.pitch` parameter depends on the language and dictionary used. For unsupported combinations the `CallEvents.PlaybackFinished` event is triggered with error 400. Available for providers: Amazon, Google, IBM, Microsoft, SaluteSpeech, T-Bank, Yandex.
`voice`	`Voice`	✗	Voice for TTS. List of all supported voices: VoiceList. The default value is VoiceList.Amazon.en_US_Joanna. Available for providers: Amazon, Google, IBM, Microsoft, SaluteSpeech, T-Bank, Yandex, ElevenLabs.

SendMediaParameters

Custom parameters for WebSocket interaction. Can be passed as arguments to the VoxMediaUnit sendMediaTo method.

Property	Type	Req.
`customParameters`	`any`	✗
`encoding`	`WebSocketAudioEncoding`	✗
`tag`	`string`	✓

StartPlaybackParameters

The parameters can be passed as arguments to the Call.startPlayback method.

Property	Type	Req.	Description
`loop`	`boolean`	✗	Whether to loop playback.
`progressivePlayback`	`boolean`	✗	Whether to use progressive playback. If true, the file is delivered in chunks which reduces delay before a method call and playback. The default value is false.

TransferToParameters

The parameters can be passed as arguments to the Call.transferTo method.

Property	Type	Req.	Description
`call`	`Call`	✓	Call (for ‘attendant transfer’ only)
`headers`	`{ [header: string]: string }`	✗	Custom parameters (SIP headers) that should be passed with a call (INVITE) message. Custom header names have to begin with the ‘X-’ prefix except the ‘VI-CallTimeout’: ‘60’ which hangs up if there is no answer after the timeout (in seconds, the default value is 60, must not be less than 10 or greater than 400). The “X-” headers can be handled by a SIP phone or WEB SDK (e.g. see the `incomingCall`(/docs/references/websdk/voximplant/events#incomingcall) event). Example: {‘X-header’:‘value’}.
`to`	`string`	✓	SIP(S) URI to make a call to. Example of an external call: sip:alice@example.org. Examples with the usage of TLS: sips:alice@example.org:5061 ; alice@example.org:5061;transport=tls. The format for calls to another user of the same Voximplant application: user-of-the-application@application-name.account-name.voximplant.com

MonitorMediaStatisticsParameters

The parameters can be passed as arguments to the Call.monitorMediaStatistics method.

Property	Type	Req.	Description
`interval`	`number`	✓	Interval between messages (in seconds). The value must not be less than 3 or greater than 10.
`monitor`	`boolean`	✓	Enables or disables media statistics monitoring.

Related guides

Contents

Methods

.fa-secondary{opacity:.4} addEventListener

.fa-secondary{opacity:.4} answer

.fa-secondary{opacity:.4} answerDirect

.fa-secondary{opacity:.4} callerid

.fa-secondary{opacity:.4} clientType

.fa-secondary{opacity:.4} customData

.fa-secondary{opacity:.4} decline

Deprecated

.fa-secondary{opacity:.4} disableBeepDetection

.fa-secondary{opacity:.4} displayName

.fa-secondary{opacity:.4} enableBeepDetection

.fa-secondary{opacity:.4} handleBlindTransfer

.fa-secondary{opacity:.4} handleMicStatus

.fa-secondary{opacity:.4} handleTones

.fa-secondary{opacity:.4} hangup

.fa-secondary{opacity:.4} id

.fa-secondary{opacity:.4} incoming

.fa-secondary{opacity:.4} monitorMediaStatistics

.fa-secondary{opacity:.4} notifyBlindTransferFailed

.fa-secondary{opacity:.4} notifyBlindTransferSuccess

.fa-secondary{opacity:.4} number

.fa-secondary{opacity:.4} playProgressTone

.fa-secondary{opacity:.4} record

.fa-secondary{opacity:.4} reject

.fa-secondary{opacity:.4} removeEventListener

.fa-secondary{opacity:.4} ring

.fa-secondary{opacity:.4} say

.fa-secondary{opacity:.4} sendDigits

.fa-secondary{opacity:.4} sendInfo

.fa-secondary{opacity:.4} sendMediaTo

.fa-secondary{opacity:.4} sendMessage

.fa-secondary{opacity:.4} startEarlyMedia

.fa-secondary{opacity:.4} startPlayback

.fa-secondary{opacity:.4} state

.fa-secondary{opacity:.4} stopMediaTo

.fa-secondary{opacity:.4} stopPlayback

.fa-secondary{opacity:.4} toString

.fa-secondary{opacity:.4} transferTo

.fa-secondary{opacity:.4} vad

CallEvents

AudioStarted

AudioIdentificationStarted

AudioIdentificationResult

AudioIdentificationStopped

AudioIdentificationError

BlindTransferRequested

Connected

Forwarding

Disconnected

Failed

InfoReceived

MessageReceived

MicStatusChange

OffHold

OnHold

PlaybackFinished

PlaybackReady

PlaybackStarted

PushSent

ReInviteAccepted

ReInviteReceived

ReInviteRejected

RecordStarted

RecordStopped

RecordError

Ringing

StateChanged

Statistics

ToneDetected

ToneReceived

TransferComplete

TransferFailed

VideoTrackCreated

FirstAudioPacketReceived

FirstVideoPacketReceived

RtpStopped

RtpResumed

addEventListener

answer

answerDirect

callerid

clientType

customData

decline

disableBeepDetection

displayName

enableBeepDetection

handleBlindTransfer

handleMicStatus

handleTones

hangup

id

incoming

monitorMediaStatistics

notifyBlindTransferFailed

notifyBlindTransferSuccess

number

playProgressTone

record

reject

removeEventListener

ring

say

sendDigits

sendInfo

sendMediaTo

sendMessage

startEarlyMedia

startPlayback

state

stopMediaTo

stopPlayback

toString

transferTo

vad

CallAnswerParameters

CallEnableBeepDetectionParameters

CallRecordParameters

CallSayParameters

SendMediaParameters

StartPlaybackParameters

TransferToParameters

MonitorMediaStatisticsParameters