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.