@fonoster/voice

voice

The Voice module is a library for creating voice applications using the Fonoster API. It provides a simple way to create voice applications that can interact with the calling party using DTMF or speech recognition combined with simple verbs.

• Installation
• Example
• Voice Response

Installation

$ npm install --save @fonoster/voice

Example

A Voice Application is a server that controls a call's flow. A Voice Application can use any combination of the following verbs:

• Answer - Accepts an incoming call
• Dial - Passes the call to an Agent or a Number at the PSTN
• Hangup - Closes the call
• Play - Takes a URL or file and streams the sound back to the calling party
• Say - Takes a text, synthesizes the text into audio, and streams back the result
• Gather - Waits for DTMF or speech events and returns back the result
• SGather - Returns a stream for future DTMF and speech results
• Stream - Starts a stream to read and write audio into the call
• Record - It records the voice of the calling party and saves the audio on the Storage sub-system
• Mute - It tells the channel to stop sending media, effectively muting the channel
• Unmute - It tells the channel to allow media flow

Voice Application Example:

const VoiceServer = require("@fonoster/voice").default;
const { 
  GatherSource, 
  VoiceRequest, 
  VoiceResponse 
} = require("@fonoster/voice");

new VoiceServer().listen(async (req: VoiceRequest, voice: VoiceResponse) => {
  const { ingressNumber, sessionRef, appRef } = req;

  await voice.answer();

  await voice.say("Hi there! What's your name?");

  const { speech: name } = await res.gather({
    source: GatherSource.SPEECH
  });

  await voice.say("Nice to meet you " + name + "!");

  await voice.say("Please enter your 4 digit pin.");

  const { digits } = await voice.gather({
    maxDigits: 4,
    finishOnKey: "#"
  });

  await voice.say("Your pin is " + digits);

  await voice.hangup();
});

// Your app will live at tcp://127.0.0.1:50061 
// and you can easily publish it to the Internet with:
// ngrok tcp 50061

VoiceResponse ⇐ Verb

Use the VoiceResponse object, to construct advance Interactive Voice Response (IVR) applications.

Kind: global class
Extends: Verb
See: module:core:APIClient

• VoiceResponse ⇐ Verb
  • new VoiceResponse(request, voice)
  • .answer()
  • .hangup()
  • .play(url, options)
  • .playDtmf(digits)
  • .playbackControl(playbackRef, action)
  • .gather(options)
  • .say(text, options)
  • .record(options) ⇒ RecordResponse
  • .dial(destination, options) ⇒ Promise.<DialStatusStream>
  • .stream(options) ⇒ Promise.<Stream>
  • .sgather(options) ⇒ Promise.<StreamGatherStream>
  • .mute(options)
  • .unmute(options)
  • .on(event, listener)

new VoiceResponse(request, voice)

Constructs a new VoiceResponse object.

Param	Type	Description
request	VoiceRequest	Options to indicate the objects endpoint
voice	VoiceSessionStream	The voice session stream

Example

import { VoiceServer } from "@fonoster/voice";

async function handler (request, response) {
  await response.answer();
  await response.play("https://soundsserver:9000/sounds/hello-world.wav");
}

new VoiceServer().listen(handler, { port: 3000 })

voiceResponse.answer()

Answer the call. Before running any other verb you must run the anwer command.

Kind: instance method of VoiceResponse
Example

async function handler (request, response) {
  await response.answer();
}

voiceResponse.hangup()

Hangup the call.

Kind: instance method of VoiceResponse
Example

async function handler (request, response) {
 await response.hangup();
}

voiceResponse.play(url, options)

Play an audio in the call.

Kind: instance method of VoiceResponse
See: Playback

Param	Type	Description
url	string	The URL of the media to play
options	PlayOptions	Options to control the playback
options.playbackRef	string	Playback identifier to use in Playback operations

Example

async function handler (request, response) {
  await response.answer();
  await response.play("https://soundsserver:9000/sounds/hello-world.wav");
}

voiceResponse.playDtmf(digits)

Play a series of DTMF digits in a call.

Kind: instance method of VoiceResponse

