UNPKG

@vonage/voice

Version:

The Voice API lets you create outbound calls, control in-progress calls and get information about historical calls.

995 lines (982 loc) 28.1 kB
"use strict"; var __create = Object.create; var __defProp = Object.defineProperty; var __getOwnPropDesc = Object.getOwnPropertyDescriptor; var __getOwnPropNames = Object.getOwnPropertyNames; var __getProtoOf = Object.getPrototypeOf; var __hasOwnProp = Object.prototype.hasOwnProperty; var __export = (target, all) => { for (var name in all) __defProp(target, name, { get: all[name], enumerable: true }); }; var __copyProps = (to, from, except, desc) => { if (from && typeof from === "object" || typeof from === "function") { for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable }); } return to; }; var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps( // If the importer is in node compatibility mode or this is not an ESM // file that has been converted to a CommonJS file using a Babel- // compatible transform (i.e. "__esModule" has not been set), then set // "default" to the CommonJS "module.exports" for node compatibility. isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod )); var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod); // lib/classes/index.ts var classes_exports = {}; __export(classes_exports, { Connect: () => Connect, Conversation: () => Conversation, Input: () => Input, NCCOBuilder: () => NCCOBuilder, Notify: () => Notify, OutboundCall: () => OutboundCall, OutboundCallWithAnswerURL: () => OutboundCallWithAnswerURL, OutboundCallWithNCCO: () => OutboundCallWithNCCO, Record: () => Record, Stream: () => Stream, Talk: () => Talk }); module.exports = __toCommonJS(classes_exports); // lib/classes/OutboundCall.ts var import_debug = __toESM(require("debug")); (0, import_debug.default)("@vonage/voice")( "This class is deprecated. Please update to use the CommonOutboundCall type" ); var OutboundCall = class { /** * The list of call endpoints to which the outbound call will be made. */ to; /** * The phone endpoint object representing the caller's information. */ from; /** * Indicates whether to use a random from number (optional). */ randomFromNumber; /** * The list of event URLs (optional). */ eventUrl; /** * The HTTP method to use for event notifications (optional). */ eventMethod; /** * The machine detection behavior (optional). */ machineDetection; /** * The length timer for the call (optional). */ lengthTimer; /** * The ringing timer for the call (optional). */ ringingTimer; /** * Creates a new outbound call. * * @param {CallEndpoint} to - The call endpoint to which the outbound call will be made. * @param {PhoneEndpointObject} [from] - The phone endpoint object representing the caller's information. */ constructor(to, from) { this.to = [to]; this.from = from; } }; // lib/classes/OutboundCallWithAnswerURL.ts var import_debug2 = __toESM(require("debug")); (0, import_debug2.default)("@vonage/voice")( "This class is deprecated. Please update to use the CallWithAnswerURL type" ); var OutboundCallWithAnswerURL = class extends OutboundCall { /** * The list of answer URLs. */ /* tslint:disable-next-line */ answer_url; /** * The list of answer URLs. * * @deprecated Use `answer_url` instead. */ answerUrl; /** * Creates a new outbound call with an answer URL. * * @param {string} answerUrl - The answer URL for the call. * @param {CallEndpoint} to - The call endpoint to which the outbound call will be made. * @param {PhoneEndpointObject} [from] - The phone endpoint object representing the caller's information. */ constructor(answerUrl, to, from) { super(to, from); this.answer_url = [answerUrl]; this.answerUrl = [answerUrl]; } }; // lib/classes/OutboundCallWithNCCO.ts var import_debug3 = __toESM(require("debug")); (0, import_debug3.default)("@vonage/voice")( "This class is deprecated. Please update to use the CallWithNCCO type" ); var OutboundCallWithNCCO = class extends OutboundCall { /** * The list of NCCO actions. */ ncco; /** * Creates a new outbound call with NCCO. * * @param {Array<NCCOAction>} ncco - The NCCO actions for the call. * @param {CallEndpoint} to - The call endpoint to which the outbound call will be made. * @param {PhoneEndpointObject} [from] - The phone endpoint object representing the caller's information. */ constructor(ncco, to, from) { super(to, from); this.ncco = ncco; } }; // lib/classes/NCCO/Connect.ts var Connect = class { /** * The action type, which is always 'connect'. */ action = "connect" /* CONNECT */; /** * An array of CallEndpoint objects representing the endpoints to connect to in the call. * * @param {CallEndpoint} endpoint - An array of CallEndpoint objects * representing the endpoints to connect to in the call. */ endpoint; /** * The caller's phone number to display as the caller ID. * * @param {string} from - The caller's phone number to display as the caller ID. */ from; /** * Set to true to use a random phone number as the caller ID from the list of * numbers assigned to the current application. * * @param {boolean} randomFromNumber - Set to true to use a random phone number as the caller ID. */ randomFromNumber; /** * The event type for call progress events sent to the specified event URL. * * @param {ConnectEventType} eventType - The event type for call progress events. */ eventType; /** * The time in seconds that Vonage waits for the call to be answered before timing out. * * @param {number} timeout - The timeout value in seconds. */ timeout; /** * The maximum number of concurrent calls that can be handled by your application. * * @param {number} limit - The maximum number of concurrent calls. */ limit; /** * Configure the behavior when Vonage detects that the call is answered by voicemail. * * @param {MachineDetection} machineDetection - The behavior when voicemail is detected. */ machineDetection; /** * An array of event URLs where call progress events are sent to. Multiple URLs can be specified. * * @param {string} eventUrl - An array of event URLs. */ eventUrl; /** * The HTTP method used to send event information to the event URL(s). * * @param {string} eventMethod - The HTTP method used for event callbacks. */ eventMethod; /** * The URL of a ringback tone to play to the caller while waiting for the call to be answered. * * @param {string} ringbackTone - The URL of the ringback tone audio file. */ ringbackTone; /** * Create a new Connect instance. * * @param {CallEndpoint} endpoint - An array of CallEndpoint objects representing the endpoints to connect to in the call. * @param {string} from - The caller's phone number to display as the caller ID. * @param {boolean} randomFromNumber - Set to true to use a random phone number as the caller ID. * @param {ConnectEventType} eventType - The event type for call progress events. * @param {number} timeout - The timeout value in seconds. * @param {number} limit - The maximum number of concurrent calls. * @param {MachineDetection} machineDetection - The behavior when voicemail is detected. * @param {string} eventUrl - An array of event URLs. * @param {string} eventMethod - The HTTP method used for event callbacks. * @param {string} ringbackTone - The URL of the ringback tone audio file. */ constructor(endpoint, from, randomFromNumber, eventType, timeout, limit, machineDetection, eventUrl, eventMethod, ringbackTone) { this.endpoint = [endpoint]; if (from) { this.from = from; } if (randomFromNumber) { this.randomFromNumber = randomFromNumber; } if (eventType) { this.eventType = eventType; } if (timeout) { this.timeout = timeout; } if (limit) { this.limit = limit; } if (machineDetection) { this.machineDetection = machineDetection; } if (eventUrl) { this.eventUrl = [eventUrl]; } if (eventMethod) { this.eventMethod = eventMethod; } if (ringbackTone) { this.ringbackTone = ringbackTone; } } /** * Serialize the Connect action to a Nexmo Call Control Object (NCCO) format. * * @return {ConnectAction} - The serialized Connect action. */ serializeToNCCO() { const data = { action: "connect" /* CONNECT */, endpoint: this.endpoint }; if (this.from) { data.from = this.from; } if (this.randomFromNumber) { data.randomFromNumber = this.randomFromNumber; } if (this.eventType) { data.eventType = this.eventType; } if (this.timeout) { data.timeout = this.timeout; } if (this.limit) { data.limit = this.limit; } if (this.machineDetection) { data.machineDetection = this.machineDetection; } if (this.eventUrl) { data.eventUrl = this.eventUrl; } if (this.eventMethod) { data.eventMethod = this.eventMethod; } if (this.ringbackTone) { data.ringbackTone = this.ringbackTone; } return data; } }; // lib/classes/NCCO/Conversation.ts var Conversation = class { /** * The action type, which is always 'conversation'. */ action = "conversation" /* CONVERSATION */; /** * The name of the conversation. * * @param {string} name - The name of the conversation. */ name; /** * An array of URLs for music to be played while participants are on hold. * * @param {string[]} musicOnHoldUrl - An array of music on hold URLs. */ musicOnHoldUrl; /** * Set to true to start the conversation when a participant enters. * * @param {boolean} startOnEnter - Set to true to start the conversation on participant enter. */ startOnEnter; /** * Set to true to end the conversation when the last participant exits. * * @param {boolean} endOnExit - Set to true to end the conversation on last participant exit. */ endOnExit; /** * Set to true to record the conversation. * * @param {boolean} record - Set to true to record the conversation. */ record; /** * An array of participant IDs (e.g., phone numbers) who can speak in the conversation. * * @param {string[]} canSpeak - An array of participant IDs who can speak in the conversation. */ canSpeak; /** * An array of participant IDs (e.g., phone numbers) who can hear in the conversation. * * @param {string[]} canHear - An array of participant IDs who can hear in the conversation. */ canHear; /** * Set to true to mute all participants in the conversation. * * @param {boolean} mute - Set to true to mute all participants in the conversation. */ mute; /** * Create a new Conversation instance. * * @param {string} name - The name of the conversation. * @param {string} musicOnHoldUrl - An array of music on hold URLs. * @param {boolean} startOnEnter - Set to true to start the conversation on participant enter. * @param {boolean} endOnExit - Set to true to end the conversation on last participant exit. * @param {boolean} record - Set to true to record the conversation. * @param {string[]} canSpeak - An array of participant IDs who can speak in the conversation. * @param {string[]} canHear - An array of participant IDs who can hear in the conversation. * @param {boolean} mute - Set to true to mute all participants in the conversation. */ constructor(name, musicOnHoldUrl, startOnEnter, endOnExit, record, canSpeak, canHear, mute) { this.name = name; if (musicOnHoldUrl) { this.musicOnHoldUrl = [musicOnHoldUrl]; } if (startOnEnter) { this.startOnEnter = startOnEnter; } if (endOnExit) { this.endOnExit = endOnExit; } if (record) { this.record = record; } if (canSpeak) { this.canSpeak = canSpeak; } if (canHear) { this.canHear = canHear; } if (mute) { this.mute = mute; } } /** * Serialize the Conversation action to a Nexmo Call Control Object (NCCO) format. * * @return {ConversationAction} - The serialized Conversation action. */ serializeToNCCO() { const data = { action: "conversation" /* CONVERSATION */, name: this.name }; if (this.musicOnHoldUrl) { data.musicOnHoldUrl = this.musicOnHoldUrl; } if (this.startOnEnter) { data.startOnEnter = this.startOnEnter; } if (this.endOnExit) { data.endOnExit = this.endOnExit; } if (this.record) { data.record = this.record; } if (this.canSpeak) { data.canSpeak = this.canSpeak; } if (this.canHear) { data.canHear = this.canHear; } if (this.mute) { data.mute = this.mute; } return data; } }; // lib/classes/NCCO/Input.ts var Input = class { /** * The action type, which is always 'input'. */ action = "input" /* INPUT */; /** * An array of input types ('dtmf' and/or 'speech'). */ type = []; /** * DTMF input settings. */ dtmf; /** * Speech input settings. */ speech; /** * An array of URLs to send events to asynchronously. */ eventUrl = []; /** * The HTTP method used to send events (e.g., 'POST' or 'GET'). */ eventMethod; /** * Input processing mode, currently only applicable to DTMF. Valid values are * synchronous (the default) and asynchronous. If set to asynchronous, all * DTMF settings must be left blank. In asynchronous mode, digits are sent one * at a time to the event webhook in real time. In the default synchronous * mode, this is controlled by the DTMF settings instead and the inputs are * sent in batch. */ mode; /** * Create a new Input instance. * * @param {DTMFSettings} dtmf - DTMF input settings. * @param {SpeechSettings} speech - Speech input settings. * @param {string} eventUrl - URL to send events to asynchronously. * @param {string} eventMethod - The HTTP method used to send events. */ constructor(dtmf, speech, eventUrl, eventMethod, mode) { if (dtmf) { this.type.push("dtmf"); this.dtmf = dtmf; } if (speech) { this.type.push("speech"); this.speech = speech; } if (eventUrl) { this.eventUrl = [eventUrl]; } if (eventMethod) { this.eventMethod = eventMethod; } if (mode) { this.mode = mode; } if (this.type.length === 0) { throw new TypeError( "Input action must have at least either DTMF or Speech settings" ); } } /** * Serialize the Input action to a Nexmo Call Control Object (NCCO) format. * * @return {InputAction} - The serialized Input action. */ serializeToNCCO() { const data = { action: "input" /* INPUT */, type: this.type }; if (this.dtmf) { data.dtmf = this.dtmf; } if (this.speech) { data.speech = this.speech; } if (this.eventUrl) { data.eventUrl = this.eventUrl; } if (this.eventMethod) { data.eventMethod = this.eventMethod; } return data; } }; // lib/classes/NCCO/NCCOBuilder.ts var NCCOBuilder = class { actions = []; /** * Add an action to the NCCO builder. * * @param {Action} action - The action to add to the NCCO. * @return {NCCOBuilder} - The NCCO builder instance (for method chaining). */ addAction(action) { this.actions.push( "serializeToNCCO" in action ? action.serializeToNCCO() : action ); return this; } /** * Build the NCCO by serializing the added actions. * * @return {Array<Action | Serializable>} - The built NCCO, which is an array of actions. */ build() { return this.actions; } }; // lib/classes/NCCO/Notify.ts var Notify = class { action = "notify" /* NOTIFY */; payload; eventUrl; eventMethod; /** * Creates a new Notify action. * * @param {Object} payload - The payload data to send with the notification. * @param {string} eventUrl - The URL where the notification events will be sent. * @param {string} [eventMethod] - The HTTP method for sending notification events (e.g., "POST"). */ constructor(payload, eventUrl, eventMethod) { this.payload = payload; this.eventUrl = [eventUrl]; if (eventMethod) { this.eventMethod = eventMethod; } } /** * Serialize the Notify action to an NCCO-compatible format. * * @return {NotifyAction} - The serialized Notify action. */ serializeToNCCO() { const data = { action: "notify" /* NOTIFY */, payload: this.payload, eventUrl: this.eventUrl }; if (this.eventMethod) { data.eventMethod = this.eventMethod; } return data; } }; // lib/classes/NCCO/Record.ts var Record = class { /** * The action type for the Record action. */ action = "record" /* RECORD */; /** * The recording format (e.g., "mp3", "wav"). */ format; /** * The split type for recording (always "conversation"). */ wrappedSplit; /** * The number of audio channels (1 to 32). */ wrappedChannels; /** * The duration of silence (in seconds) to end the recording (3 to 10 seconds). */ wrappedEndOnSilence; /** * The DTMF key that ends the recording (e.g., "0", "*", "#"). */ wrappedEndOnKey; /** * The maximum recording duration in seconds (3 to 7200 seconds). */ wrappedTimeOut; /** * Whether to play a beep before recording starts. */ beepStart; /** * The URL where recording events will be sent. */ eventUrl; /** * The HTTP method for sending recording events (e.g., "POST"). */ eventMethod; /** * Creates a new Record action. * * @param {RecordingFormat} format - The recording format (e.g., "mp3", "wav"). * @param {string} split - The split type for recording (should be "conversation"). * @param {number} channels - The number of audio channels (1 to 32). * @param {number} endOnSilence - The duration of silence (in seconds) to end the recording (3 to 10 seconds). * @param {string} endOnKey - The DTMF key that ends the recording (e.g., "0", "*", "#"). * @param {number} timeout - The maximum recording duration in seconds (3 to 7200 seconds). * @param {boolean} beepStart - Whether to play a beep before recording starts. * @param {string} eventUrl - The URL where recording events will be sent. * @param {string} eventMethod - The HTTP method for sending recording events (e.g., "POST"). */ constructor(format, split, channels, endOnSilence, endOnKey, timeout, beepStart, eventUrl, eventMethod) { if (format) { this.format = format; } if (split) { this.split = split; } if (channels) { this.channels = channels; } if (endOnSilence) { this.endOnSilence = endOnSilence; } if (endOnKey) { this.endOnKey = endOnKey; } if (timeout) { this.timeout = timeout; } if (beepStart) { this.beepStart = beepStart; } if (eventUrl) { this.eventUrl = [eventUrl]; } if (eventMethod) { this.eventMethod = eventMethod; } } /** * Getter for the number of audio channels. * * @return {number | undefined} - The current number of audio channels. */ get channels() { return this.wrappedChannels; } /** * Setter for the number of audio channels. * * @param {number} channels - The number of audio channels (1 to 32). * @throws {Error} - If the channel value is invalid or split is not set to "conversation." */ set channels(channels) { if (channels < 1 || channels > 32) { throw new Error("Channels must be between 1 and 32, inclusive"); } if (this.wrappedSplit !== "conversation") { throw new Error( "Channels must have split set to 'conversation' before changing channel numbers" ); } this.wrappedChannels = channels; } /** * Getter for the character that signals the end of recording. * * @return {string | undefined} - The character that signals the end of recording. */ get endOnKey() { return this.wrappedEndOnKey; } /** * Setter for the DTMF key that ends the recording. * * @param {string} character - The DTMF key that ends the recording (e.g., "0", "*", "#"). * @throws {Error} - If the character is not a valid DTMF key. */ set endOnKey(character) { const re = /^[0-9*#]$/; if (!re.test(character)) { throw new Error("Valid characters are 0-9, *, and # only"); } this.wrappedEndOnKey = character; } /** * Getter for the duration of silence (in seconds) that signals the end of recording. * * @return {number | undefined} - The duration of silence (in seconds) that signals the end of recording. */ get endOnSilence() { return this.wrappedEndOnSilence; } /** * Setter for the duration of silence to end the recording. * * @param {number} numSeconds - The duration of silence in seconds (3 to 10 seconds). * @throws {Error} - If the duration value is out of the valid range. */ set endOnSilence(numSeconds) { if (numSeconds < 3 || numSeconds > 10) { throw new Error( "End on Silence must be between 3 and 10 seconds, inclusive" ); } this.wrappedEndOnSilence = numSeconds; } /** * Getter for the recording split type. * * @return {string} - The recording split type, which is always 'conversation'. */ get split() { return "conversation"; } /** * Setter for the recording split type. * * @param {string} splitType - The recording split type. Must be set to 'conversation'. * @throws {Error} - Throws an error if the splitType is not 'conversation'. */ set split(splitType) { if (splitType !== "conversation") { throw new Error("Recording can only be split to 'conversation'"); } this.wrappedSplit = splitType; } /** * Getter for the recording timeout duration in seconds. * * @return {number | undefined } - The recording timeout duration in seconds. */ get timeout() { return this.wrappedTimeOut; } /** * Setter for the recording timeout. * * @param {number} seconds - The maximum recording duration in seconds (3 to 7200 seconds). * @throws {Error} - If the timeout value is out of the valid range. */ set timeout(seconds) { if (seconds < 3 || seconds > 7200) { throw new Error( "Recording timeout must be between 3 and 7200 seconds, inclusive" ); } this.wrappedTimeOut = seconds; } /** * Serializes the Record action to NCCO format. * * @return {RecordAction} - The serialized Record action. */ serializeToNCCO() { const data = { action: "record" /* RECORD */ }; if (this.format) { data.format = this.format; } if (this.wrappedSplit) { data.split = this.split; } if (this.wrappedChannels) { data.channels = this.wrappedChannels; } if (this.wrappedEndOnKey) { data.endOnKey = this.endOnKey; } if (this.wrappedEndOnSilence) { data.endOnSilence = this.endOnSilence; } if (this.wrappedTimeOut) { data.timeOut = this.wrappedTimeOut; } if (this.beepStart) { data.beepStart = this.beepStart; } if (this.eventUrl) { data.eventUrl = this.eventUrl; } if (this.eventMethod) { data.eventMethod = this.eventMethod; } return data; } }; // lib/classes/NCCO/Talk.ts var Talk = class { /** * The action type for this NCCO action. */ action = "talk" /* TALK */; /** * The text to be spoken during the call. */ text; /** * Indicates whether the talk action allows barge-in (optional). */ bargeIn; /** * The number of times to loop the speech (optional). */ loop; /** * The audio level at which to play the speech (optional). */ level; /** * The language for the text-to-speech synthesis (optional). */ language; /** * The speech style (optional). */ style; /** * Indicates whether to use premium text-to-speech (optional). */ premium; /** * Creates a new Talk action. * * @param {string} text - The text to be spoken during the call. * @param {boolean} [bargeIn] - Indicates whether the talk action allows barge-in (optional). * @param {number} [loop] - The number of times to loop the speech (optional). * @param {string} [level] - The audio level at which to play the speech (optional). * @param {TTSLanguages | string} [language] - The language for the text-to-speech synthesis (optional). * @param {string} [style] - The speech style (optional). * @param {boolean} [premium] - Indicates whether to use premium text-to-speech (optional). */ constructor(text, bargeIn, loop, level, language, style, premium) { this.text = text; if (bargeIn) { this.bargeIn = bargeIn; } if (loop) { this.loop = loop; } if (level) { this.level = level; } if (language) { this.language = language; } if (style) { this.style = style; } if (premium) { this.premium = premium; } } /** * Serializes the Talk action to a Nexmo Call Control Object (NCCO). * * @return {TalkAction} - The serialized Talk action. */ serializeToNCCO() { const data = { action: "talk" /* TALK */, text: this.text }; if (this.loop) { data.loop = this.loop; } if (this.bargeIn) { data.bargeIn = this.bargeIn; } if (this.level) { data.level = this.level; } if (this.language) { data.language = this.language; } if (this.style) { data.style = this.style; } if (this.premium) { data.premium = this.premium; } return data; } }; // lib/classes/NCCO/Stream.ts var Stream = class { /** * The action type for this NCCO action. */ action = "stream" /* STREAM */; /** * An array of stream URLs to play audio from. */ streamUrl; /** * The audio level at which to play the stream (optional). */ level; /** * Indicates whether the stream should allow barge-in (optional). */ bargeIn; /** * The number of times to loop the audio (optional). */ loop; /** * Creates a new Stream action. * * @param {string} streamUrl - The URL of the audio stream. * @param {number} [level] - The audio level at which to play the stream (optional). * @param {boolean} [bargeIn] - Indicates whether the stream should allow barge-in (optional). * @param {number} [loop] - The number of times to loop the audio (optional). */ constructor(streamUrl, level, bargeIn, loop) { this.streamUrl = [streamUrl]; if (level) { this.level = level; } if (bargeIn) { this.bargeIn = bargeIn; } if (loop) { this.loop = loop; } } /** * Serializes the Stream action to a Nexmo Call Control Object (NCCO). * * @return {StreamAction} - The serialized Stream action. */ serializeToNCCO() { const data = { action: "stream" /* STREAM */, streamUrl: this.streamUrl }; if (this.level) { data.level = this.level; } if (this.bargeIn) { data.bargeIn = this.bargeIn; } if (this.loop) { data.loop = this.loop; } return data; } }; // Annotate the CommonJS export names for ESM import in node: 0 && (module.exports = { Connect, Conversation, Input, NCCOBuilder, Notify, OutboundCall, OutboundCallWithAnswerURL, OutboundCallWithNCCO, Record, Stream, Talk });