channel

A channel object represents a voice connection to a remote party, such as a person calling in, or an outbound call to them. The channel object has properties which are methods to call channel commands.

Each Summit Application has access to its associated channel via this object. You will notice how it can be used by reviewing the example code which is automatically generated when you create a new app:

-- A call to the phone number that routed to the application, starts it up and answers the call.
channel.answer()

-- TTS greeting to the caller
channel.say("Hello there! This is an example application. Enter any number followed by the pound sign.")

-- Collecting the digits pressed by the caller
local digits = channel.gather()

-- TTS playback of the pressed digits
channel.say(digits)

-- Call ends and the application goes away
channel.hangup()

Notice how when the application starts, the very first thing that happens is the channel.answer() command and it ends with the channel.hangup() command. Take a look at the various functions you can call on a channel below.

Classes

Name Summary
ApplicationResult

A class representing the result of a call to channel.app

ChannelReference

This object is returned from actions like channel.dial.

RecognizeResult

The result of the recognize command.

Functions

Name Summary
answer

Send answer signal to PBX.

app

Call another Summit Application directly.

barge

Eavesdrop on a channel.

conference

Create or join a conference.

dial

Dial another extension or outside number.

dtmf

Emits a DTMF signal.

gather

Prompt to collect DTMF.

get_external_trunk_group

Returns the trunk group name for the far end of this channel

get_hangup_cause

Get back the value of the current expected hangup_cause for the channel.

hangup

Send a hangup signal to the PBX.

is_pstn

Returns whether or not the user on the channel is on the Public Switched Telephone Network

play

Play a file, url, or stream a playlist.

recognize

Recognize speech input.

record

Collect channel audio into a recording object.

ring

Send ringing audio to channel, useful for simulating ring sounds before channel.answer() has been called.

say

Call out to TTS engine.

set_hangup_cause

Sets the default hangup cause to be used when the channel hangs up.

sleep

PBX level sleep function. This is useful because it allows you to create DTMF-interruptable sleep statements.

Fields

Name Type Summary
data.ani

string

The Source Phone Number (Indiscriminate of call direction!!)

data.channel_id

string

The ID of the channel for the app (UUID)

data.custom_sip_headers

table

Custom SIP headers (those that start with X-*) for this channel.

data.destination

string

The internally routed number, changes every time a channel is transferred internally. Not terribly useful for most apps

data.direction

string

The direction of the call (“inbound” means calling in to the system, “outbound” means calling out from the system)

data.diversion

string or nil

If this call was diverted, this will be the raw SIP Diversion header. A diverted call would be a call that was forwarded from a carrier using a call forwarding feature or some other diversion mechanism. The values in diversion_number and diversion_params are parsed versions of this header and are most likely more useful.

data.diversion_number

string or nil

If the current call was diverted, this will be the phone number it was diverted from.

data.diversion_params

table or nil

If the current call was diverted (eg forwarded via call forwarding) it will contain the parameters of that diversion. The most common and interesting paramter will be ‘reason’ which will indicate why the call was diverted. Typical values are, ‘busy’ when a line is busy, ‘unconditional’ for call forwarding, and ‘unavailable’.

data.dnis

string

The Dialed number (indiscriminate of call direction!!)

data.domain

string

The SIP domain associated with the tenant (UUID)

data.localnumber

string

The system’s phone number (==dnis for inbound, ==ani for outbound)

data.remotenumber

string

The supposed human’s phone number (==ani for inbound, ==dnis for outbound)

Classes : channel

ApplicationResult

A class representing the result of a call to channel.app

This object is returned when you call channel.app and that application calls application.exit. Useful information about that application call is contained in this object. Most importantly, if that application called application.exit with an argument, that value is available here as the exit_value attribute.

The data in this object is also available through the REST API at /channel_application.

Fields
Name Type Summary
application_data

string or nil

The value of application_data used by the application

application_destination

string or nil

The value of application_destination used by the application

application_name

string

The name of the called application

call_id

uuid

A unique ID for the call

channel_application_id

uuid

A unique ID for the application execution

channel_id

uuid

A unique ID for the channel

cleanup_success

bool or nil

Whether cleanup ran successfully on the application

cleanup_timestamp

time.DateTime or nil

A timestamp for when cleanup happened

created_timestamp

time.DateTime

A timestamp for when the ChannelApplication object was created

domain_id

uuid

Your domain ID

duration

number or nil

The duration of the application execution, in seconds

exit_success

bool

Whether the application exited successfully

exit_timestamp

time.DateTime or nil

A timestamp for when the application finished

exit_value

string or nil

The return value of the application (set by application.exit)

modified_timestamp

time.DateTime

A timestamp for when the ChannelApplication was last modified

application_id

uuid

The application ID

ChannelReference

This object is returned from actions like channel.dial.

This object represents the result of the channel.dial function. It cannot be instantiated directly, and currently is only returned by that function. It contains useful information about what happened to the dial command (and the call that followed, if there was one).

Fields
Name Type Summary
channel_id

uuid

The ID of the channel

total_duration

float

The total length (in seconds) of the call

connected_duration

float

The length of time (in seconds) for which the call was connected

hangupCause

string

The cause for the hangup; one of the following:

  • ‘normal’ : The callee answered normally
  • ‘canceled’ : The call was canceled before it could be answered
  • ‘busy’ : The line was busy
  • ‘rejected’ : The call was rejected by the destination
  • ‘noanswer’ : The dial reached the ring timeout with no answer
  • ‘unregistered’ : The intended destination was a valid endpoint, but was not registered
  • ‘unallocated’ : The intended destination was not an allocated number (for example, and endpoint that does not exist)
  • ‘congestion’ : Network congestion prevented the call from completing
  • ‘failure’ : Something went wrong and the call did not complete successfully

RecognizeResult

The result of the recognize command.

This object holds a list of speech interpretations in descending order of confidence.

Fields
Name Type Summary
attempts

number

The number of times the user was prompted for input.

cause

string

A description of the recognition result. Possible values of the description are listed below. This value may also be a short string describing a problem with grammar loading or contacting the speech recognition server.

  • success when there is an interpretation that passes min-confidence and validation.
  • dtmf-no-match if the DTMF input does not match the supplied regex,
  • confidence-too-low if there was recognized speech but the interpretation’s confidence did not meet the minimum threshold
confidence

number

A percentage between 0 and 100 that the interpretation matches the user’s input. Confidence may be lower if the grammar contains phonetically similar words (e.g. “help” and “belt”). If DTMF input was matched, the confidence level is always 100.

input

string

The phonetic utterance or raw DTMF input that the user had said or entered. Spelling may be normalized in certain grammars (e.g. “in the uh afternoon” may be transliterated as “in_the_afternoon” as non-terminals in the grammar are matched).

input_mode

string

Will be ‘speech’ if the input was vocal and ‘dtmf’ if the voice recognition was interrupted by a successful DTMF match.

interpretation

string

The meaning of the user input, according to either the grammar (on recognized voice input) or the supplied mapping (on DTMF input).

num_results

number

The number of interpretations retrievable wtih the nth method.

Functions
Name Returns Summary
first()

table

An alias for RecognizeResult:nth(1).

nth(n)

table

Get data about the n'th interpretation of the user’s input.

recognized()

boolean

Determines if recognition was successful.

RecognizeResult:first()

An alias for RecognizeResult:nth(1).

Returns
Type Summary

table

A table containing input, interpretation, confidence, and input_mode fields. with meanings identical to that of the top-level object.

Usage
local speech = require "summit.speech"
local grammar = require "summit.speechrec.grammar"

local result, err = channel.recognize(grammar.builtin('phonenumber'), {
    play=speech.speech('Please say your phone number.')
})

if result ~= nil and result:recognized() then
    val f = result:first()

    channel.say('You said ' .. f.input .. ' meaning ' .. f.interpretation)
    channel.say('I know this with ' .. f.confidence .. ' percent confidence')
end

RecognizeResult:nth(n)

Get data about the n'th interpretation of the user’s input. If the user input did not pass validation, then the field successful will be false and the method recognized will return false, but there may still be data returned from this method. This can be useful in order to log or otherwise utilize user input data which did not meet some confidence threshold or pass validation.

Parameters
Name Type Default Summary

n

number

The index of the interpretation result to retrieve.

Returns
Type Summary

table

A table containing input, interpretation, confidence, and input_mode fields. with meanings identical to that of the top-level object.

Usage
local speech = require "summit.speech"
local grammar = require "summit.speechrec.grammar"

local result, err = channel.recognize(grammar.builtin('phonenumber'), {
    play=speech.speech('Please say your phone number.')
})

if result ~= nil and result:recognized() then
    val f = result:first()

    channel.say('You said ' .. f.input .. ' meaning ' .. f.interpretation)
    channel.say('I know this with ' .. f.confidence .. ' percent confidence')
end

for i=2,result.num_results do
    channel.say('You may also have meant ' .. result:nth(i).interpretation)
end

RecognizeResult:recognized()

Determines if recognition was successful.

Returns
Type Summary

boolean

Whether or not the recognition was successful.

Usage
local speech = require "summit.speech"
local grammar = require "summit.speechrec.grammar"

local result, err = channel.recognize(grammar.builtin('phonenumber'), {
    play=speech.speech('Please say your phone number.')
})

if result ~= nil and result:recognized() then
    channel.say('Thank you.')
else
    channel.say('Sorry, I did not catch that.')
end

Functions : channel

answer()

Send answer signal to PBX. This is required to happen as one of the first steps of any inbound voice application. Failure to do so will cause unexpected disconnects.

Returns
Type Summary

nil

app(application_name[, options])

Call another Summit Application directly. This will pause execution of the current Application and will run another Summit App, which will inherit the current channel. When the called Application completes, this Application will resume.

Parameters
Name Type Default Summary

application_name

string

The name of the application to be called

options

table

Optional

Parameter: options
Name Type Default Summary

application_data

table or string or nil

nil

Some string value which will be available in the called App from the summit.application library using get_data. If you use a table, it must be JSON-encodable. If you use a string, we will attempt to JSON decode it when the called application accesses it, but if that fails the original string will be returned.

application_destination

string or nil

nil

Some string value which will be available in the called App from the summit.application library using get_destination.

Returns
Type Summary

ApplicationResult

A table of information about the application execution

Usage
local result = channel.app('MyApp', {application_data={foo='bar'}})
print(result.exit_value) -- prints out whatever "MyApp" passed to `channel.exit`

barge(identity[, options])

Eavesdrop on a channel.

Parameters
Name Type Default Summary

identity

string

Identity of channel to barge.

options

table

Optional

Parameter: options
Name Type Default Summary

allowModeChange

boolean

false

Allow changing of barge modes.

mode

string

'listen'

Mode of barge. Available choices:

  • “listen” – Eavesdrop
  • “whisper” – Speak to caller
  • “whisper-far” – Speak to callee
  • “threeway” – Speak to both caller and callee
Returns
Type Summary

boolean

Always returns true

conference(conference_name[, options])

Create or join a conference. This command allows you to join an existing conference or create a new one. Conference names are unique; to join an existing conference, simply use the same name. By default, if no conference by the given name exists, a new one will be created and the channel will join.

Parameters
Name Type Default Summary

conference_name

string

Conference name

options

table

Optional

Parameter: options
Name Type Default Summary

allowCreate

boolean

true

Control whether this channel can create a new conference. If false, this channel can only join in-progress conferences.

deaf

boolean

false

Join a conference unable to hear.

moderated

boolean

false

Indicates whether this conference is moderated.

moderator

boolean

false

Indicates that this channel should be a moderator.

moderatorTimeout

int

nil

If set to be zero or greater, is the number of seconds after the last moderator has left the conference that the entire confererence is taken down. Normally, a conference will go on until all attendees have left. The first attendee who sets this value to a non-negative number, sets it for the remaining duration of the conference. If it is not set at the time a moderator joins, that moderator does not count as someone triggering a teardown of the conference. This value is ignored in non-moderated conferences.

mute

boolean

false

Join a conference unable to speak.

playlist

audiostream.Playlist

nil

Specify a playlist which is heard before a second member joins the conference. This object can be constructed by the audiostream library.

Returns
Type Summary

ChannelReference or nil

Table of information about the call, or nil if this channel could not join the conference for some reason.

nil or string

If the conference was joined, this will be nil. Otherwise, it will be an error message. Possible messages are:

  • Conference not currently started and allowCreate is False
  • Could not start a conference
  • Over API limits
  • Over conference limits (total concurrent active conferences)
  • Over conference limits (total members across all active conferences)
  • Over conference limits (total members in this conference)
Usage
-- This would join a conference muted.
local result, err = channel.conference('my_conference', {mute=true, playlist=audiostream.playlist('hold_music')})
if err then
    channel.say('Could not join the conference, sorry')
end

dial(destination[, options])

Dial another extension or outside number. This function will block until the dial is completed. If the dial is answered, it will continue blocking until that call completes.

Note that the caller id (CID) rules are a bit involved. The options given in this command have the last word on how the CID is resolved, but there are a number of possible sources for the CID when it is not explicitly given here. The resolution will the done in this order:

  • If this is a scheduled call

    • channel CID options, if they are specified.
    • the destination number otherwise.
  • If this is an endpoint

    • the CID values for the endpoint, if they are specified.
    • the CID values for the endpoint’s settings group.

These values may be overridden if this is an outbound call and there is a set_caller_id value out the outbound route for the call and something has set a flag allowing its use. This flag can be set, in order of precendence:

  • in the channel.dial command’s allowOutboundRouteCallerId option
  • in a scheduled call’s channel_allow_outbound_route_caller_id field
  • in an endpoint’s allow_outbound_route_caller_id field
  • in a settings group’s allow_outbound_route_caller_id field, which defaults to true

Additionally, if this is an outbound call and a CID is specified, that caller id must be authorized for use by your domain. Authorized numbers can be viewed through the REST API endpoint /latest/caller_id_number.

For internal calls, the CID can be set to anything you like.

Note that caller id name is only meaningful for internal calls. The name that appears with the number for external calls is not settable by the caller and is under the control of whatever carrier is receiving the call.

Parameters
Name Type Default Summary

destination

string or table

The destination route / number / etc (see destinationType below) to dial

  • destination as a string – Supported by all.
  • destination as a list – Currently supported only by destionationType endpoint and outbound.

options

table

Optional

Parameter: options
Name Type Default Summary

allowOutboundRouteCallerId

boolean

nil

Whether or not to use any outbound route’s caller id settings. This parameter has the last word on whether or not the outbound route can determine the external caller id. If it is nil, then parameters elsewhere (eg settings group, endpoint, scheduled call record) are allowed to determine this allowance.

callerId

string

nil

Deprecated. Do not use this. See internalCallerIdName, internalCallerIdNumber and externalCallerIdNumber.

destinationType

string

'route'

Type of destination number; choices:

  • ‘route’ – a route, ex. “4145551234” or “1234”, anything you could dial from the phone normally
  • ‘endpoint’ – an endpoint, ex. “2001”
  • ‘outbound’ – dial through outbound routes, ex. “15555551234”
  • ‘channel’ – dial a channel to be connected to it which requires knowing the id of an existing (active) channel, ex. “7c7eb39a-e6e1-40bf-b841-6856f98bd7fb”

externalCallerIdNumber

string

nil

Caller id number to present on outbound calls. If this number is not authorized for use by your domain, it will default to the original caller’s caller ID.

forceTimeout

boolean

true

Set this to false to inherit an existing timeout from the context of a calling application or routepoint.

intercom

boolean

false

Whether or not to attempt to intercom (auto-answer) at the destination hardware. Be aware that intercom will only work if allow_intercom is true on the endpoint settings (eg settings group, or endpoint configuration record)

internalCallerIdName

string

nil

Caller id name to display to internally registered phones

internalCallerIdNumber

string

nil

Caller id number to display to internally registered phones

record

boolean

false

Whether to record the call

ringback

string or nil or sound

nil

The sound to be played to the user while waiting for the far side to answer or fail. If nil it will play the default US ring tone. Audio types are summit. Note that if a sound.tone is provided, it will be altered to loop endlessly. If a sound.silence is provided, it will be altered to have an endless duration.

timeout

number

30

Ring timeout

Returns
Type Summary

ChannelReference

Table of information about the call (see link)

Usage
-- Dial a route and set the caller id. If the domain does not own
-- the number being used for caller id, the original caller's id will be displayed
channel.dial('4145551234', {externalCallerIdNumber='4145559876', record=true})

-- Simple dial of an extension
channel.dial('2021')

-- Dial multiple extensions
channel.dial({'3001', '3002', '3003', '3004'}, {destinationType='endpoint'})

-- Dial multiple outbound
channel.dial({'4145551111', '4145552222', '4145553333'}, {destinationType='outbound'})

-- Dial a known channel
channel.dial('7c7eb39a-e6e1-40bf-b841-6856f98bd7fb', {destinationType='channel'})

-- Using `ringback`
local sound = require('summit.sound')
local asset = require('summit.asset')
local speech = require('summit.speech')

-- Ringback with a sound asset from the application's ./asset directory
channel.dial("5302xyz", {destinationType="endpoint", ringback="asset://sounds/coin.wav"})
channel.dial("5302xyz", {destinationType="endpoint", ringback=asset("sounds/coin.wav")})
channel.dial("5302xyz", {destinationType="endpoint", ringback=asset.get("sounds/coin.wav")})

-- Ringback with a TTS object
channel.dial("5302xyz", {destinationType="endpoint", ringback=speech("waiting.")})

-- Ringback with a tone
channel.dial("5302xyz", {destinationType="endpoint", ringback=sound.tone(500, 250, 174.61)})

-- Ringback dead silence
channel.dial("5302xyz", {destinationType="endpoint", ringback=sound.silence(-1)})
-- Ringback with silence, but louder comfort noise
channel.dial("5302xyz", {destinationType="endpoint", ringback=sound.silence(-1, 600)})

dtmf(input[, options])

Emits a DTMF signal.

Parameters
Name Type Default Summary

input

string

values to send, which must pass the regex validator [0-9a-dA-D#\*]+

options

table

Optional

Parameter: options
Name Type Default Summary

toneDuration

string

500

Time in milliseconds to play each tone (minimum 100)

Returns
Type Summary

nil

Usage
channel.dtmf('1432#', {toneDuration=250})

gather(options)

Prompt to collect DTMF. Collect DTMF input from remote party

If you need to collect 0-9 as well as # and *, you can accomplish this by setting delimiters to an impossible value like comma (,) and set your regex to \\d|\\*|#.

Parameters
Name Type Default Summary

options

table

Parameter: options
Name Type Default Summary

attempts

number

3

Maximum number of retries after ‘invalid’ state reached

delimiters

string

'#'

String of characters that, when pushed by the caller, completes gather and returns what has been gathered so far, if valid. The delimiter will not appear in the returned result.

digitTimeout

number

5

Number of seconds to wait between digits before considering gather to be ‘complete’.

includeDelimiter

bool

false

Determines whether any pressed delimiter is included in the returned value (ie: pressing ‘123#’ would return ‘123#’)

invalidPlay

string

nil

The filename or URL to be played when the caller does something invalid (timeout, improper number of digits, or entering of a digit that is not allowed). This parameter may not be a playlist.

maxDigits

number

100

Number of digits which, after reached, completes the gather.

minDigits

number

1

When gather completes, the minimum number of digits required to not be considered ‘invalid’ entry

play

string or table

nil

The sound to be played before gathering digits. The constraints on this value is are same as the play command.

regex

string

'\\d+'

Determines which input is ‘valid’ vs ‘invalid’

timeout

number

5

Number of seconds to wait for input, ‘invalid’ condition hit if reached. This timer begins only after the prompt audio has finished playing. Note that if streaming a playlist this timer will never begin as the audio stream has an infinite length.

Returns
Type Summary

string

String of number(s) pressed

Usage
local speech = require 'summit.speech'
local welcome = channel.gather({play={'/sounds/hello.wav', '/sounds/greeting.wav'}})
local x = speech('Enter your zip code.')
local zip = channel.gather({play=x, minDigits=5, maxDigits=5})

get_external_trunk_group()

Returns the trunk group name for the far end of this channel There may be times when you need to know the nature of the user in your application. Whether the call is inbound to summit or outbound, this tells you through what system that user is connected. Examples are “PSTN”, “Endpoint”, or other customer trunk group identifier.

Returns
Type Summary

string

Trunk group name

Usage
-- These examples would need to be set to a string matching the trunk group name that is assigned
-- to your customer account
local HOUSTON_PBX
local ORLANDO_PBX

-- ENDPOINT and PSTN are "virtual" trunk groups that everybody has.
local ENDPOINT = 'ENDPOINT'
local PSTN = 'PSTN'

local user_trunk_grup = channel.get_external_trunk_group()

-- Choose an IVR function
if user_trunk_grup == HOUSTON_PBX then
    do_houston_menu()
elseif user_trunk_grup == ORLANDO_PBX then
    do_orlando_menu()
elseif user_trunk_grup == PSTN then
    do_determine_inbound_destination()
elseif user_trunk_grup == ENDPOINT then
    do_agent_menu()
end

get_hangup_cause()

Get back the value of the current expected hangup_cause for the channel. This function will return whatever the current expected hangup_cause value is on this channel. If you've never called channel.set_hangup_cause, this should return ‘normal’. Otherwise, it will return whatever value has been set by that function.

Note that the value returned may not match the eventual channel CDR records; the current hangup_cause on the channel can always be overriden with an argument to channel.hangup.

Returns
Type Summary

string

The current expected hangup_cause for the channel. Default is ‘normal’ if nothing else has been specified yet.

Usage
local cause = channel.get_hangup_cause()
print(cause)  -- prints 'normal'

channel.set_hangup_cause("rejected")
local new_cause = channel.get_hangup_cause()
print(new_cause)  -- prints 'rejected'

hangup(options)

Send a hangup signal to the PBX. This is required to ensure a clean disconnect from the remote caller.

Parameters
Name Type Default Summary

options

table

Parameter: options
Name Type Default Summary

cause

string or nil

nil

The cause for the hangup. Note that including an argument here will overwrite anything set by channel.set_hangup_cause. Valid choices are:

  • ‘normal’
  • ‘canceled’
  • ‘busy’
  • ‘rejected’
  • ‘noanswer’
  • ‘unregistered’
  • ‘unallocated’
  • ‘congestion’
  • ‘failure’

withAnswer

boolean

false

Answer first, then hangup.

Returns
Type Summary

nil

Usage
-- Dial an endpoint
local dial_result = channel.dial("1234", {destinationType="endpoint"})
-- Check the result: if no one answered, pass that result on
if dial_result.hangupCause == "noanswer" then
    channel.hangup({cause="noanswer"})
else
    channel.hangup()
end

is_pstn()

Returns whether or not the user on the channel is on the Public Switched Telephone Network For intents and purposes, is_pstn() is effectively a wrapper for get_external_trunk_group() == ‘PSTN’

Returns
Type Summary

boolean

True if the channel is a PSTN channel.

Usage
if channel.is_pstn() then
    do_external_user_ivr()
else
    do_internal_user_ivr()
end

play(filename, options)

Play a file, url, or stream a playlist. Play a sound asset from the application’s assets directory or from a URL, or stream an audiostream playlist.

Parameters
Name Type Default Summary

filename

string or table

The file name or URL where the file is located. This method also accepts objects created by the sound library. A list of sounds to be played sequentially may also be passed. Example: {'/sounds/intro.mp3', 'asset://sounds/greeting.wav'}.

If a playlist constructed by the audiostream library is given, it must be given alone. It is illegal to pass a playlist along with another sound source.

options

table

Parameter: options
Name Type Default Summary

interruptOnDTMF

boolean or string

false

Playback is DTMF interruptable. If true, any DTMF input will interrupt playback. If a string is given, only DTMF input contained in the string will interrupt playback.

loop

number

1

Number of times to play file. This parameter will be ignored when streaming a playlist.

recordingType

string

'auto'

Type of recording passed to play(). Available options:

  • ‘auto’
  • ‘voice’

timeout

number

nil

Number of seconds before playback times out.

Returns
Type Summary

string or nil

If playback was interrupted by DTMF, this value is the digit entered. Otherwise, this value is nil.

Usage
channel.play({'/sounds/intro.mp3', 'asset://sounds/greeting.wav'})

local speech = require('summit.speech')
local x = speech('Hello!')
channel.play(x, {loop=3})

local audiostream = require('summit.audiostream')
local y = audiostream.playlist('greetings-from-paradise')
local result, err = channel.play(y)
if err == nil and result then
    channel.say('You entered ' .. result)
end

recognize(grammar[, options])

Recognize speech input. Match speech from a remote party to a given interpretation.

Billing is determined by the amount of time connected to the speech recognition server. Specifically, this duration is pinned between the when the audio prompt begins to play and when the speech server’s interpretation response is received. Note that this is necessary as a user’s utterance may interrupt the prompt.

Parameters
Name Type Default Summary

grammar

GrammarRule or string

A grammar or a raw string. Grammars must be constructed via functions in the grammar building library.

options

table

Optional

Parameter: options
Name Type Default Summary

attempts

number

3

Maximum number of retries after ‘invalid’ state is reached.

delimiters

string

'#'

String of characters that, when pushed by the caller, completes gather and returns what has been gathered so far, if valid.

digitTimeout

number

5

Number of seconds to wait between DTMF input before considering recognize to be ‘complete’.

enableDTMF

bool

false

Allow speech recognition to be interrupted by DTMF input. This flag is set implicitly with the presence of the mapping or regex parameters. If this flag is set but the mapping parameter is not supplied, then the digits that the user entered will be returned un-interpreted. The user input can be validated by using the regex, delimeter, and includeDelimiter parameters.

includeDelimiter

bool

false

Determines whether any pressed delimiter is included in the returned value (ie: pressing ‘123#’ with a delimiter of ‘#’ would return ‘123#’ instead of ‘123’ when this flag is true).

invalidPlay

string

nil

Played when the caller does something invalid, either a timeout, a failed recognize, or an invalid DTMF input.

mapping

table

nil

A list of pairs specifying how to interpret DTMF input. The first value in a pair should be a PCRE regular expression pattern which will implicitly match the entire DTMF input (hence there is no need for the ^ or $ metacharacters). The second value in a pair should be the interpretation of the input. If the first pair contains a capture group, the second pair can reference that capture group. For example, if the mapping includes the pattern 1(\d+) and the value of this pattern is ext-\1, then an input of 12345 would be interpreted as ext-2345.

This field will implicitly populate the regex field, and hence both parameters are mutually exclusive. The order of the regular expressions are important – they will be matched in the order supplied. If a more general regular expression is supplied earlier than a more specific one, then the more general expression will always match. See the usage at the bottom of this section for an example.

maxDigits

number

1000

Number of digits which, after reached, completes the DTMF input.

maxVoiceLength

number

5

Number of seconds to wait after voice input has started before considering recognition to be ‘complete’. This timer will continue to run as the user speaks. If the user halts speech, the timer will continue to remain active.

minConfidence

number

60

The minimum confidence threshold input has to exceed in order to be considered ‘valid’. A confidence threshold between 0 (no confidence) and 100 (perfect confidence) is returned from the server. If all interpretations of the user’s utterance fall below this threshold, then recognition fails. If recognition fails due to this, the RecognizeResult value will indicate the reason.

minDigits

number

1

The minimum number of DTMF digits required to not be considered ‘invalid’ entry.

name

string

nil

[] An identifier for this invocation of recognize. This may appear in user-facing logs and billing statements. This identifier is truncated if it is larger than 255 characters.

play

string or table

nil

Sound to be played at the start of the command when speech input may begin. A user’s utterance or a DTMF tone (if enabled) may interrupt playback. You may specify multiple sounds/files to play by using a table. For example: {'/sounds/hello.wav', '/sounds/greeting.wav'}

regex

string

'\\d+'

Determines if DTMF input is ‘valid’ or ‘invalid’ by matching the user input against the PCRE regular expression.

timeout

number

5

Number of seconds to wait for either voice or DTMF input, ‘invalid’ condition hit if reached. This timer starts after the initial prompt sound has finished.

Returns
Type Summary

RecognizeResult or nil

Data about the recognized speech, or nil if there was a problem.

string or nil

If RecognizeResult is nil, then this will be an error message of the form Bad call to recognize: {reason}, where reason may be one of the following.

  • Expected a grammar object when a non-grammar object is passed as the primary argument.
  • Invalid item text: {text} when text supplied to a grammar contains illegal characters. Legal items contain only letters, numbers, spaces, and the punctuation set ., ,, ?, !. The {text} portion of the message will contain the offending string.
  • Invalid tag text: {text} when a meaning supplied to a grammar contains illegal characters. Meanings cannot contain double-quote characters. The {text} portion of the message will contain the offending string.
  • Grammar too large when the compiled grammar string exceeds the maximum grammar size which is currently one million characters.
  • Mapping supplied but DTMF is explicitly suppressed when enableDTMF is false but the mapping parameter is non-nil.
  • Regex supplied but DTMF is explicitly suppressed when enableDTMF is false but the regex parameter is non-nil.
  • Mapping and regex options are mutually exclusive when both the mapping and regex parameters are supplied.
  • grammar-error when a grammar is malformed. This should not occur when grammars that are constructed using the grammar building library.
  • asr-init-error when there is a connection error to the speech recognition server.
Usage
local speech = require "summit.speech"
local grammar = require "summit.speechrec.grammar"

local grm = grammar.choice({'English', 'Spanish', 'French'})

local result, err = channel.recognize(grm, {
    play=speech.speech(
      'Press 1 or say English for English' ..
      'Press 2 or say Spanish for Spanish' ..
      'Press 3 or say French for French'
    ),
    mapping={
        {'1', 'English'},
        {'2', 'Spanish'},
        {'3', 'French'},
    },
    maxDigits=1,
})

record([options])

Collect channel audio into a recording object.

Parameters
Name Type Default Summary

options

table

Optional

Parameter: options
Name Type Default Summary

detectSilence

boolean

false

If true, the recording will automatically end when it detects a configurable period of silence.

finishOnKey

string

'1234567890#*'

Terminate recording on pressed digit. Defaults to stopping on any digit pressed.

maxLength

number

3600

Number of seconds, after which, recording will stop automatically.

playBeep

boolean

true

Play beep on recording start.

silenceLength

int

3

The number of seconds of silence to wait before ending the recording.

silenceThreshold

int

200

A configurable level of silence. Increasing this number will increase the threshold (higher numbers mean more noise will count as silence). Generally, we'd suggest leaving this at the default level.

Returns
Type Summary

RecordingResult

Usage
local result = channel.record({finishOnKey='#', maxLength=60, playBeep=false})
local with_silence = channel.record({detectSilence=true, silenceLength=5})

ring()

Send ringing audio to channel, useful for simulating ring sounds before channel.answer() has been called.

Returns
Type Summary

nil

say(text[, options])

Call out to TTS engine.

Parameters
Name Type Default Summary

text

string or table

String to pass to TTS. A table can also be used to specify multiple strings or text files to say. For example: {'asset://text/greeting.txt', 'hello'}

options

table

Optional

Parameter: options
Name Type Default Summary

interruptOnDTMF

boolean

false

language

string

'en'

voice

string

'woman'

Returns
Type Summary

nil

Usage
channel.say('Hello there!', {voice='man'})

set_hangup_cause(cause)

Sets the default hangup cause to be used when the channel hangs up. This function will set the default hangup_cause on the current channel. Whenever the channel hangs up, this value will be used. You can also override this by calling channel.hangup and specifying a cause argument, in which case anything set by this function will be ignored.

If you call channel.application and that Summit application uses this method to set a hangup_cause, that cause will persist on the channel. If you later call channel.hangup without specifying a cause, your channel will use whatever was last set by this method (in this case, whatever was set by the other application).

Parameters
Name Type Default Summary

cause

string

nil

The hangup cause to set on this channel. Choices are:

  • ‘normal’
  • ‘canceled’
  • ‘busy’
  • ‘rejected’
  • ‘noanswer’
  • ‘unregistered’
  • ‘unallocated’
  • ‘congestion’
  • ‘failure’
Returns
Type Summary

bool or nil

Returns true on success, nil on failure

nil or string

On error, returns a description of what went wrong

Usage
channel.set_hangup_cause("rejected")
-- later...
channel.hangup()
-- The `channel` CDR record will have a hangup_cause of "rejected"

sleep(seconds[, options])

PBX level sleep function. This is useful because it allows you to create DTMF-interruptable sleep statements.

Parameters
Name Type Default Summary

seconds

number

Float representing how many seconds to sleep (decimals are ok, such as “1.5”)

options

table

Optional

Parameter: options
Name Type Default Summary

interruptOnDTMF

boolean

false

Timer is DTMF interruptable

Returns
Type Summary

nil

Usage
do_something()
channel.sleep(5, {interruptOnDTMF=true})
do_something_5_seconds_later_or_after_DTMF_interrupt()

Fields : channel

data.ani

Type: string

The Source Phone Number (Indiscriminate of call direction!!)

data.channel_id

Type: string

The ID of the channel for the app (UUID)

data.custom_sip_headers

Type: table

Custom SIP headers (those that start with X-*) for this channel.

data.destination

Type: string

The internally routed number, changes every time a channel is transferred internally. Not terribly useful for most apps

data.direction

Type: string

The direction of the call (“inbound” means calling in to the system, “outbound” means calling out from the system)

data.diversion

Type: string or nil

If this call was diverted, this will be the raw SIP Diversion header. A diverted call would be a call that was forwarded from a carrier using a call forwarding feature or some other diversion mechanism. The values in diversion_number and diversion_params are parsed versions of this header and are most likely more useful.

data.diversion_number

Type: string or nil

If the current call was diverted, this will be the phone number it was diverted from.

data.diversion_params

Type: table or nil

If the current call was diverted (eg forwarded via call forwarding) it will contain the parameters of that diversion. The most common and interesting paramter will be ‘reason’ which will indicate why the call was diverted. Typical values are, ‘busy’ when a line is busy, ‘unconditional’ for call forwarding, and ‘unavailable’.

data.dnis

Type: string

The Dialed number (indiscriminate of call direction!!)

data.domain

Type: string

The SIP domain associated with the tenant (UUID)

data.localnumber

Type: string

The system’s phone number (==dnis for inbound, ==ani for outbound)

data.remotenumber

Type: string

The supposed human’s phone number (==ani for inbound, ==dnis for outbound)