Interaction

Introduction

An SCP Lua script may request that the caller be directed to an on-switch or external SRF using ConnectToResource or EstablishTemporaryConnection as appopriate.

For external SRFs, the service must specify a known SRF Name as configured within the LhoScpApp list of configured SRF nodes.

If a different SRF is currently open from a previous interaction, then a prior DisconnectForwardConnection will be sent on the SSP transaction, and any external SRF transaction will be ended according to the applicable SRF configuration.

The processing will suspend until the SRF indicates completion of the interaction, or a guard timer expires. In the “normal” case where the caller waits for the announcement to end, the call will continue to be “controlled”, and the service logic may carry on and attempt other telephony actions.

The LhoScpLuaService Interaction API

.interaction

This method provides full access to the Interaction mechanism and is provided for use by custom service developers. In the majority of scenarios, one of the subsequently-described convenience methods should be sufficient and preferable. However, this full-featured alternative is provided for use by complex or non-standard services.

This method takes a single details parameter which is a Lua table with the following structure:

The interaction method returns a structure indicating the result of the interaction.

Example (prompt and collect 4 digits):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

scp_api.set_language ('German')
local result = scp_api.prompt_and_collect (srf_name, message_id, nil, 4, 4, options)

local.result = scp_api.interaction ({
    srf_name = 'DefaultSRF',
    message_id = 1010,
    language = 'English',
    prompt = 1,
    min_num_digits = 4,
    max_num_digits = 4
})

-- Note that it is possible to get digits even if the A-Leg control was lost.
if (result.digits) then
    n2svcd.notice ("DIGITS = %s")

-- In the case of non-collection, we might have been abandoned, or we might 
-- have encountered a problem on the SRF (e.g. bad announcement, collection timeout).
-- At least one explaination will apply.
--
else 
    n2svcd.notice ("NON-COLLECT = %s", result.error or result.reason)
end

-- If the call control w
if (result.controlled) then
    scp_api.release_call (5)

else
    n2svcd.notice ('Interaction Abandoned = %s', result.reason)
end

return 

.set_language

The set_language method sets the language name that will be passed in future calls to the following interaction helper methods. It takes a single argument:

.play_announcement

The play_announcement method takes the following arguments:

The language will be the value in the most recent call to .set_language (or nil).

The play_announcement method returns the same result structure as interaction.

Example (two message IDs, with retry on failure):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

scp_api.set_language ('English')
local result = scp_api.play_announcement ("SWITCH", { 1070, 1073 }, { { integer = 5000 }})

if (result.error and result.controlled) then
    scp_api.set_language (nil)
    result = scp_api.play_announcement ("SWITCH", { 1080, 1073 }, { { integer = 5000 }})
end

-- Call will release automatically on exit.
return 

.prompt_and_collect

The prompt_and_collect method sets the prompt flag to request the SRF to collect digits input by the caller. It has additional parameters, including the minimum and maximum number of digits to collect.
It also allows some additional refined control options.

The prompt_and_collect method takes the following arguments:

The language will be the value in the most recent call to .set_language (or nil).

The prompt_and_collect method returns the same result structure as interaction.

Example (prompt for exactly 4 digits and play them back):

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call = ...

local SWITCH = "SWITCH"

-- Override some options for no good reason at all.
local options = {
    end_digit = '*',
    cancel_digit = 'e',
    first_digit_timeout = 6,
    inter_digit_timeout = 4,
    interruptable = false
}

-- Collect exactly 4 digits, or none at all.
local result = scp_api.prompt_and_collect (SWITCH, 3007, nil, 4, 4, options)

-- If the caller is gone, we don't bother going on.
if (not result.controlled) then
    return
end

-- Our scenario REQUIRES digits.
if (not result.digits or not string.len (result.digits)) then
    error "No digits entered, cannot continue."
end

-- Play back the collected digits (as "number digits" type).
result = scp_api.play_announcement (SWITCH, 4040 nil, { { number_digits = result.digits } })

-- This will automatically release the call (if needed) with default release cause.
return