@vonage/voice
Version:
The Voice API lets you create outbound calls, control in-progress calls and get information about historical calls.
416 lines • 14.7 kB
TypeScript
import { AuthenticationType, Client } from '@vonage/server-client';
import { GetCallDetailsParameters, CallPageResponse, CallDetail, CallResult, CallUpdateResult, UpdateCallResponse, Action, TalkAction, OutboundCall } from './types';
type NCCODestination = {
type: 'ncco';
url?: Array<string>;
ncco?: Array<Action>;
};
/**
* A Clint to make calls to the Vonage Voice API.
*
* @remarks
* Vonage API's will return information using `snake_case`. This represents the
* pure response before the client will transform the keys into `camelCase`.
*
* @example
* Create a standalone Voice client
*
* ```ts
* import { Voice } from '@vonage/voice';
*
* const voiceClient = new Voice({
* apiKey: VONAGE_API_KEY,
* apiSecret: VONAGE_API_SECRET
* });
* ```
*
* @example
* Create an Voice client from the Vonage client
*
* ```ts
* import { Vonage } from '@vonage/server-client';
*
* const vonage = new Vonage({
* apiKey: VONAGE_API_KEY,
* apiSecret: VONAGE_API_SECRET
* });
*
* const voiceClient = vonage.voice;
* ```
*/
export declare class Voice extends Client {
protected authType: AuthenticationType;
/**
* Retrieves details of all calls using pagination.
*
* @param {GetCallDetailsParameters} params - Optional parameters for filtering and pagination.
* @return {AsyncGenerator<CallDetail, void, undefined>} An async generator that yields call details or void when there are no more results.
*
* @example
* ```ts
* for await (const call of voiceClient.getAllCalls()) {
* console.log(call.startTime);
* }
* ```
*/
getAllCalls(params?: GetCallDetailsParameters): AsyncGenerator<CallDetail, void & CallDetail, undefined>;
/**
* Retrieves a page of call details based on the specified parameters.
*
* @param {GetCallDetailsParameters} params - Optional parameters for filtering and pagination.
* @return {Promise<CallPageResponse>} A promise that resolves to a page of call details.
*
* @example
* ```ts
* const page = await voiceClient.getCallsPage();
* for (const call of page._embedded.calls) {
* console.log(call.startTime);
* }
* ```
*
* @example
* Get the next page of call details
* ```ts
* const page = await voiceClient.getCallsPage({
* pageSize: 4,
* recordIndex: 10,
* });
* for (const call of page._embedded.calls) {
* console.log(call.startTime);
* }
* ```
*
* @example
* Get all started calls
* ```ts
* import { CallStatus } from '@vonage/voice';
*
* const page = await voiceClient.getCallsPage({
* pageSize: 4,
* recordIndex: 10,
* status: CallStatus.STARTED,
* });
* for (const call of page._embedded.calls) {
* console.log(call.startTime);
* }
* ```
*/
getCallsPage(params: GetCallDetailsParameters): Promise<CallPageResponse>;
/**
* Searches for call details based on the provided filter.
*
* @param {GetCallDetailsParameters} [filter] - Optional filter criteria to narrow down the search.
* @return {Promise<CallPageResponse>} A promise that resolves to a page of call details matching the filter.
*
* @example
* ```ts
* const page = await voiceClient.search({
* pageSize: 4,
* });
*
* for (const call of page._embedded.calls) {
* console.log(call.startTime);
* console.log(call.status);
* console.log(call.direction);
* console.log(call.duration);
* };
* ```
*/
search(filter: GetCallDetailsParameters): Promise<CallPageResponse>;
/**
* Retrieves detailed information about a specific call using its UUID.
*
* @param {string} uuid - The UUID of the call to retrieve details for.
* @return {Promise<CallDetail>} A promise that resolves to detailed information about the call.
*
* @example
* ```ts
* const call = await voiceClient.getCall('CALL_UUID');
* console.log(call.startTime);
* ```
*/
getCall(uuid: string): Promise<CallDetail>;
/**
* Initiates an outbound call with the specified configuration.
*
* @param {OutboundCall} call - The configuration for the outbound call.
* @return {Promise<CallResult>} A promise that resolves to the result of the outbound call initiation.
*
* @example
* Create a call with answer NCCO
* ```ts
* const call = await voiceClient.createOutboundCall({
* to: [{
* type: 'phone',
* number: TO_NUMBER
* }],
* asnwer_url: ['https://example.com/answer'],
* });
*
* console.log(call.uuid);
*
* ```
* @example
* Create a call with answer URL
* ```ts
* const call = await voiceClient.createOutboundCall({
* to: [{
* type: 'phone',
* number: TO_NUMBER
* }],
* ncco: [{
* action: 'talk',
* text: 'This is a text to speech call from Vonage'
* }]
* });
*
* console.log(call.uuid);
* ```
*/
createOutboundCall(call: OutboundCall): Promise<CallResult>;
/**
* Plays DTMF (Dual-Tone Multi-Frequency) tones on an active call.
*
* @param {string} uuid - The UUID of the call on which to play DTMF tones.
* @param {string} digits - The DTMF tones to play.
* @return {Promise<CallUpdateResult>} A promise that resolves to the result of playing DTMF tones on the call.
*
* @example
* ```ts
* const result = await voiceClient.playDTMF('CALL_UUID', '1234');
* console.log(result.status);
* ```
*/
playDTMF(uuid: string, digits: string): Promise<CallUpdateResult>;
/**
* Register a listener to receive asynchronous DTMF inputs from a call
*
* This is only applicable to Input NCCO events with the mode set to
* asynchronous. The payload delivered to this URL will be an Input webhook
* event with a single DTMF digit every time the callee enters DTMF into the
* call.
*
* @param {string} uuid - The UUID of the call leg
* @param {string} eventUrl - The The URL to send DTMF events to, as a POST request.
* @return {Promise<void>} A promise that resolves to the result
*
* @example
* ```ts
* const result = await voiceClient.subscribeDTMF('CALL_UUID', 'https://example.com/dtmf');
* console.log(result.status);
* ```
*/
subscribeDTMF(uuid: string, eventUrl: string): Promise<void>;
/**
* Removes the registered DTMF listener
* @param {string} uuid - The UUID of the call leg
* @return {Promise<void>} A promise that resolves to the result
*
* @example
* ```ts
* const result = await voiceClient.subscribeDTMF('CALL_UUID', 'https://example.com/dtmf');
* console.log(result.status);
* ```
*/
unsubscribeDTMF(uuid: string): Promise<void>;
/**
* Plays text-to-speech (TTS) audio on an active call.
*
* @param {string} uuid - The UUID of the call on which to play TTS audio.
* @param {TalkAction} action - The TTS action configuration.
* @return {Promise<CallUpdateResult>} A promise that resolves to the result of playing TTS audio on the call.
*
* @example
* ```ts
* const result = await voiceClient.playTTS(
* CALL_UUID,
* {
* text: 'This is a text to speech call from Vonage',
* },
* );
*
* console.log(result.status);
* ```
*/
playTTS(uuid: string, action: TalkAction): Promise<CallUpdateResult>;
/**
* Stops any ongoing text-to-speech (TTS) audio playback on an active call.
*
* @param {string} uuid - The UUID of the call on which to stop TTS audio playback.
* @return {Promise<CallUpdateResult>} A promise that resolves to the result of stopping TTS audio playback on the call.
*
* @example
*
* ```ts
* const result = await voiceClient.stopTTS(CALL_UUID);
* console.log(result.status);
* ```
*/
stopTTS(uuid: string): Promise<CallUpdateResult>;
/**
* Stream audio to an active call, allowing you to play audio files or live audio streams.
*
* @param {string} uuid - The UUID of the call to which to stream audio.
* @param {string} url - The URL of the audio stream to play.
* @param {number} [loop=1] - The number of times to loop the audio stream (default is 1).
* @param {number} [volumeLevel=0.0] - The volume level of the audio stream (0.0 to 1.0, default is 0.0).
* @return {Promise<UpdateCallResponse>} A promise that resolves to the result of streaming audio to the call.
*
*
* @example
* ```ts
* const result = await voiceClient.streamAudio(CALL_UUID, 'https://example.com/audio.mp3');
* console.log(result.message);
* ```
*/
streamAudio(uuid: string, url: string, loop?: number, volumeLevel?: number): Promise<UpdateCallResponse>;
/**
* Stop streaming audio to an active call.
*
* @param {string} uuid - The UUID of the call from which to stop streaming audio.
* @return {Promise<CallUpdateResult>} A promise that resolves to the result of stopping audio streaming to the call.
*
* @example
* ```ts
* const result = await voiceClient.stopStreamAudio(CALL_UUID);
* console.log(result.message);
* ```
*/
stopStreamAudio(uuid: string): Promise<CallUpdateResult>;
/**
* Transfer an active call to a new destination using a Nexmo Call Control Object (NCCO).
*
* @param {string} uuid - The UUID of the call to transfer.
* @param {Action[]} ncco - The NCCO actions defining the transfer destination.
* @return {Promise<void>} A promise that resolves when the call has been successfully transferred.
*
* @example
* ```ts
* await voiceClient.transferCallWithNCCO(
* CALL_UUID,
* [{
* action: 'talk',
* text: 'You will now be transferred to a new destination''
* }],
* )
* ```
*/
transferCallWithNCCO(uuid: string, ncco: Action[]): Promise<void>;
/**
* Transfer an active call to a new destination using a URL.
*
* @param {string} uuid - The UUID of the call to transfer.
* @param {string} url - The URL of the transfer destination.
* @return {Promise<void>} A promise that resolves when the call has been successfully transferred.
*
* @example
* ```ts
* await voiceClient.transferCallWithURL(
* CALL_UUID,
* 'https://example.com/transfer',
* );
* ```
*/
transferCallWithURL(uuid: string, url: string): Promise<void>;
/**
* Hang up an active call.
*
* @param {string} uuid - The UUID of the call to hang up.
* @return {Promise<void>} A promise that resolves when the call has been successfully hung up.
* @example
* ```ts
* await voiceClient.hangupCall(CALL_UUID);
* ```
*/
hangupCall(uuid: string): Promise<void>;
/**
* Mute an active call.
*
* @param {string} uuid - The UUID of the call to mute.
* @return {Promise<void>} A promise that resolves when the call has been successfully muted.
*
* @example
* ```ts
* await voiceClient.muteCall(CALL_UUID);
* ```
*/
muteCall(uuid: string): Promise<void>;
/**
* Unmute a muted call, allowing audio to be transmitted again.
*
* @param {string} uuid - The UUID of the call to unmute.
* @return {Promise<void>} A promise that resolves when the call has been successfully unmuted.
*
* @example
* ```ts
* await voiceClient.unmuteCall(CALL_UUID);
* ```
*/
unmuteCall(uuid: string): Promise<void>;
/**
* Places a call on earmuff, muting the audio for all participants except the user.
*
* @param {string} uuid - The UUID of the call to earmuff.
* @return {Promise<void>} A promise that resolves when the call has been successfully earmuffed.
*
* @example
* ```ts
* await voiceClient.earmuffCall(CALL_UUID);
* ```
*/
earmuffCall(uuid: string): Promise<void>;
/**
* Remove an earmuff from a call, allowing all participants to hear each other again.
*
* @param {string} uuid - The UUID of the call to unearmuff.
* @return {Promise<void>} A promise that resolves when the call has been successfully unearmuffed.
*
* @example
* ```ts
* await voiceClient.unearmuffCall(CALL_UUID);
* ```
*/
unearmuffCall(uuid: string): Promise<void>;
/**
* Download the recording of a call to the specified file path.
*
* @param {string} file - The name or recording id of the recording file to download.
* @param {string} path - The local file path where the recording will be saved.
* @return {Promise<void>} A promise that resolves when the recording has been successfully downloaded.
*
* @example
* ```ts
* await voiceClient.downloadRecording(RECORDING_UUID, './recording.mp3');
* ```
*/
downloadRecording(file: string, path: string): Promise<void>;
/**
* Download the transcription of a call to the specified file path.
*
* @param {string} file - The name or transcription id of the recording file to download.
* @param {string} path - The local file path where the transcription will be saved.
* @return {Promise<void>} A promise that resolves when the transcription has been successfully downloaded.
*
* @example
* ```ts
* await voiceClient.downloadTranscription(TRANSCRIPTION_UUID, './transcription.txt');
* ```
*/
downloadTranscription(file: string, path: string): Promise<void>;
/**
* Send a call action to a specific call identified by its UUID.
*
* @param {string} uuid - The UUID of the call to which the action should be applied.
* @param {string} action - The action to perform on the call (e.g., 'hangup', 'mute', 'unmute').
* @param {NCCODestination} [destination] - The destination details for transfer actions.
* @return {Promise<void>} A promise that resolves when the call action has been successfully executed.
*
* @example
* ```ts
* await voiceClient.callAction(CALL_UUID, 'mute');
* ```
*/
protected callAction(uuid: string, action: string, destination?: NCCODestination): Promise<void>;
}
export {};
//# sourceMappingURL=voice.d.ts.map