SIP Outcall Lua Agent

LhoSipOutcallLuaAgent Module

Introduction

The LhoSipOutcallLuaAgent is an asynchronous helper for LUA scripts running within the LogicApp. It is used for initiating an outbound SIP call A-Leg. This agent will send an outbound SIP INVITE Request to open an A-Leg and then will allow interaction and B-Leg termination in the same manner as supported for inbound A-Legs.

For handling inbound SIP A-Leg calls you need to use the LhoSipIncallLuaService

The LhoSipOutcallLuaAgent communicates with one or more instances of the LhoSipApp which can be used to perform outcalls to external SIP UAC or SIP Gateways.

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

The LhoSipOutcallLuaAgent is tied to the outcall action key.

Configuring LhoSipOutcallLuaAgent

The LhoSipOutcallLuaAgent 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>
            ...
            <parameter name="default_sip_outcall_app_name" value="LHO-SIP"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="LhoSipApp::LhoSipOutcallLuaAgent" libs="../../n2sip/apps/lho_sip/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

Attribute Type XML Type Description
module LhoSipApp::LhoSipOutcallLuaAgent Attribute [Required] The module name containing the LUA Agent code.
libs ../../n2sip/apps/lho_sip/lib Element Location of the module for LhoSipOutcallLuaAgent.
default_no_answer_secs Integer Attribute The default number of seconds to wait for No Answer on the A-Leg outcall 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).

In addition, the LhoSipOutcallLuaAgent must be configured with the name of the LhoSipApp with which it will communicate. This is configured within the parameters of the containing LogicApp.

Attribute Type Description
parameters Array Array of name = value Parameters for this Application instance.
.default_sip_outcall_app_name String Default name for the LhoSipApp to which LhoSipOutcallLuaAgent will send the request for initiating the outbound A-Leg out SIP INVITE Request.

Invoking LhoSipOutcallLuaAgent

A LUA Script can access the LhoSipOutcallLuaAgent outcall action with code such as the following.

In this example, the Lua script performing the outcall has been started as the result of receiving an inbound REST Request (via the RestLuaService). In practice, any Lua Script may use the outcall agent, independent of how the Lua script itself was initiated.

local n2svcd = require "n2.n2svcd"
local rest_service = require "n2.n2svcd.rest_service"
local sip_outcall_agent = require "n2.n2svcd.sip_outcall_agent"

local rest = ...

if (type (rest.query_args) ~= 'table') then
    error ("Missing REST Query Args for SIP Outcall")
end

local calling_party = rest.query_args.calling_party
local called_party = rest.query_args.called_party

local result = sip_outcall_agent.outcall (calling_party, called_party)
if (not result.controlled) then
    return result.reason
end

-- We're going to return now, before the REST Server gives up on us.
rest_service.response ("ANSWERED")

result = sip_outcall_agent.rtp_interaction ({ message_id = 25046, variables = { { number_digits = "1234" } } })
if (not result.controlled) then
    return nil
end

sip_outcall_agent.hangup ()

return

This is standard LUA-style library usage. The n2/n2svcd/sip_outcall_agent.lua library is loaded with require "n2.n2svcd.sip_outcall_agent". Then methods are invoked on the returned library object.

The LhoSipOutcallLuaAgent API

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

.outcall [Asynchronous]

The outcall method initiates an outbound A-Leg SIP INVITE Request. The method parameters are:

Field Type Description
calling_party Hex&String Calling Party address digits.
These will be set as the "user" part of the From header URI.
called_party Hex&String Called Party address digits.
These will be set as the "user" part of the To header URI.
no_answer_timeout Integer The No Answer timeout (in seconds) which will be used for this call attempt.
If no final SIP INVITE Response (code 200-699) is received within this time, then SIP CANCEL will be sent.

The outcall method returns an result object with the following attributes.

The outcall attempt will return to the Lua service logic only when one of the following conditions is met:

Attribute Type Description
.controlled Boolean [Required] Is this call under control of the service logic.
This field will be true if and only if the corresponding answered field is true.
.answered Boolean [Required] Was this call answered.
This value being true indicates that the A-Leg outbound attempt received a SIP INVITE Response containing an acceptable "success" final response value, i.e. typically 200 OK.
Receipt of a provisional SIP INVITE Response value is never considered an "answered" call, even if it contains early media.
.code Integer An SIP Response final code in the range 200-699 associated with the A-Leg outcall attempt.
This value is present only when the B-Leg outcall attempt received a final SIP INVITE Response code.
.reason No Route / Declined / No Answer / Answered [Required] A descriptive string for how the outcall attempt ended.

Example:

    local result = sip_outcall.outcall ("7000", "100123")
    if (not result.connected) then
        return "NOT ANSWERED .. " . result.reason
    end

Hangup

Once the outcall is connected to the A-Party, Hangup can be performed as described for the SIP Incall Lua Service / Hangup.

Note that hangup of an outcall A-Leg is always performed using BYE.

Interaction (Internal RTP)

Once the outcall is connected to the A-Party, Internal RTP Interaction can be performed as described for the SIP Incall Lua Service / Interaction RTP.

Internal RTP Interaction refers to interaction which is performed using a co-located, on-platform RTP media server via the RtpApp.

Interaction (External INAP)

Once the outcall is connected to the A-Party, External INAP Interaction can be performed as described for the SIP Incall Lua Service / Interaction RTP.

External INAP Interaction refers to interaction which is performed by opening a B-Leg to an off-platform, independent INAP-Controlled IVR platform.

Termination (Attempt)

Once the outcall is connected to the A-Party, Termination (Attempt) can be performed as described for the SIP Incall Lua Service / Termination (Attempt).

Charged and Monitored Terminations are fully supported.