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:
- 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.
.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:
- The outcall attempt is unacceptable and cannot be processed.
- No SIP Route is available towards the indicated called party number.
- A SIP INVITE Response with final code 300-699 (not answered).
- A SIP INVITE Response with final code 200-299 (answered).
- An unacceptable SIP INVITE Response (final or non-final) is received.
- The No Answer time expires before a SIP INVITE Response with final code is received.
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.