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 answer 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 include 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.sgather({ 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)

Unmute 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");
 });
}