Navigation :

Decline

Introduction

An Incall Lua script may decline the incall attempt, i.e. request that a SIP INVITE Final Response be sent with code in the range 300-699.

This is done using the decline method. A convenience redirect method is also provided for the common redirection case.

Here is the overall flow for this declined case:

SCC Message Flow (Incall, Declined)

The “Post-Call Notification” shown in this flow is given purely as an example of supplementary functionality, but is not at all intrinsic to the flow.

Note that the decline method can only be used before the SIP INVITE Final Response is sent.

Any of the following service logic actions can potentially cause a Final Response to be sent on the A-Leg, meaning that the decline method is no longer applicable.

Attempting to terminate a B-Leg.
Playing an announcement using a configured external SRF.
Playing an announcement using the internal RTP media server (if enabled).

The service logic should examine the decline_ok attribute returned by the methods associated with proceeding, interaction, and termination to determine if decline or redirect can still be used.

If not, the service logic should use hangup to expressly end the call.

The LhoSipIncallLuaService Decline API

.decline [Synchronous]

The decline method allows control of the A-Leg SIP INVITE Final Response code.

Note that Authentication Response codes 401 and 403 are handled internally by the LhoSipApp, and the service logic does not need to (and should not) use this method to perform authentication checks.

The decline method takes the following arguments:

Attribute	Type	Description
`code`	Integer	The code to send in the SIP INVITE Final Response. The code must be in the range `300-699`. (Default = `603` or other platform-configured default value).
`reason`	Table	This is a container for specifying the details for a `Reason` header. The header will be included in the SIP INVITE Final Response. (Default = do not include a `Reason` header).
`.protocol`	`SIP`/`Q.850`	The protocol value to include in the `Reason` header. (Default = `SIP`).
`.cause`	Integer	The cause parameter value to include in the `Reason` header. (Default = do not include a `cause` parameter in the header).
`.text`	String	The text parameter value to include in the `Reason` header. (Default = do not include a `text` parameter in the header).
`extra_headers`	Table	Additional user headers to include in the SIP INVITE Final Response. The table keys are header names. The table values are tables of header values. (Default = do not add extra user headers).

The decline method returns true.

Note that the decline method will pass the processing request off to the controlling LhoSipApp (using the SCC-DO-ALEG-DECLINE-FINAL message) and then will immediately (synchronously) return back to Lua script control, without waiting to confirm the result of the SIP transaction state change.

Example (decline with 604 Does Not Exist Anywhere, with a prior 180 Ringing):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

local scc = ...

incall_api.ringing ()
incall_api.decline (604, nil)

return

Example (returning a Q.850 Cause 16):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

local scc = ...

incall_api.decline (487, { protocol = "Q.850", value = 16, text = 'Normal Call Teardown' })

return

.redirect [Synchronous]

The redirect method is a special-case convenience method which is identical to the decline case in terms of message flow, but which has two specific differences:

The code is always 302.
A new called party will be placed in the Contact header in the SIP INVITE Response.

Otherwise, all other comments and limitations relevant to decline also apply for redirect.

The redirect method takes the following arguments:

Attribute	Type	Description
`contact_user`	(+)Hex String	[Required] The digits identifying an alternate contact, to include in the SIP INVITE Final Response `Contact` header. The protocol and domain parts of the address will be determined automatically.

The redirect method returns true.

Note that the redirect method will pass the processing request off to the controlling LhoSipApp (using the SCC-DO-ALEG-DECLINE-FINAL message) and then will immediately (synchronously) return back to Lua script control, without waiting to confirm the result of the SIP transaction state change.

Example (redirect to 00645559999):

local n2svcd = require "n2.n2svcd"
local incall_api = require "n2.n2svcd.sip_incall_service"

local scc = ...

incall_api.redirect ("00645559999")

return