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>
        ...
      </applications>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

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.

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:

• Invalid input parameters supplied by Lua script.
• Unexpected results structure returned from LhoSipApp.
• Processing error occurred at LhoSipApp.
• Timeout occurred when waiting for the LhoSipApp response.

.establish_new_call [Asynchronous]

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

The establish_new_call method returns a Lua table with the following attributes.

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

• The outcall attempt is unacceptable and cannot be processed.
• No SIP Route is available towards the indicated called party.
• A SIP INVITE Final Response with code 300-699 (not answered) is received.
• A SIP INVITE Final Response with code 200-299 (answered) is received.
• An unacceptable SIP INVITE Provisional or Final Response is received.
• The No Answer time expires before a SIP INVITE Final Response is received.

Example:

    local result = sip_outcall.establish_new_call ({ calling_party = "7000", called_party = "100123", is_calling_restricted = true })
    if (not result.answered) then
        return "NOT ANSWERED .. " . result.reason
    end

.outcall [Asynchronous]

This helper method provides a simplified flattened-argument version of the establish_new_call method.

The outcall method takes the following arguments:

The outcall method returns the same table structure as establish_new_call.

Example:

    local result = sip_outcall.outcall ("7000", "100123")
    if (not result.answered) 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 INAP.

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.