☰
Navigation :

RTP Language Lua Agent

RTP Language Lua Agent Module

Introduction

The RTP Language Agent is an synchronous API for LUA scripts to query the internal RPT “variable parts” builder for variable parts files to play when generating dynamic content - such as numbers, prices, and dates.

The information provided by this agent module can be used when calling the rtp_interaction() API for an inbound SIP call being handled by the SIP-AS.

Configuring the Agent

The RTP Language Agent is configured within a LogicApp.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="Logic" module="LogicApp">
          <include>
            <lib>../apps/logic/lib</lib>
          </include>
          <config>
            <agents>
              <agent module="RtpApp::RtpLanguageLuaAgent" libs="../../n2sip/apps/rtp/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, the following agent attributes apply:

Attribute Type Description
module RtpApp::RtpLanguageLuaAgent [Required] The module name containing the LUA Agent code.
libs ../../n2sip/apps/rtp/lib Location of the module.

Invoking the RTP Language Agent

A LUA Script can access the language agent actions with code such as the following. This is an example REST server Lua script:

local n2svcd = require "n2.n2svcd"
local rtp_lang = require "n2.n2sip.rtp_lang_agent"

local rest_request = ...
local lang   = rest_request.query_args.lang
local gender = rest_request.query_args.gender
local value  = rest_request.query_args.value

-- use expand_price, expand_yyyymmdd etc instead of expand_integer
-- for different builder expansions.
prompt_list = rtp_lang.expand_integer (lang, value, gender)

if type(prompt_list) == 'string' then
    return {
        code = 400
        , content_type = 'text/plain'
        , content = prompt_list
    }
end

local content = "[\n";
for i = 1, #prompt_list, 1 do
    content = content .. '"' .. prompt_list[i] .. '"'
    if i ~= #prompt_list then
        content = content .. ",\n"
    end
end
content = content .. "\n]";

return {
    code = 200
    , content_type = 'application/json'
    , content = content
}

This shows an example of a REST interface generating a JSON array of files to play for an integer where the language, and value are provided as parameters to the HTTP query.

The RTP Language Agent API

All methods may raise a LUA Error in the case of exception, including:

.expand_integer [Synchronous]

The expand_integer generates the list of files to play a non-negative integer value as audio.

Argument Type Description
lang An ISO code as a String The ISO code, such as `en-GB` or `ar-AE` indicating the language to build the announcement using. The country-code is ignored, only the language code is used.
value String & Integer The value to generate audio for.
gender String Either 'M' for Male gender audio, or 'F' for female. Most language builders do not support Gender. Arabic (any language code of `ar`) does. A default will be used if one is not given.

The expand_integer method returns a result either as a string, which indicates and error, or an array (table) of strings which is a list of audio files that when played back will represent the given value in the given language & gender.

.expand_price [Synchronous]

The expand_price generates the list of files to play a non-negative price small and big units). The price must be given in the format ddddddcc where cc is the littles (cents/piaster etc) and dddddd is the bigs (dollars/pounds etc)

Argument Type Description
lang An ISO code as a String The ISO code, such as `en-GB` or `ar-AE` indicating the language to build the announcement using. The country-code is ignored, only the language code is used.
value String & Integer The value to generate audio for.

The expand_price method returns a result either as a string, which indicates and error, or an array (table) of strings which is a list of audio files that when played back will represent the given value in the given language.

.expand_hhmm [Synchronous]

The expand_hhmm generates the list of files to play a time of day (hours & minutes)

Argument Type Description
lang An ISO code as a String The ISO code, such as `en-GB` or `ar-AE` indicating the language to build the announcement using. The country-code is ignored, only the language code is used.
hhmm String The time of day to generate audio for.

The expand_hhmm method returns a result either as a string, which indicates and error, or an array (table) of strings which is a list of audio files that when played back will represent the given time of day in the given language.

.expand_yyyymmdd [Synchronous]

The expand_yyyymmdd generates the list of files to play a day of year. The format the date should be played in is given as the third argument.

Argument Type Description
lang An ISO code as a String The ISO code, such as `en-GB` or `ar-AE` indicating the language to build the announcement using. The country-code is ignored, only the language code is used.
yyyymmdd String The day of the year to generate audio for.
format String One of `DATE_DDTH_MONTH_YEAR`, `DATE_DDTH_MONTH`, `DATE_WEEKDAY_DDTH_MONTH_YEAR`, or `DATE_WEEKDAY_DDTH_MONTH`.

The expand_yyyymmdd method returns a result either as a string, which indicates and error, or an array (table) of strings which is a list of audio files that when played back will represent the given day of year in the given language. The format depends on the format requested: