Navigation :

SCC Outcall Lua Agent

SccOutcallLuaAgent Module

Introduction

The SccOutcallLuaAgent is an asynchronous helper for LUA scripts running within the LogicApp. It is used for initiating an outbound SIP call. For handling inbound SIP calls you need to use the LhoSipIncallLuaService

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

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

The SccOutcallLuaAgent is tied to the outcall action key.

Configuring SccOutcallLuaAgent

The SccOutcallLuaAgent 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_outcall_app_name" value="SCC-APP"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="LhoSipApp::SccOutcallLuaAgent" libs="../apps/scc/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

Attribute	Type	Description
`module`	`LhoSipApp::SccOutcallLuaAgent`	[Required] The module name containing the LUA Agent code.
`libs`	`../apps/scc/lib`	Location of the `module` for SccOutcallLuaAgent.

In addition, the SccOutcallLuaAgent 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_outcall_app_name`	String	Default name for the LhoSipApp with which SccOutcallLuaAgent will communicate when performing SIP outcalls.

Invoking SccOutcallLuaAgent

A LUA Script can access the SccOutcallLuaAgent outcall action with code such as the following:

local n2svcd = require "n2.n2svcd"
local scc_api = require "n2.n2svcd.scc_outcall"

local rest = ...

local result = scc_api.callout ("7000", "100123")
if (not result.connected) then
    return "NOT ANSWERED"
end

result = scc_api.play_announcement (25046, { { number_digits = "1234" } })
if (not result.connected) then
    return "ABANDONED"
end

scc_api.hangup ()

return "COMPLETED INTERACTION"

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

The SccOutcallLuaAgent 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 at LhoSipApp.

.callout [Asynchronous]

The callout method initiates an outbound SIP INVITE. The method parameters are:

Field	Type	Description
`calling_party`	Hex&String	Calling Party address digits. These will become the part of the `From` address before the `@` character.
`called_party`	Hex&String	Called Party address digits. These will become the part of the `To` address before the `@` character.

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

Parameter	Type	Description
`result`	Object	Container for information about the outcall attempt.
`.language`	String	Default SCC Language Name. The name of the language e.g. `English` configured for default interpretation of announcement IDs and variable part construction.
`.code`	Integer	The SIP Response code for the INVITE, if one was received. If the SIP INVITE timer expired before response then this will be `nil`.
`.connected`	Boolean	Is the call connected and ready for A-LEG Audio? i.e. did the called-party accept the INVITE?
`.rsf`	Boolean	This is `true` if the call failed because we had no active trunk group.
`.noanswer`	String	[Required iff `connected` = `false`] No answer reason string. e.g. "Route Select Fail", "NoAnswer SIP Code = 404", "NoAnswer SIP Timeout".

Example:

    local result = scc_api.callout ("7000", "100123")
    if (not result.connected) then
        return "NOT ANSWERED .. " . result.noanswer
    end

Hangup

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

Interaction

Once the outcall is connected to the A-Part, Interaction can be performed as described for the SCC Incall Lua Service / Interaction.

Termination (Attempt)

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