☰
Navigation :

Interaction (RTP)

Introduction

An SIP LUA script may request that the A-Leg be connected to a locally generated RTP stream for the purpose of playing announcements with optional digit collection.

This requires that an RtpApp instance is running locally, and is configured as a known resource for the LhoSipApp which is controlling the call. The controlling LhoSipApp will perform the relevant A-Leg SIP messaging necessary to connect to the internal RTP player, using one of:

Here is the overall flow for the interaction case using the SIP INVITE Response (200 OK) mechanism to connect to our internal RTP-streaming Media Server:

Message Flow (Internal RTP Interaction)

Service logic processing will suspend until:

The LhoSipIncallLuaService Interaction API (Internal/RTP)

.rtp_interaction [Asynchronous]

This method provides full access to the Interaction mechanism for the Internal RTP resource.

This method takes two arguments:

Argument Type Description
announcement Object A structure defining the announcement interaction which is to be performed.
(Default = Open the RTP connection but do not play any announcement).
.message_id Integer A single message ID to play.
This ID must be configured within the RtpApp database or file-based configuration.
The definition of this ID may depend on the specified language, and the definition may allow multiple audio file fragements and/or one or more variable parts.
Specify exactly one of .message_id or .message_ids or .files.
.message_ids Array of Integer An array of one or more message IDs to play in sequence.
Each ID listed here must be configured within the RtpApp database or file-based configuration.
The definition of each ID may depend on the specified language, and the definition may allow multiple audio file fragements and/or one or more variable parts.
Each ID listed here may contain variable parts. The supplied variable parts list must contain sufficient variable parts for all message IDs.
Specify exactly one of .message_id or .message_ids or .files.
.files Array of String Explicit Array of one or more filenames to play in sequence. Specifying this parameter will bypass the message ID translation process in RtpApp and allows the service logic to explicitly control the audio file fragments to be streamed.
All filenames must be from the announcement language, it is not possible to override the language per-fragment.
Each filename must not include the audio file type suffix part e.g. must not contain the .ul, or .amr.
Each filename must include the subdirectory announcements or variable_parts.
The directory name "a" is a supported abbreviation for "announcements".
The directory name "vp" or "v" is a supported abbreviation for "variable_parts".
Example files list: [ 'a/You_Entered', 'v/1', 'vp/4' ].
.language String Optional language name to use instead of the default value configured within the RtpApp.
The RtpApp will use this when mapping announcement ID/IDs into a file list.
The RtpApp will use this expanding variable parts into audio file fragments.
This language name must be configured within the RtpApp database or file-based configuration.
Refer to the RtpApp configuration documentation.
(Default = The default language configured in the RtpApp)
.repetition Positive Integer A requested repetition count, the announcement will be repeated up to the indicated number of times.
(Default = Play the announcement list only once).
.duration Positive Integer The total permitted duration of the interaction including repetitions and any silence.
(Default = the configured rtp_max_play_secs for the SipApp).
.variables Array of Object An array of variable values to substitute into pre-defined placeholders in the message structure.
Each variable part is an object which specifies exactly one of the attributes as follows.
.integer Integer An integer value to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.number_digits Integer An integer value to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.time_hhmm <HHMM> An integer hour and minute to speak as a variable part.
Value is in the range 0000-2400.
Construction rules for the chosen/default langage will be used.
.date_yymmdd <YYMMDD> A 6-digit integer year/month/day to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.date_yyyymmdd <YYYYMMDD> An 8-digit integer year/month/day to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.price_digits Integer An integer value of "cents" to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.collect Object Container for information related to digit collection.
Digit collection will be performed if and only if this container element is present.
(Default = do not collect user input digits).
.min_num_digits 1 - 32 The minimum number of digits which the internal Media Server will be instructed to collect.
[Required] This value is required when collect is specified.
.max_num_digits 1 - 32 The maximum number of digits which the internal Media Server will be instructed to collect.
This value must be greater than or equal to min_num_digits.
[Required] This value is required when collect is specified.
.end_digit #*A-F0-9 The digit which specifies End of Input.
(Default = The default value configured in the RtpApp).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
(Default = The default value configured in the RtpApp).
.first_digit_timeout Positive Integer The number of seconds allowed between completing the announcement and entering the first digit.
(Default = The default value configured in the RtpApp).
.inter_digit_timeout Positive Integer The number of seconds allowed between entering one digit and entering the subsequent digit.
(Default = The default value configured in the RtpApp).
.interruptable 0 / 1 Informs the internal Media Server that DTMF input from the user should interrupt the playing of the prompt.
(Default = the prompt may be interrupted by the user).
.private_digits 0 / 1 Indicates that the collected digits are private, e.g. PIN entry, and the framework should not log them to EDR.
(Default = the default behavior configured for the application).
aleg_headers Object Additional headers to add to the `SIP INVITE Response (200 OK)` or `SIP re-INVITE Request` sent to the A-Leg when the RTP resource is connected.
The table entry key is the header name.
Each table entry value is a list (array) of header value strings.
(Default = do not add extra user headers).

The rtp_interaction method returns a LUA table with the following attributes.

Attribute Type Description
.controlled Boolean [Required] Is this call still controlled, i.e. can subsequent SIP actions be performed?
.error String An optional interaction error related to a problem in playing the announcement or collecting input.
If this parameter is defined, then the service logic should assume that the announcement audio was not successfully communicated to the user, e.g. the RTP application is at capacity or could not be reached, some audio files were missing, some interaction parameters were invalid, etc.
.digits #*A-F0-9 Input digits collected from user.
May include * or # characters according to the local Media Server's interpretation.
The .digits and .error are mutually exclusive.
One of .digits or .error will be present when .reason is not present and digit collection was requested.
.reason Abandoned Reason for loss of call control during interaction.
This field is present is present if and only if .controlled is false.
.decline_ok Boolean Can the service logic still use the .proceeding and .decline methods?
This field is present is present if and only if .controlled is true.
This field will be true if we have not yet sent a 2XX or 300-699 Response code.

Example (simple announcement):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

WELCOME_ID = 4022

local scc = ...

incall_api.rtp_interaction ({ message_id = WELCOME_ID })

return

Example (one integer variable part):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

local scc = ...

NUM_DAYS_ID = 1020

if (not result.controlled) then
    error ("Caller Abandoned during Answer.")
end

incall_api.rtp_interaction ({ message_id = NUM_DAYS_ID, variables = { integer = 356 } })

return

Example (collect 4 digit PIN):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

local scc = ...

ENTER_PIN_ID = 1044

incall_api.rtp_interaction ({ message_id = ENTER_PIN_ID, collect = { min_num_digits = 4, max_num_digits = 4 }})

return

Example (play specific files with limited duration):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

local scc = ...

result = incall_api.rtp_interaction ({ duration = 4, files = { 'a/Goodbye', 'announcements/Goodbye', 'v/1', 'a/Welcome_To_Demonstration', 'a/Welcome_To_Demonstration' } })
if (not result.controlled) then return end

return

.set_language [Pure Lua]

The set_language method sets the Language Name for any subsequent interaction processing.

This method takes a single argument:

Argument Type Description
default_language String The new default Language for all subsequent calls to the interaction helper methods.
Specify `nil` to default to the default language for the internal Media Server.

.set_early_media [Pure Lua]

The set_early_media method sets the Early Media preference subsequent interaction processing.

This method takes a single argument:

Argument Type Description
default_early_media require / prefer / allow / never The new default early media preference for all subsequent calls to the interaction helper methods for internal Media Server interaction.
See the documentation for the early_media parameter in the interaction method.
Specify `nil` to default to the early media behavior for the internal Media Server.