Call
Represents an audio or video call.
Methods
addEventListener
addEventListener(event: , callback: Function
): void
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.
Parameters
event:
Event class (i.e., CallEvents.Connected)
callback:
Function
Handler function. A single parameter is passed - object with event information
Returns
type:
void
answer
answer(extraHeaders: {[header: string]: string}
, parameters: ): void
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.
Parameters
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the answer 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 Connected event). Example: {'X-header':'value'}
parameters:
OptionalOptional. Answering call parameters
Returns
type:
void
answerDirect
answerDirect(peerCall: , extraHeaders: {[header: string]: string}
, parameters: ): void
Answer the incoming call in the peer-to-peer mode. Use it only for P2P call legs connection.
Parameters
peerCall:
The other P2P call leg.
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the answer 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 Connected (/docs/references/websdk/enums/callevents.html#connected) event). Example: {'X-header':'value'}
parameters:
OptionalOptional. Answering call parameters
Returns
type:
void
callerid
callerid(): string
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.
Returns
type:
string
clientType
clientType(): string
Returns a type of the client.
Returns
type:
string
customData
customData(customData: string
): string
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 object. Note that if you receive a value from an SDK, you can always replace it manually.
SDKs can pass customData in two ways:
1) when SDK calls the Voximplant cloud
2) 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()
Parameters
customData:
string
OptionalOptional. Custom call data to set. Maximum size is 200 bytes
Returns
type:
string
decline
Use Call.reject instead
decline(code: number
, extraHeaders: {[header: string]: string}
): void
Rejects the incoming call.
Parameters
code:
number
SIP status code
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the reject 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
type:
void
displayName
displayName(): string
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.
Returns
type:
string
handleBlindTransfer
handleBlindTransfer(handle: boolean
): void
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.
Parameters
handle:
boolean
Enable/disable blind transfers
Returns
type:
void
handleMicStatus
handleMicStatus(handle: boolean
): void
Whether to enable detection of microphone status in the call. If detection is enabled, the CallEvents.MicStatusChange event is triggered at each status' change.
Parameters
handle:
boolean
Enable/disable microphone status analysis. The default value is false
Returns
type:
void
handleTones
handleTones(doHandle: boolean
, supportedDtmfTypes: ): void
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.
Parameters
doHandle:
boolean
Whether to enable DTMF analysis. The default values is true
supportedDtmfTypes:
OptionalThe DTMF type to process. The default value is ALL
Returns
type:
void
hangup
hangup(extraHeaders: {[header: string]: string}
): void
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).
Parameters
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the 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
type:
void
id
id(): string
Returns the call's id. Each call in a JavaScript session has its own unique id.
Returns
type:
string
incoming
incoming(): boolean
Whether the call is incoming.
Returns
type:
boolean
notifyBlindTransferFailed
notifyBlindTransferFailed(code: number
, reason: string
): void
Sends a notification about a failed call transfer with an error code and reason.
Parameters
code:
number
Error code
reason:
string
Reason why the blind transfer is failed
Returns
type:
void
notifyBlindTransferSuccess
notifyBlindTransferSuccess(): void
Sends a notification of a successful call transfer with the 200 OK message.
Returns
type:
void
number
number(): string
Returns a dialed number of the incoming or outgoing call.
Returns
type:
string
playProgressTone
playProgressTone(country: string
): void
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.
Parameters
country:
string
2-letter country code. Currently supported values are US, RU
Returns
type:
void
record
record(parameters: ): void
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.
Parameters
parameters:
Recorder parameters
Returns
type:
void
reject
reject(code: number
, extraHeaders: {[header: string]: string}
): void
Rejects the incoming call. First it triggers the CallEvents.Disconnected event immediately. The AppEvents.Terminating and AppEvents.Terminated events are triggered in 60 seconds.
Parameters
code:
number
SIP status code with the rejection reason. You can pass any standard SIP code starting with 3xx, 4xx, 5xx and 6xx as a reject reason.
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the reject 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
type:
void
removeEventListener
removeEventListener(event: , callback: Function
): void
Removes a handler for the specified CallEvents event.
Parameters
event:
Event class (i.e., CallEvents.Connected)
callback:
Function
OptionalOptional. Handler function. If not specified, all handler functions are removed
Returns
type:
void
ring
ring(extraHeaders: {[header: string]: string}
): void
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.
Parameters
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the 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
type:
void
say
This method internally operates with the Player class and its events. Use the VoxEngine.createTTSPlayer to get more flexibility
say(text: string
, parameters: ): void
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.
Parameters
text:
string
Message that is played to the call. To put an accent to the specified syllable, use the <say-as stress='1'></say-as> tag
parameters:
OptionalOptional. TTS parameters
Returns
type:
void
sendDigits
sendDigits(digits: string
): void
Sends DTMF digits to the remote peer.
Parameters
digits:
string
Any combination of 0-9, *, #, p (pause) symbols
Returns
type:
void
sendInfo
sendInfo(mimeType: string
, body: string
, headers: {[header: string]: string}
): void
Sends info (SIP INFO) message to the call.
Parameters
mimeType:
string
MIME type of the message
body:
string
Message content. Maximum size is 8192 bytes according to the limits
headers:
{[header: string]: string}
OptionalOptional. 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
type:
void
sendMediaTo
sendMediaTo(mediaUnit: , parameters: ): void
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.
Parameters
mediaUnit:
Media unit that receives media
parameters:
OptionalOptional. WebSocket interaction only parameters
Returns
type:
void
sendMessage
sendMessage(text: string
): void
Sends a text message to the call.
Parameters
text:
string
Message text. Maximum size is 8192 bytes according to the limits
Returns
type:
void
startEarlyMedia
startEarlyMedia(extraHeaders: {[header: string]: string}
, scheme: string
, maxVideoBitrate: number
, audioLevelExtension: false
| true
, conferenceCall: false
| true
): void
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.
Parameters
extraHeaders:
{[header: string]: string}
OptionalOptional. Custom parameters (SIP headers) that should be passed with the 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'}
scheme:
string
OptionalOptional. Internal information about codecs from the AppEvents.CallAlerting event
maxVideoBitrate:
number
OptionalOptional. Set the maximum possible video bitrate for the customer device in kbps
audioLevelExtension:
false
OptionalOptional. Audio level extension
conferenceCall:
false
OptionalOptional. Whether the call is coming from a conference. The default value is false
Returns
type:
void
startPlayback
startPlayback(url: string
, parameters: ): void
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.
Parameters
url:
string
HTTP/HTTPS url to the audio file. The file is cached after the first playing. Supported formats are: mp3, ogg, flac, and wav (mp3, speex, vorbis, flac, and wav codecs respectively). Maximum file size is 10 Mb
parameters:
OptionalOptional. Playback parameters
Returns
type:
void
state
state(): string
Returns the current state of the call. Possible values are: TERMINATED | CONNECTED | PROGRESSING | ALERTING.
Returns
type:
string
stopMediaTo
stopMediaTo(mediaUnit: ): void
Stops sending media (voice and video) from the call to media unit.
Parameters
mediaUnit:
Media unit that does not need to receive media from this call anymore
Returns
type:
void
stopPlayback
stopPlayback(): void
Stops audio playback started before via the Call.startPlayback method.
Returns
type:
void
toString
toString(): string
Returns the human-readable description of the call's status.
Returns
type:
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
type:
boolean