Navigation :

SIP Incall Lua Service

LhoSipIncallLuaService Module

Introduction

The LhoSipIncallLuaService is a service for initiating Lua scripts to control inbound SIP calls. The Lua logic runs within the LogicApp (see core n2svcd documentation).

The LhoSipIncallLuaService receives messages from one or more instances of the LhoSipApp which is configured to receive inbound SIP INVITE Requests from an external client.

The LhoSipIncallLuaService communicates with the LhoSipApp using the SCC-… messages.

For initiating outbound SIP calls, an already running Lua script use the LhoSipOutcallLuaAgent.

Configuring LhoSipIncallLuaService

The LhoSipIncallLuaService 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>
          <parameters>
            ...
          </parameters>
          <config>
            <services>
              <service module="LhoSipApp::LhoSipIncallLuaService" libs="../../n2sip/apps/lho_sip/lib" script_dir="/var/n2sip/scripts">
                <triggers>
                  <trigger called_prefix="800" script_key="800_digit_menu"/>
                  <trigger called_prefix="811" script_key="811_rest"/>
                  <trigger called_prefix="900" script_key="900_mca"/>
                </triggers>
              </service>
            </services>
            <agents>
              ...
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, the following service parameters apply:

Parameter	Type	XML Type	Description
`module`	`LhoSipApp::LhoSipIncallLuaService`	Attribute	[Required] The module name containing the Lua Service code.
`libs`	`../../n2sip/apps/lho_sip/lib`	Attribute	Location of the `module` for LhoSipIncallLuaService.
`script_dir`	String	Attribute	[Required] The directory containing scripts used by this service.
`default_no_answer_secs`	Integer	Attribute	The default number of seconds to wait for No Answer on an a B-Leg termination attempt, when the service logic does not explicitly specify a no-answer timeout value. (Default = `60` seconds).
`default_pa_wait_secs`	`1` - `600`	Attribute	The number of seconds to wait for a non-`prompt` Interaction action to complete when the service logic does not specify a duration. (Default = `120` seconds).
`default_pacui_wait_secs`	`1` - `600`	Attribute	The number of seconds to wait for a `prompt` Interaction action to complete when the service logic does not specify a duration. (Default = `300` seconds).
`wait_margin_secs`	`1` - `15`	Attribute	The number of seconds to add to the wait time for all SIP call control actions to account for round-trip latency. (Default = `5` seconds).
`triggers`	Array	Element	Array of `trigger` elements specifying Lua scripts to run for SIP Incalls.
`.trigger`	Object	Element	Provisions a trigger which guides Lua script selection.

See also the script-loading and refresh timing parameters for all file-scripted Lua Service Loaders described as part of the LogicApp documentation.

Script Trigger Rules

Each SIP Incall trigger rule defines the name of a script which is ready to handle an incall for some/all called and/or calling party addresses. For SIP Incalls the called party address is the portion before the @ in the URI contained in the SIP To header, and the calling party address is the portion before the @ in the URI contained in the SIP From header

This may include non-digit characters, in which case the matching is case-insensitive.

Each trigger Object in the config.triggers Array is configured as follows.

Attribute	Type	Description
`from_otg` / `otg`	String	Specify that this trigger applies only for an exact `otg` (Outgoing Trunk Group) tag on the SIP `From` URI. For example, a SIP INVITE `From` header `<sip:12456@Test-SS;otg=NP>;tag=Sqepd3Ad9` would match `otg` = `NP`. (Default = Trigger applies to all SIP Incalls).
`to_dtg` / `dtg`	String	Specify that this trigger applies only for an exact `dtg` (Destination Trunk Group) tag on the SIP `To` URI. (Default = Trigger applies to all SIP Incalls).
`called`	String	This trigger applies for only Incalls to this exact called party. (Default = Trigger applies to all SIP Incalls).
`called_prefix`	String	This trigger applies for only Incalls to called parties starting with this prefix. (Default = Trigger applies to all SIP Incalls).
`calling`	String	This trigger applies for only Incalls from this exact calling party. (Default = Trigger applies to all SIP Incalls).
`calling_prefix`	String	This trigger applies for only Incalls from calling parties starting with this prefix. (Default = Trigger applies to all SIP Incalls).
`script_key`	String	[Required] The key of the Lua script to load and run. This is the file name excluding the ".lua"/".lc" suffix. The script should reside in the configured `script_dir` directory. Note that derived subclasses such as `AcdSipApp::AcdSipLuaService` may allow `script_key` to be undefined here, and will instead perform a dynamic database lookup to determine the script key.

