Decline
Introduction
An Incall LUA script may decline the incall attempt, i.e. request that a final SIP INVITE
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:
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 final result is sent for the INVITE.
Any of the following service logic actions will cause a final response to be sent, meaning
that the decline method is not longer applicable.
- Attempting to terminate a B-Leg.
- Playing announcement using an external SRP.
- Playing announcement using an internal SRP, unless
183 Early Mediawas used.
If the service logic has played an announcement, but not attempted to terminate a B-Leg,
then it should examine the decline_ok attribute of the announcement method result value
to determine if decline 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 final SIP status code in the range 3xx-6xx for the A-Leg final
SIP INVITE Response sent by us.
Note that Authentication 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
|
300-699
|
SIP response code to return in the A-Leg final SIP Response. (Default = 603)
|
reason
|
Object |
This is a container for specifying extended information in the SIP response Reason
header of the SIP final response or of the SIP BYE request, depending on which is used.(Default = SIP response does not contain Reason header)
|
.protocol
|
SIP/Q.850
|
The protocol to which this reason belongs. (Default = SIP)
|
.value
|
Integer |
[Required] A numeric Reason value code.
|
.text
|
String |
A text Reason.(Default = Terminated)
|
extra_headers
|
Table |
Requests that custom extra headers be set on the SIP INVITE Final 300-699 Response. Each value in this table must be a SCALAR value, or an ARRAY of SCALAR values. (Default = Do not add any service-logic header values to the SIP Final 300-699 Response.) |
The decline method returns true.
Note that the hangup 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"
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"
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
codeis always302. - A new called party will be placed in the
Contactheader 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] An alternate contact digits to specify in the Contact header.This is only the digits part with optional leading +.
|
The redirect method returns true.
Note that the hangup 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"
local scc = ...
incall_api.redirect ("00645559999")
return