☰
Navigation :

LhoSipApp

LHO SIP Application Configuration

The LHO (Logic Hand-Off) SIP Application performs SIP call control under the control of an separate LogicApp instance. The LHO Application is a component in the integrated N-Squared “SIP Application Server” Product.

The LHO SIP Application supports both SIP Incall and SIP Outcall scenarios under the control of a logic script written in the Lua scripting langage.

The LHO SIP Application supports playing announcements in two different modes:

Note that the LHO SIP App does not support voice recording at this time.

Note that the LHO SIP App is only an end-point for RTP streams. It does not proxy/transcode RTP packets.

The LhoSipApp relies on three other applications:

Here is a LHO SIP Application config example.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <!-- SIP call controller application. -->
        <application name="LHO" module="LhoSipApp">
          <include>
            <lib>../../n2sip/apps/lho_sip/lib</lib>
            <lib>../../n2sip/lib</lib>
          </include>
          <parameters>
            <parameter name="trace_level" value="1"/>
            <parameter name="trace_per_second" value="20"/>
            <parameter name="edr_enabled" value="1"/>
            <!-- SIP base -->
            <parameter name="sip_proto" value="udp"/>
            <parameter name="sip_host" value="192.168.1.100"/>
            <parameter name="sip_port" value="5061"/>
            <parameter name="sip_public_domain" value="mytelconame.com"/>
            <parameter name="sip_registry_cache" value="/tmp/lho-registry.json"/>
            <parameter name="sip_auth_schema" value="open"/>
            <!-- Local RTP support -->
            <parameter name="rtp_app_name" value="RTP"/>
            <!-- LHO -->
            <parameter name="default_logic_app_name" value="Logic"/>
            <parameter name="default_sigtran_app_name" value="SIGTRAN"/>
          </parameters>
          <config>
            <sip_peers>
              <sip_peer id="srf-group" sip_host="1.2.3.4" sip_port="5064"/>
            </sip_peers>
            <trunks>
              <trunk leading="999" sip_peer_id="srf-group"/>
            </trunks>
            <sip_accounts>
              <sip_account id="LP1" username="665566" password="ABC"/>
              <sip_account id="LP2" username="4000" password="ABC"/>
            </sip_accounts>
            <subscriptions>
              <subscription sip_account_id="LP1" leading="665566"/>
              <subscription sip_account_id="LP2" leading="4000"/>
            </subscriptions>
            <!-- External SRF announcement language maps. -->
            <language_maps>
              <map name="default">
                <language name="English" id="1"/>
                <language name="German" id="2"/>
              </map>
            </language_maps>
            <srfs>
              <srf name="N2IVR" routing_address="9991" language_extension_type="400"/>
            </srfs>
            <trace_traps>
              <trace_trap called_party="901444" trace_level="2"/>
            </trace_traps>
            <normalisation>
              <!-- Normalisation rules -->
            </normalisation>
            <denormalisation>
              <!-- Denormalisation rules -->
            </denormalisation>
          </config>
        </application>
        ...
      </applications>
      ...
    </n2svcd>

Configuration Details

The application element attributes for an LHO SIP Application instance may include the below.

For details of the various parameter types used, refer to Common Configuration.

Parameter Name Type XML Type Description
See: Common Application configuration
See: SIP Application configuration
See: Normalisation and Denormalisation Rules
module String Attribute [Required] LhoSipApp
include.lib String Attribute [Required] ../../n2sip/apps/lho_sip/lib
[Required] ../../n2sip/lib
parameters Array Element Array of name = value Parameters for this Application instance.
"default_logic_app_name" String Attribute The name of the destination Logic Application used for executing our Lua Control Scripts.
(Default = Logic Processing is not available).
"default_sigtran_app_name" String Attribute The name of the destination SIGTRAN Application used for communication with external INAP/CAP SRFs.
The named SIGTRAN application is responsible for assigning and matching Correlation IDs for the inbound AssistRequestInstructions operation.
(Default = INAP/CAP SRFs control is not available).
"sip_ringing_compact" yes / no / 1 / 0 Attribute This parameter enables the supression of redundant "180 Ringing" SIP Response sent back to the A-Leg.
When enabled, consecutive 180 Ringing SIP Responses (without SDP) body will be suppressed, only the first such provisional 180 Ringing response of each sequence will be sent.
(Default = yes suppress duplicate non-SDP "180 Ringing" SIP Response).
"maximum_no_answer" Integer Attribute The maximum NoAnswer timer (in seconds) which service logic may specify.
(Default = 120 seconds).
"leg_change_timer_ms" 100 - 5000 Attribute The maximum duration (in milliseconds) allowed to complete various leg change operations.
This is the allowed duration for joining a new B-Leg back to the A-Leg using re-INVITE.
This is the allowed duration for modifying the A-Leg RTP stream using re-INVITE.
This is the allowed duration for tearing-down a no-longer-required ETC on the B-Leg.
This is the allowed duration for activity test of the A-Leg or B-Leg using re-INVITE.
This process is also bound by the limits of the SIP transaction state/retry timers, however we typically require production network elements to respond within an interval signficantly shorter than the SIP timers.
(Default = 2500 milliseconds).
"service_logic_ms" 10 - 5000 Attribute The limit (integer in milliseconds) for the service logic to respond and give us instructions about how to proceed with call processing during the call set-up or interaction phases.
(Default = 2500 milliseconds).
"correlation_id_ms" 10 - 5000 Attribute The limit (integer in milliseconds) for the SIGTRAN application to provide a correlation ID when one is requested for the purposes of connecting to an INAP-controlled external SRF.
(Default = 1500 milliseconds).
"max_call_secs" 300 - 86400 Attribute The limit (integer in seconds) for the the maximum call duration for a call segment.
(Default = 7200 seconds).
"activity_interval_secs" 0, 5 - 600 Attribute How often (integer in seconds) to supervise the call with an activity test for a connected A-Leg/B-Leg segment.
A value of 0 disables supervision activity testing for non-monitored/non-charged calls.
Activity tests are not sent during internal or external SRF announcement playing.
(Default = 120 seconds).
"default_max_etc_ms" 10 - 5000 Attribute The default maximum (integer in milliseconds) complete interval allowed for setup of the speech path (via SIP) and control path (over INAP/CAP) to an external SRF.
This value can be overridden for each SRF definition in the configuration below.
During this interval, the SIP join of the A-Leg and B-Legs must occur, and the AssistRequestInstructions must be received from the SRF.
(Default = 4000 milliseconds).
"default_tcap_margin_ms" 10 - 5000 Attribute The default maximum (integer in milliseconds) allowance for latency introduced by the TCAP messaging when communicating with an external SRF over INAP/CAP, per announcement.
This value can be overridden for each SRF definition in the configuration below.
This grace margin is added to the maximum interaction timer for each announcement or prompt instruction sent to the SRF.
(Default = 3000 milliseconds).
"default_max_pa_secs" 5 - 3600 Attribute The default maximum (integer in seconds) duration of a single SRF interaction activity (announcement without prompt) operation interaction with an SRF (internal or external).
This value can be overridden for each SRF definition in the configuration below.
This value can be overridden by the service logic for each interaction.
(Default = 300 seconds).
"default_max_pacui_secs" 5 - 3600 Attribute The default maximum (integer in seconds) duration of a single SRF interaction activity (announcement with prompt/collect) operation interaction with an SRF (internal or external).
This value can be overridden for each SRF definition in the configuration below.
This value can be overridden by the service logic for each interaction.
(Default = 300 seconds).
"private_digits" 0 / 1 / yes / no By default, should collected digits be treated as private and masked in PLAYED EDRs?
(Default = 0, not masked).
"internal_cancel_digit" [A-E*#] Attribute The digit that is treated as cancel input when performing DTMF or RTP Event collection using the internal resource.
The service-logic may override this per-interaction or may cancel the default by specifying UNDEF in service logic.
(Default = no cancel-input digit is applied by default for internal interactions)
"internal_end_digit" [A-E*#] Attribute The digit that is treated as end of input when performing DTMF or RTP Event collection using the internal resource.
The service-logic may override this per-interaction or may cancel the default by specifying UNDEF in service logic.
(Default = no end-of-input digit is applied by default for internal interactions)
config Object Element Container for extended configuration for this Application instance.
.language_maps Array Element Array of map elements defining language name maps used for external SRF communication.
.map Array Element Array of language elements defining a language name map used for external SRF communication.
.language Object Element Defines a single name mapping within a language name map used for external SRF communication.
.srfs Array Element Array of srf elements defining external SRF definitions.
.srf Object Element Defines an external SRF.
The internal media server is not configured in this list.

Language Map Entries

Each language map entry definition maps a language name to an external ID in the context of a language map, for the purpose of mapping Name to numeric ID when controlling an external SRF. These mappings are not used when communicating with the internal (local) RTP resource.

Names must be unique within the map.

Each language Object in a config.language_maps.map Array is configured as follows.

Parameter Name Type XML Type Description
name String Attribute [Required] The name of the language mapped by this language map entry.
id Integer Attribute [Required] The ID used when representing this language to an external SRF via this map.
Note that ID values do not need to be unique within this map.

SRFs

Each SRF definition defines a known external SRF media server which may be referenced by the service logic when it requests an interaction be performed.

There is no “default” external SRF. If the service logic does not specify an SRF name for an interaction, then the internal media server will be used, if configured.

Names must be unique.

Each srf Object in the config.srfs Array is configured as follows.

Parameter Name Type XML Type Description
name String Attribute [Required] Unique name for this SRF.
routing_address Hex Digits Attribute [Required] Defines the prefix of the routing address when constructing the B-Leg to connect to the SRF.
The correlation ID may be appended to this address. Refer to correlation_id_location.
This routing address is used to determine an outbound trunk group, which will then determine the SIP IP and port, and the SIP host name used to construct the "To" address header for that B-Leg SIP INVITE.
from_otg String Attribute A value to set as the otg parameter of the URI address in the From header for ETC B-Leg established to this SRF.
(Default = do not add any otg parameter to the B-Leg From URI).
to_dtg String Attribute A value to set as the dtg parameter of the URI address in the To header for ETC B-Leg established to this SRF.
(Default = do not add any dtg parameter to the B-Leg To URI).
star_digit A - F Attribute Used when the service logic communicates with an external SRF over INAP.
If the service logic or default configuration specifies the * character as an end-of-input or cancel character, then this value will be used instead as the on-the-wire value in the INAP endOfReplyDigit or cancelDigit.
(Default = B).
hash_digit A - F Attribute Used when the service logic communicates with an external SRF over INAP.
If the service logic or default configuration specifies the # character as an end-of-input or cancel character, then this value will be used instead as the on-the-wire value in the INAP endOfReplyDigit or cancelDigit field.
(Default = C).
cancel_digit A - F / * / # Attribute Used when the service logic communicates with an external SRF over INAP.
Specify the cancel digit to pass in the INAP cancelDigit field, if not specified by the service logic.
(Default = none, do not indicated a preferred cancel digit to the SRF).
end_digit A - F / * / # Attribute Used when the service logic communicates with an external SRF over INAP.
Specify the end-of-input digit to pass in the INAP endOfReplyDigit field, if not specified by the service logic.
(Default = none, do not indicated a preferred end-of-input digit to the SRF).
correlation_id_location routing_address / standalone Attribute Used when the service logic communicates with an external SRF over INAP.
Specify how the correlation ID digits are passed to the SRF within the SIP INVITE.
routing_address - Append the digits to the routing address.
standalone - Place the digits into a header named CorrelationID within the SIP INVITE.
(Default = routing_address).
tcap_close prearranged / end / abort Attribute Used when the service logic communicates with an external SRF over INAP.
Specify how the TCAP dialog to the SRF is ended once it is no longer required by service logic.
prearranged - Pre-arranged TCAP END. No message is put on the wire.
end - An empty TCAP END is sent.
abort - A TCAP ABORT is sent.
(Default = prearranged).
language_mechanism nap Attribute Used when the service logic communicates with an external SRF over INAP.
Specify how the language identifier (mapped from the service logic language name) is indicated to the SRF.
nap - Use the "NAP" encoding as described in the "N2IVR INAP Conformance" documentation.
(Default = nap if language_extension_id is defined, otherwise do not send language ID).
language_extension_id Integer Attribute Used when the service logic communicates with an external SRF over INAP.
If defined, then when sending INAP/CAP PlayAnnouncement and PromptAndCollectUserInformation operations, add an INAP extension with this numeric Type ID. The extension payload contains an integer language ID value which is mapped to determine the preferred language name for announcement message ID mapping and for variable parts.
The binary encoding of this extension is defined in the "N2IVR INAP Conformance" document.
(Default = do not send language ID).
max_etc_ms 10 - 5000 Attribute Set the limit (in integer milliseconds) for the timeout when performing leg setup for this SRF.
See the notes for the global configuration of default_max_etc_ms.
(Default = use the configured default_max_etc_ms).
tcap_margin_ms 10 - 5000 Attribute Set the allowance (in integer milliseconds) for TCAP latency when performing interactions for this SRF.
See the notes for the global configuration of default_tcap_margin_ms.
(Default = use the configured default_tcap_margin_ms).
max_pa_secs 10 - 5000 Attribute Set the maximum (in integer seconds) maximum non-prompt interaction duration for SRF.
See the notes for the global configuration of default_max_pa_secs.
A value specified by the service logic will take precedence over the SRF and global default.
(Default = use the configured default_max_pa_secs).
max_pacui_secs 10 - 5000 Attribute Set the maximum (in integer seconds) maximum prompting interaction duration for SRF.
See the notes for the global configuration of default_max_pacui_secs.
A value specified by the service logic will take precedence over the SRF and global default.
(Default = use the configured default_max_pacui_secs).

Message Handling

The LhoSipApp uses the following messages: