VoiceResponse

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)
  • .use(plugin)
  • .play(media, options)
  • .say(text, options)
  • .gather(options)
  • .sgather(options) ⇒ SGatherStream
  • .dtmf(options)
  • .dial(destination, options) ⇒ StatusStream
  • .playback(playbackId)
  • .on(handler)
  • .mute(options)
  • .unmute(options)
  • .answer()
  • .hangup()
  • .record(options) ⇒ Promise.<RecordResult>

new VoiceResponse(request)

Constructs a new VoiceResponse object.

Param	Type	Description
request	VoiceRequest	Options to indicate the objects endpoint

Example

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

async function handler (request, response) {
  await response.answer();
  await response.play("sound:hello-world");
}

const voiceServer = new VoiceServer({base: '/voiceapp'})
voiceServer.listen(handler, { port: 3000 })

voiceResponse.use(plugin)

Adds a tts or asr plugin. Only one type of plugin can be attached.

Kind: instance method of VoiceResponse
See

• GoogleTTS
• GoogleASR

Param
plugin

voiceResponse.play(media, options)

Play an audio in the channel.

Kind: instance method of VoiceResponse
See: Playback

Param	Type	Description
media	string	Sound name or uri with audio file
options	PlayOptions	Optional parameters to alter the command's normal behavior
options.offset	string	Milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified
options.skip	string	Milliseconds to skip for forward/reverse operations
options.playbackId	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.say(text, options)

Converts a text into a sound and sends sound to media server. To use this verb, you must first setup a TTS plugin such as GoogleTTS, or AWS PollyTTS

Kind: instance method of VoiceResponse
See

• Play
• Voice.use

Param	Type	Description
text	string	Converts a text into a sound and sends sound to media server
options	SayOptions	Optional parameters to alter the command's normal behavior
options.offset	string	Milliseconds to skip before playing
options.skip	string	Milliseconds to skip for forward/reverse operations
options.playbackId	string	Playback identifier to use in Playback operations

Example

async function handler (request, response) {
  await response.answer();
  response.use(new GoogleTTS())
  await response.say("Hello workd");   // Plays the sound using GoogleTTS's default values
}

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).
See: SpeechProvider

Param	Type	Description
options	GatherOptions	Options to select the maximum number of digits, final character, and timeout
options.numDigits	number	Milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified
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	string	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 dtmf,speech. Defaults to dtmf

Example

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

voiceResponse.sgather(options) ⇒ SGatherStream

Waits for data entry from the user's keypad or from a stream speech provider. This command is different from gather in that it returns a stream of results instead of a single result. You can think of it as active listening.

Kind: instance method of VoiceResponse
Returns: SGatherStream - The SGatherStream fires events via the on method for transcription, dtmf, and error. And the stream can be close with the close function.
See: StreamSpeechProvider

Param	Type	Description
options	SGatherOptions	Options object for the SGather verb
options.source	string	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 dtmf,speech. Defaults to speech,dtmf

Example

async function handler (request, response) {
  await response.answer();
  const stream = await response.sgather({source: "dtmf,speech"});

  stream.on("transcript", (text, isFinal) => {
     console.log("transcript: %s", text);
  })

  stream.on("dtmf", digit => {
     console.log("digit: " + digit);
     if (digit === "#") stream.close();
  })
}

voiceResponse.dtmf(options)

Sends dtmf tones to the current session.

Kind: instance method of VoiceResponse

Param	Type	Description
options	DtmfOptions	Options object for the Dtmf verb
options.dtmf	string	A string of the dtmf tones

Example

async function handler (request, response) {
   await response.answer();
   await response.play("sound:hello-world");
   await response.dtmf({dtmf: "1234"});
}

voiceResponse.dial(destination, options) ⇒ StatusStream

Forwards the call to an Agent or the PSTN.

Kind: instance method of VoiceResponse
Returns: StatusStream - The StatusStream fires events via the on method for progress, answer, noanswer, and busy. And the stream can be close with the close function.

Param	Type	Description
destination	string	Number or Agent to forward the call to
options	DialOptions	Options object for the Dial verb
options.timeout	timeout	Dial timeout

Example

async function handler (request, response) {
   await response.answer();
   await response.say("dialing number");
   const stream = await response.dial("17853178070");
   stream.on("progress", console.log)
   stream.on("answer", console.log)
   stream.on("busy", console.log)
}

voiceResponse.playback(playbackId)

Returns a PlaybackControl control object.

Kind: instance method of VoiceResponse
See: Play

Param	Type	Description
playbackId	string	Playback identifier to use in Playback operations

Example

async function handler (request, response) {
  await response.answer();
  response.onDtmfReceived(async(digit) => {
     const control = response.playback("1234")
     digit === "3"
       ? await control.restart()
       : await control.forward()
  })

  await response.play("https://soundsserver:9000/sounds/hello-world.wav", {
     playbackId: "1234"
  });
}

voiceResponse.on(handler)

Listens event publication.

Kind: instance method of VoiceResponse

Param	Type	Description
handler	function	Event handler

Example

async function handler (request, response) {
  await response.answer();
  response.on("DtmfReceived", async(digit) => {
     const control = response.playback("1234")
     digit === "3"
       ? await control.restart()
       : await control.forward()
  })

  await response.play("https://soundsserver:9000/sounds/hello-world.wav", {
     playbackId: "1234"
  });
}

voiceResponse.mute(options)

Mutes a channel.

Kind: instance method of VoiceResponse
See: unmute

Param	Type	Description
options	MuteOptions	Indicate which direction of he communication to mute
options.direction	string	Possible values are 'in', 'out', and 'both'

Example

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

voiceResponse.unmute(options)

Unmutes a channel.

Kind: instance method of VoiceResponse
See: mute

Param	Type	Description
options	MuteOptions	Indicate which direction of he communication to unmute
options.direction	string	Possible values are 'in', 'out', and 'both'

Example

async function handler (request, response) {
  ...
  await response.unmute({direction: "out"});       // Will unmute only the "out" direction
}

voiceResponse.answer()

Answer the communication channel. 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()

Terminates the communication channel.

Kind: instance method of VoiceResponse
Example

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

voiceResponse.record(options) ⇒ Promise.<RecordResult>

Records the current channel and uploads the file to the storage subsystem.

Kind: instance method of VoiceResponse
Returns: Promise.<RecordResult> - Returns useful information such as the duration of the recording, etc.

Param	Type	Description
options	RecordOptions	optional parameters to alter the command's normal behavior
options.maxDuration	number	Maximum duration of the recording, in seconds. Use 0 for no limit
options.maxSilence	number	Maximum duration of silence, in seconds. Use 0 for no limit
options.beep	boolean	Play beep when recording begins
options.finishOnKey	string	DTMF input to terminate recording

Example

async function handler (request, response) {
  await response.answer();;
  const result = await response.record({finishOnKey: "#"});
  console.log("recording result: " + JSON.stringify(result))     // recording result: { duration: 30 ...}
}