Param	Type	Description
digits	string	The DTMF digits to play (0-9, #, or *)

Example

async function handler (request, response) {
 await response.answer();
 await response.playDtmf("1234");
}

voiceResponse.playbackControl(playbackRef, action)

Control the playback of the currently playing media.

Kind: instance method of VoiceResponse
See: play

Param	Type	Description
playbackRef	string	The playback identifier
action	PlaybackControlAction	The action to perform (STOP, RESTART, PAUSE, UNPAUSE, FORWARD)

Example

async function handler (request, response) {
   await response.answer();
   await response.play("https://s3.fonoster.io/uuid/hello-world.wav", { playbackRef: "playback-01" });

   // Pause the media
   await response.playbackControl("playback-01", PlaybackControlAction.PAUSE);
}

voiceResponse.gather(options)

Waits for data entry from the user's keypad or from a speech provider.

Kind: instance method of VoiceResponse
Note: When including SPEECH the default timeout is 10000 (10s).

Param	Type	Description
options	GatherOptions	Options to select the maximum number of digits, final character, and timeout
options.maxDigits	number	Maximum number of digits to collect. Defaults to 1
options.timeout	number	Milliseconds to wait before timeout. Defaults to 4000. Use zero for no timeout.
options.finishOnKey	string	Optional last character to wait for. Defaults to '#'. It will not be included in the returned digits
options.source	GatherSource	Where to listen as input source. This option accepts DTMF and SPEECH. A speech provider must be configure when including the SPEECH source. You might inclue both with SPEECH_AND_DTMF. Defaults to SPEECH_AND_DTMF

Example

async function handler (request, response) {
  await response.answer();
  const speech = await response.gather({ source: GatherSource.SPEECH, numDigits: 3 });
  console.log("speech: " + speech);
  await response.hangup();
}

voiceResponse.say(text, options)

Send a text for a TTS engine to convert to speech.

Kind: instance method of VoiceResponse
See: Say

Param	Type	Description
text	string	The text to convert to speech
options	SayOptions	Options to control the TTS engine
options.playbackRef	string	Playback identifier to use in Playback operations
options.ttsOptions	TTSOptions	Options to control the TTS engine (specific to the TTS engine)

Example

async function handler (request, response) {
  await response.answer();
  const playbackRef = await response.say("Hello World");

  // Like the play verb, you can control the playback
  await response.playbackControl(playbackRef, PlaybackControlAction.STOP);
}

voiceResponse.record(options) ⇒ RecordResponse

Record the audio of the call.

Kind: instance method of VoiceResponse
Returns: RecordResponse - The record response

Param	Type	Description
options	RecordOptions	Options to control the record operation
options.maxDuration	number	The maximum duration of the recording in seconds. Default is 60
options.maxSilence	number	The maximum duration of silence in seconds. Default is 5
options.beep	boolean	Play a beep before recording. Default is true
options.finishOnKey	string	Stop recording when a DTMF digit is received. Default is '#'

Example

async function handler (request, response) {
  await response.answer();
  const record = await response.record();
  console.log("Recording: %s", record.name);
}

voiceResponse.dial(destination, options) ⇒ Promise.<DialStatusStream>

Dials a destination and returns a stream of status.

Kind: instance method of VoiceResponse
Returns: Promise.<DialStatusStream> - The dial status stream

Param	Type	Description
destination	string	The destination to dial
options	DialOptions	Options to control the dial operation
options.timeout	number	The timeout in seconds. Default is 60
options.recordDirection	RecordDirection	The direction to record the call (IN, OUT, BOTH). Default is BOTH

voiceResponse.stream(options) ⇒ Promise.<Stream>

Starts a bidirectional audio stream between the call and the application.

Kind: instance method of VoiceResponse
Returns: Promise.<Stream> - The stream object

Param	Type	Description
options	StreamOptions	Options to control the stream operation
options.direction	StreamDirection	The direction to stream the audio (IN, OUT, BOTH). Default is BOTH
options.format	StreamAudioFormat	The audio format to stream (WAV). Default is WAV

Example

async function handler (request, response) {
  await response.answer();

  const stream = await response.stream({
    direction: StreamDirection.BOTH
  });

  stream.onPayload((payload) => {
    // Use the payload
  });

  // Or write to the stream
  // stream.write({ type: StreamMessageType.AUDIO_OUT, payload: "\x00\x01\x02" });
}

voiceResponse.sgather(options) ⇒ Promise.<StreamGatherStream>

Starts a server-side stream gather operation which sends transcription data to the voice server.

Kind: instance method of VoiceResponse
Returns: Promise.<StreamGatherStream> - The stream gather object
See: Gather

Param	Type	Description
options	StreamGatherOptions	Options to control the stream gather operation
options.source	StreamGatherSource	The source to gather data from (DTMF, SPEECH, SPEECH_AND_DTMF). Default is SPEECH

Example

async function handler (request, response) {
 await response.answer();
 const sGather = await response.streamGather({ source: StreamGatherSource.SPEECH });
 sGather.onPayload((payload) => {
   console.log("Payload: %s", payload);
 });
}

voiceResponse.mute(options)

Mutes a call.

Kind: instance method of VoiceResponse
See: unmute

Param	Type	Description
options	MuteOptions	Options to control the mute operation
options.direction	MuteDirection	The direction to mute the channel (IN, OUT, BOTH). Default is BOTH

Example

async function handler (request, response) {
  await response.answer();
  await response.mute();       // Will mute both directions
}

voiceResponse.unmute(options)

Unmutes a call.

Kind: instance method of VoiceResponse
See: mute

Param	Type	Description
options	MuteOptions	Options to control the unmute operation
options.direction	MuteDirection	The direction to unmute the call (IN, OUT, BOTH). Default is BOTH

Example

async function handler (request, response) {
  await response.answer();
  await response.unmute();     // Will unmute both directions
}

voiceResponse.on(event, listener)

Register a listener for the given event.

Kind: instance method of VoiceResponse

Param	Type	Description
event	StreamEvent	The event to listen for
listener	function	The callback function

Example

async function handler (request, response) {
 ...

 response.on(StreamEvent.END, () => {
  console.log("Call ended");
 });
}