Script Selection (SIP Incall Request)

The Lua Script selection to execute for a SIP Incall is a function of the called party and/or calling party digits in the INVITE. The LhoSipApp expects the SIP invite to contain From and To addresses where the username part before the @ is in the format of a PSTN phone number, optionally with a leading + character.

The LhoSipApp will extract the phone number part from the From/To addresses and will supplied that as the called/calling party number to the SIP Incall Lua Service.

The SIP Incall Lua Service will iterate the configure trigger entries in the sequence in which they are configured and find the first trigger which matches the received called and/or calling parties (or a script which matches all called and/or calling parties).

Refer to the LogicApp configuration for more information on directories, library paths, and script caching parameters.

Script Entry Parameters (SIP Incall Request)

The Lua script defines the service processing steps, such as the following:

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

local scc = ...

-- No Thanks.
incall_api.decline (607)

return

The service script will be executed with a single scc entry parameter:

Field	Type	Description
`scc`	Object	[Required] The SCC control parameters for the message. This is a pass-through of the `scc` attribute of the `SCC-HANDLE-ALEG-INBOUND-INVITE` message.
`.calling_party`	(+)Hex String	[Required] Calling Party address digits. This is the part of the `From` address which precedes the `@`. It is guaranteed to contain only `0-9A-F` digits.
`.called_party`	(+)Hex String	[Required] Calling Party address digits. This is the part of the `To` address which precedes the `@`. It is guaranteed to contain only `0-9A-F` digits.
`.pending_tn`	(+)Hex String	[Required] Pending termination number digits. It is guaranteed to contain only `0-9A-F` digits.
`.from`	Table	[Required] The decoded object representation of the "From" header.
`.header`	String	[Required] The original "From" header value, complete.
`.display_name`	String	The Display Name, if present.
`.parameters`	Table	A map of top-level parameter values (not the address parameters). This will include the `tag`, and could include `isup-oli` or other site-specific parameters. A parameter, e.g. `;urgent` will be present with a value of `UNDEF`.
`.address`	Table	[Required] Container for the Address attributes.
`.uri`	String	[Required] The complete encoded URI including address parameters, but not including any `< >`.
`.protocol`	String	[Required] The protocol, `sip` or `tel`.
`.user`	String	[Required] The user part of the address, preceding the `@`.
`.host`	String	The host part of the address, if present.
`.port`	Integer	The port number part of the address, if explicitly present.
`.parameters`	Table	The inner address parameters (not the top-level parameters). This will include the `transport` parameter (if explicit), and could include `otg` or other site-specific parameters. A parameter, e.g. `;exdirectory` will be present with a value of `UNDEF`.
`.to`	Table	[Required] The decoded object representation of the "To" header. The table structure is identical to the structure described for the "From" header.
`.privacy`	Table	This table will be present only when both the `sip_privacy_header` parameter is enabled for the application, and the `Privacy` header is present in the received A-Leg SIP INVITE. In this case, this table will have entries with keys matching each of the Privacy attributes which are present in this header, each with the value `1`. For example if the `Privacy` header has value `user;id` then this table will be `{ user = 1, id = 1}`. (Default = The header was not present, or the feature is not enabled for the app)
`.extra_headers`	Table	A table of extra headers "of interest" from the received A-Leg SIP INVITE. These are only headers specifically configured in the `<invite_headers>` configuration block. Each table entry is a non-empty list of raw header values parse for that header name. The header name key is upper/lower case as defined in the `name` attribute of the `<invite_header>` configuration, even though the matching for the header name in the SIP INVITE is performed using case-insensitive matching. (Default = no headers of interest were matched)

Script Return Parameters (SIP Incall Response)

The return value from the Lua script should always be nil. Returning any other value will generate a warning to the syslog.

The LhoSipIncallLuaService API

A script processing SCC incalls must use the SIP SIP Incall API.

    local incall_api = require "n2.n2svcd.sip_incall_service"

The following SIP functions are available for a controlled call.