☰
Navigation :

SCC Messages

Introduction

The SIP Logic Hand-Off Application (LhoSipApp) uses SCC-... messages for SIP call control. These messages are transmitted over the n2svcd message bus between the LHO SIP Application (LhoSipApp) and the Logic Application (LogicApp).

The start of the message sequence is slightly different between incall and outcall scenarios:

However once the call is established then the subsequent SCC-... messages are identical.

The SCC-... message names are divided into two categories depending on which direction the message is flowing.

a. SCC-HANDLE-... messages from LhoSipApp to LogicApp to request service logic assistance.
b. SCC-DO-... messages from LogicApp to LhoSipApp to perform service logic actions.

SIP Incall Messages

Initiated by LhoSipApp by sending SCC-HANDLE-ALEG-INBOUND-INVITE to LogicApp.

Handled by LhoSipLuaService which selects the Lua script to execute.

The internal messages used between LhoSipApp and LogicApp during incall setup are:

…plus the common messages.

Here is an example internal n2svcd message flow for the incall scenario with interaction, where the RTP stream for the interaction is generated by an internal Media Server (an instance of the RtpApp), not from an external SRF.

SCC Message Flow (Out-Call)

SIP Out-Call Messages

Initiated by LogicApp from an already-running Lua script. That Lua script must be initiated by some other mechanism, e.g. an inbound REST request.

The internal messages used between LhoSipApp and LogicApp during outcall setup are:

…plus the common messages.

Here is an example internal n2svcd message flow for the outcall scenario with interaction, where the RTP stream for the interaction is generated by an internal Media Server (an instance of the RtpApp), not from an external SRF.

SCC Message Flow (Out-Call)

SIP Common Messages

The following messages are common to both incall and outcall.

SCC-DO-ALEG-OUTBOUND-INVITE

The SCC-DO-ALEG-OUTBOUND-INVITE instructs the LhoSipApp to initiate an outbound A-Leg INVITE. This message is sent by the LhoSipOutcallLuaAgent.

This message will cause a new LhoSipInstance instance to be created, which initially has no leg control. The instance will begin a new outbound INVITE attempt associated with the A-Leg, and will return back to the service logic once the status of that A-Leg SIP INVITE Request attempt is known.

If the A-Leg outbound SIP INVITE Request attempt fails, then the response back to LhoSipOutcallLuaAgent will be SCC-HANDLE-ALEG-FAILURE-FINAL and no further messages can occur in relation to that LhoSipInstance.

Note: In some unexpected error scenarios, the SCC-HANDLE-SHUTDOWN message may be used instead of SCC-HANDLE-ALEG-FAILURE-FINAL.

If the A-Leg attempt succeeds, then the response message will be SCC-HANDLE-ALEG-ANSWER-ONGOING, and the service logic may proceed to process the call control in a manner essentially identical to the incall scenario where an inbound SIP INVITE Request caused SCC-HANDLE-ALEG-INBOUND-INVITE to be sent to the LogicApp and is handled by the LhoSipIncallLuaService.

I.e. Once the outbound A-Leg is established the service logic may attempt to:

The attributes of the SCC-DO-ALEG-OUTBOUND-INVITE message are:

Field Type Description
scc Object [Required] The SIP call control parameters for the standalone outcall A-Leg.
.no_answer_timeout Integer Specify how long the INVITE will be permitted to try before we CANCEL.
(Default = a system-configured default value).
.calling_party (+)Hex String [Required] Calling Party address digits.
This will be used to construct the From header in the outbound SIP INVITE Request.
Depending on configuration, this may help determine the outbound SIP trunk on which the SIP INVITE Request is set.
It must contain only 0-9A-F digits.
.called_party (+)Hex String [Required] Called Party address digits.
This will be used to construct the To header in the outbound SIP INVITE Request.
This is nearly always used to determine the outbound SIP trunk on which the SIP INVITE Request is set.
It must contain only 0-9A-F digits.
.extra_headers Object Additional user headers to add for this outbound A-Leg SIP INVITE.
The object key is the header name.
The object value is an array of header values.
(Default = do not add extra outbound SIP INVITE user headers).

SCC-HANDLE-ALEG-FAILURE-FINAL

The SCC-HANDLE-ALEG-FAILURE-FINAL is sent by the LhoSipApp to the LhoSipOutcallLuaAgent to inform it that the attempt to perform an outbound A-Leg SIP INVITE (outcall) has not been successful.

This can occur when:

I.e. No SIP Response at all was received from the far-end within the SIP state machine timer, and/or service logic No Answer timer.

I.e. A 100 Trying and/or 1xx Provisional SIP INVITE Response was received, but no final 2xx or 300-699 SIP INVITE Response was received.

This message indicates that the LHO SIP Instance is over, and no more messages should be sent by the service logic.

The attributes of the SCC-HANDLE-ALEG-FAILURE-FINAL message are:

Field Type Description
scc Object [Required] The SIP call control parameters for the standalone outcall A-Leg.
.reason "No Answer" / "No Route" / "Declined" [Required] The reason why the A-Leg could not be established.
.code 300 - 699 The received final SIP INVITE Response code, if one was received.

SCC-HANDLE-ALEG-ANSWER-ONGOING

The SCC-HANDLE-ALEG-ANSWER-ONGOING is sent by the LhoSipApp to the LhoSipOutcallLuaAgent to inform it that the attempt to perform an outbound A-Leg SIP INVITE (outcall) was successful due to the receipt of an acceptable “200 OK” SIP INVITE Response.

The service logic must provide subsequent call control instructions, using the same SCC messages as would be applicable following the receipt of SCC-HANDLE-ALEG-INBOUND-INVITE except that neither SCC-DO-ALEG-PROCEEDING nor SCC-DO-ALEG-DECLINE-FINAL may be sent by the service logic in relation to an A-Leg which was established using outcall.

The attributes of the SCC-HANDLE-ALEG-ANSWER-ONGOING message are:

Field Type Description
scc Object [Required] The SIP call control parameters for the standalone outcall A-Leg.
.code 200 - 299 The final SIP INVITE Response code that was received.
By default LhoSipApp will only accept 200 as a permitted response code.

SCC-DO-ALEG-PROCEEDING

The SCC-DO-ALEG-PROCEEDING instructs the LhoSipApp to send a 1XX Proceeding Response, and optionally to refresh the service logic wait timer.

This can only be sent if the inbound INVITE has not yet been sent a final response. Any of the following service logic actions may cause a final response to be sent:

In some message flow scenarios, it is necessary to check the decline_ok attribute of the message received from the LhoSipApp to determine if the SCC-DO-ALEG-PROCEEDING message may be sent.

For example, the SCC-HANDLE-ALEG-INTERACTION-COMPLETE-ONGOING and SCC-HANDLE-BLEG-TEARDOWN-ONGOING messages indicate that the call is still controlled, but may or may not allow for a decline or proceeding operation to be performed.

Note that the this SCC-DO-ALEG-PROCEEDING message should not (and may not) be used for sending a 100 Trying provisional response. The sending of 100 Trying is performed entirely automatically by the underlying framework and is not user-controlled.

After sending this message, the service logic should send no further messages until it receives one of the following messages from the LhoSipApp:

The attributes of the SCC-DO-ALEG-PROCEEDING message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.code Integer [Required] Proceeding status code to return in the range 100-199.
.seconds Integer The number of seconds from now to refresh the service logic timer.
(Default = do not refresh the service logic timer)

Note that the initial service logic timer is defined in milliseconds, but the refresh timer value (if present) is specified in seconds.

SCC-DO-ALEG-DECLINE-FINAL

The SCC-DO-ALEG-DECLINE-FINAL instructs the LhoSipApp to end the call.

This can only be sent if the inbound INVITE has not yet been sent a final response. Any of the following service logic actions may cause a final response to be sent:

The decline_ok flag of the SCC-HANDLE-ALEG-INTERACTION-COMPLETE-ONGOING message indicates if it is still possible to decline the call after a pre-call announcement – i.e. that we are still in the early media phase.

If this flag is true, then the service logic may use SCC-DO-ALEG-DECLINE-FINAL following a pre-call announcement. Otherwise SCC-DO-ALEG-HANGUP-FINAL must be used instead.

The decline message allows control of final SIP status code in the range 3xx-6xx. When using SIP status code 302 Moved Temporarily with an alternate called_party place in the response Contact address.

In any case we can also request an optional 180 Ringing provisional response to be sent directly before the final response.

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 attributes of the SCC-DO-ALEG-DECLINE-FINAL message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.code Integer Status code to return in the range 300-699.
(Default = 603 or other platform-configured default value)
.contact_user (+)Hex String An alternate contact digits to specify in the Contact header.
This should be hex digits with optional leading +.
This is typically only used when code = 302.
(Default = do not specify the Contact header in the final response)
.reason Object An Object defining the contents of a Reason header.
.protocol SIP/Q.850 The protocol of the value in the reason.
(Default = SIP)
.value Integer A release cause value to include in the reason header.
.text String The text to supply with the reason.
(Default = Terminated)

SCC-DO-ALEG-HANGUP-FINAL

The SCC-DO-ALEG-HANGUP-FINAL instructs the LhoSipApp to end the call by terminating the A-Leg. The code and reason parameters define additional information which is used in the teardown of the A-Leg only.

The A-Leg teardown will be performed by:

If a B-Leg is present then a teardown will be performed using SIP BYE or SIP CANCEL as appropriate, using default parameters.

The attributes of the SCC-DO-ALEG-HANGUP-FINAL message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.code Integer Status code to return in the range 300-699 for the SIP INVITE Response.
This value is only used in the case where the A-Leg is an inbound SIP INVITE which is still Proceeding.
(Default = 603 or other platform-configured default value)
.reason Object An Object defining the contents of a Reason header.
This Reason will be included in either the SIP INVITE Final Response message sent for the A-Leg (if the A-Leg INVITE transaction was an inbound request which is still Proceeding) or in the SIP BYE Request sent for the A-Leg.
.protocol SIP/Q.850 The protocol of the value in the reason.
(Default = SIP)
.value Integer A release cause value to include in the reason header.
.text String The text to supply with the reason.
(Default = Terminated)

SCC-DO-ALEG-INTERACTION-INTERNAL

The SCC-DO-ALEG-INTERACTION-INTERNAL message is sent by the LogicApp to the LhoSipApp to request the local framework to provide a local RTP endpoint (via SDP in SIP) for the purposes of streaming RTP audio packets to the one leg of the call currently under control. I.e. when we want to invoke the on-node media server resident within our executing framework.

The supported model is:

After sending this message, the service logic should send no further messages until it receives one of the following messages from the LhoSipApp:

Note that the first time this message is sent, the framework will allocate RTP port(s) and will perform the SIP messaging on the A-Leg for the SDP negotiation related to our local RTP endpoint. The RTP negotiation may include:

These are in fact the same standard options which would apply for a back-to-back user agent connection to an external B-Leg, although in this case the B-Leg is us acting as an RTP endpoint to generate audio.

Refer to the N2SIP Protocol Conformance Statement for a more thorough description of the supported SDP exchange mechanisms with specific reference to RFC 6337.

If there is currently a temporary B-Leg connection active for the purpose of performing announcements with an external media server, then the framework will terminate the in-progress external announcement channel and then proceed to setup of the internal on-node RTP media session.

If there is currently a B-Leg end-to-end call in progress, then this message will be rejected, i.e. it is not permitted to use this internal announcement mechanism while a monitored or charged call is currently in progress. The service logic must explicitly end the B-Leg end-to-end call, or wait for it to be terminated by one of the parties.

After this announcement is complete (either because it played to the end of message, or because it was interrupted by user input) then the established RTP audio channel will remain established in the anticipation of subsequent announcements using the same on-node RTP audio media server resources.

The RTP channel will be automatically ended if the subsequent action is an action which does not use it - e.g. the call is ended, or a request is made to establish an call to a B-Leg, or to establish a temporary B-Leg connection for the purpose of playing announcements using an external media server.

Note: This message can be sent with no announcement information, in which case the RTP audio channel will be established by SDP exchange (as described above) but the audio will not yet start streaming.

This is useful for IVR implementations, where the desired behavior is:

  1. Receive inbound SIP INVITE for the purpose of being an IVR under external control.
  2. Establish RTP channel (send SCC-DO-ALEG-INTERACTION-INTERNAL without announcement details).
  3. Notify the external controller that we are ready for instructions (e.g. by sending INAP AssistRequestInstructions).
  4. Wait for interaction instructions (e.g. by receiving INAP PlayAnnouncement).
  5. Execute the interaction instructions (using SCC-DO-ALEG-INTERACTION-INTERNAL with announcement details).
  6. Return the result of instructions (e.g. by sending INAP SpecializedResourceReport).
  7. Go to step 4.

Note that in the just-described case, we are the media server, operating under locally-implemented service logic control, or under external control from another node. This is the reverse of the situation where we are using SCC-DO-ALEG-INTERACTION-EXTERNAL and we are acting as the controller, controlling an external media server.

The attributes of the SCC-DO-ALEG-INTERACTION-INTERNAL message are:

Field Type Description
scc Object [Required] The detailed control parameters for the interaction.
.early_media require / prefer / allow / never Specify if this interaction should use "183 Early Media" instead of "200 OK".
Note that when performing multiple internal media server interactions in sequence, this parameter is only relevant for the first interaction in that sequence – any subsequent interactions using the same internal media server connection will silently ignore this parameter.
require - This interaction must use Early Media, or generate a run-time script error.
prefer - This interaction should use Early Media, if allowed by the SIP layer.
allow - This interaction may use Early Media, if preferred by the SIP layer.
never - This interaction must never use Early Media, regardless of SIP layer preferences.
(Default = allow)
.aleg_headers Object This is a map of custom SIP headers to include in the SIP INVITE Response sent to the A-Leg when establishing the RTP channel. The Object attributes are the header key names, and the Object values must be either a simple String or an Array of simple String values.
The header key names must not include reserved, special SIP header names, this functionality is for adding custom header values only.
(Default = Do not add any service logic custom headers to the SIP INVITE Response)
.announcement Object Container for the attributes of the announcement to be constructed and streamed.
This structure is passed through (with potential modifications as indicated) into the RTP-PLAY message sent to the RtpApp.
(Default = Establish RTP but do not begin streaming)
.message_id Integer A single message ID to play.
This ID must be configured within the RtpApp database or file-based configuration.
The definition of this ID may depend on the specified language, and the definition may allow multiple audio file fragements and/or one or more variable parts.
Specify exactly one of .message_id or .message_ids or .files.
.message_ids Array of Integer An array of one or more message IDs to play in sequence.
Each ID listed here must be configured within the RtpApp database or file-based configuration.
The definition of each ID may depend on the specified language, and the definition may allow multiple audio file fragements and/or one or more variable parts.
Each ID listed here may contain variable parts. The supplied variable parts list must contain sufficient variable parts for all message IDs.
Specify exactly one of .message_id or .message_ids or .files.
.files Array of String Explicit Array of one or more filenames to play in sequence. Specifying this parameter will bypass the message ID translation process in RtpApp and allows the service logic to explicitly control the audio file fragments to be streamed.
All filenames must be from the announcement language, it is not possible to override the language per-fragment.
Each filename must not include the audio file type suffix part e.g. must not contain the .ul, or .amr.
Each filename must include the subdirectory announcements or variable_parts.
The directory name "a" is a supported abbreviation for "announcements".
The directory name "vp" or "v" is a supported abbreviation for "variable_parts".
Example files list: [ 'a/You_Entered', 'v/1', 'vp/4' ].
.language String Optional language name to use instead of the default value configured within the RtpApp.
The RtpApp will use this when mapping announcement ID/IDs into a file list.
The RtpApp will use this expanding variable parts into audio file fragments.
This language name must be configured within the RtpApp database or file-based configuration.
Refer to the RtpApp configuration documentation.
(Default = The default language configured in the RtpApp)
.repetition Positive Integer A requested repetition count, the announcement will be repeated up to the indicated number of times.
(Default = Play the announcement list only once).
.duration Positive Integer The total permitted duration of the interaction including repetitions and any silence.
(Default = the configured rtp_max_play_secs for the SipApp).
.variables Array of Object An array of variable values to substitute into pre-defined placeholders in the message structure.
Each variable part is an object which specifies exactly one of the attributes as follows.
.integer Integer An integer value to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.number_digits Integer An integer value to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.time_hhmm <HHMM> An integer hour and minute to speak as a variable part.
Value is in the range 0000-2400.
Construction rules for the chosen/default langage will be used.
.date_yymmdd <YYMMDD> A 6-digit integer year/month/day to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.date_yyyymmdd <YYYYMMDD> An 8-digit integer year/month/day to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.price_digits Integer An integer value of "cents" to speak as a variable part.
Construction rules for the chosen/default langage will be used.
.collect Object Container for information related to digit collection.
Digit collection will be performed if and only if this container element is present.
(Default = do not collect user input digits).
.min_num_digits 1 - 32 The minimum number of digits which the internal Media Server will be instructed to collect.
[Required] This value is required when collect is specified.
.max_num_digits 1 - 32 The maximum number of digits which the internal Media Server will be instructed to collect.
This value must be greater than or equal to min_num_digits.
[Required] This value is required when collect is specified.
.end_digit #*A-F0-9 The digit which specifies End of Input.
(Default = The default value configured in the RtpApp).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
(Default = The default value configured in the RtpApp).
.first_digit_timeout Positive Integer The number of seconds allowed between completing the announcement and entering the first digit.
(Default = The default value configured in the RtpApp).
.inter_digit_timeout Positive Integer The number of seconds allowed between entering one digit and entering the subsequent digit.
(Default = The default value configured in the RtpApp).
.interruptable 0 / 1 Informs the internal Media Server that DTMF input from the user should interrupt the playing of the prompt.
(Default = the prompt may be interrupted by the user).
.private_digits 0 / 1 Indicates that the collected digits are private, e.g. PIN entry, and the framework should not log them to EDR.
(Default = the default behavior configured for the application).

SCC-DO-ALEG-INTERACTION-EXTERNAL

The SCC-DO-ALEG-INTERACTION-EXTERNAL message is sent by the LogicApp to the LhoSipApp when it wishes the LhoSipApp to establish a temporary B-Leg connection to an external media server, and then to communicate with that external media server to request it to perform interaction.

The supported model is:

The service logic must specify the name of the INAP-controlled SRF to use, which must be a configured SRF in the LhoSipApp.

After sending this message, the service logic should send no further messages until it receives one of the following messages from the LhoSipApp:

Note that the first time this message is sent, the framework will establish a temporary B-Leg connection to the external SRF. The B-Leg is established by sending a SIP INVITE Request, where:

The B-Leg response will be passed-through using the standard B2BUA mechanism for B-Leg/A-Leg interaction.

Refer to the N2SIP Protocol Conformance Statement for a more thorough description of the supported SDP exchange mechanisms with specific reference to RFC 6337.

If there is currently a temporary B-Leg connection active for the purpose of performing announcements with an different external media server, then the framework will terminate the in-progress external announcement channel and then proceed to establish a new temporary connection to the requested new SRF.

If there is currently an internal on-node RTP media session in progress, then this will be ended before beginning the process to establish the temporary connection to the requested SRF.

If there is currently a B-Leg end-to-end call in progress, then this message will be rejected, i.e. it is not permitted to use this external announcement mechanism while a monitored or charged call is currently in progress. The service logic must explicitly end the B-Leg end-to-end call, or wait for it to be terminated by one of the parties.

After each announcement is complete (either because it played to the end of message, or because it was interrupted by user input) then the established temporary connection will remain established in the anticipation of subsequent announcements using the same external SRF name.

The temporary connection will be automatically ended if the subsequent action is an action which does not use it - e.g. the call is ended, or a request is made to establish an call to a B-Leg, or to establish a connection for the purpose of playing announcements using an internal media server, or to establish a temporary B-Leg connection for the purpose of playing announcements using a different external SRF.

Note: This message may not be sent without announcement information.

The underlying processing including INAP messaging is managed by the LhoSipApp:

  1. Send SIP INVITE to the address for the requested INAP-controllable SRF (including our SCP ID and correlation ID).
  2. Wait until we receive INAP AssistRequestInstructions.
  3. Send our instructions (INAP PlayAnnouncement or PromptAndCollectUserInformation).
  4. Wait to receive interaction results (INAP SpecializedResourceReport or PromptAndCollectUserInformation-Result).
  5. Return to the service logic and allow it to decide how to proceed.

The attributes of the SCC-DO-ALEG-INTERACTION-EXTERNAL message are:

Field Type Description
scc Object [Required] The detailed control parameters for the interaction.
.srf_name String [Required] An external SRF name as configured in the LhoSipApp.
.announcement Object [Required] Container for the attributes of the announcement to be constructed and played.
.message_id Integer A single message ID to play.
This ID must be coordiated with the external SRF.
Specify exactly one of .message_id or .message_ids.
.message_ids Array of Integer An array of message IDs to play.
These IDs must be coordiated with the external SRF.
Specify exactly one of .message_id or .message_ids.
.language String Optional language name which may be conveyed to the external SRF (if it supports sending of language information).
For external INAP-controlled SRFs, this name is mapped to an on-the-wire integer value according to the configured language map.
Refer to the LhoSipApp configuration documentation.
(Default = Platform-Configured Value)
.repetition Integer A requested repetition count supplied to the SRF.
This value is set in informationToSend.inbandInfo.numberOfRepetitions for the PA or PACUI.
(Default = do not specify this value to the SRF).
.duration Integer A requested duration value supplied to the SRF.
This value is set in informationToSend.inbandInfo.duration for the PA or PACUI.
(Default = do not specify this value to the SRF).
.interval Integer A requested interval value supplied to the SRF.
This value is set in informationToSend.inbandInfo.interval for the PA or PACUI.
(Default = do not specify this value to the SRF).
.variables Array of Object An array of variable values to substitute into pre-defined placeholders in the message structure.
Each variable part is an object which specifies exactly one of the attributes as follows.
.integer Integer An integer value to speak as a variable part.
.number_digits Integer An integer value to speak as a variable part.
.time_hhmm <HHMM> An integer hour and minute to speak as a variable part.
Value is in the range 0000-2400.
.date_yymmdd <YYMMDD> A 6-digit integer year/month/day to speak as a variable part.
.date_yyyymmdd <YYYYMMDD> An 8-digit integer year/month/day to speak as a variable part.
.price_digits Integer An integer value of "cents" to speak as a variable part.
.collect Object Container for information related to digit collection.
Digit collection will be performed if and only if this container element is present.
(Default = do not collect user input digits).
.min_num_digits 1 - 32 The minimum number of digits which the SRF will be instructed to collect.
This value is set in collectedInfo.collectedDigits.minimumNbOfDigits for the PACUI.
[Required] This required when collect is specified.
.max_num_digits 1 - 32 The maximum number of digits which the SRF will be instructed to collect.
This value must be greater than or equal to min_num_digits.
This value is set in collectedInfo.collectedDigits.maximumNbOfDigits for the PACUI.
[Required] This required when collect is specified.
.end_digit #*A-F0-9 The digit which specifies End of Input.
This value is set in collectedInfo.collectedDigits.endOfReplyDigit for the PACUI.
(Default = determined by the SRF).
.cancel_digit #*A-F0-9 The digit which specifies Cancel Input.
This value is set in collectedInfo.collectedDigits.cancelDigit for the PACUI.
(Default = determined by the SRF).
.first_digit_timeout Positive Integer The number of seconds allowed between completing the announcement and entering the first digit.
This value is set in collectedInfo.collectedDigits.firstDigitTimeOut for the PACUI.
(Default = determined by the SRF).
.inter_digit_timeout Positive Integer The number of seconds allowed between entering one digit and entering the subsequent digit.
This value is set in collectedInfo.collectedDigits.interDigitTimeOut for the PACUI.
(Default = determined by the SRF).
.interruptable 0 / 1 Informs the SRF that DTMF input from the user should interrupt the playing of the prompt.
This value is set in collectedInfo.collectedDigits.interruptableAnnInd for the PACUI.
(Default = do not specify this value to the SRF).
.private_digits 0 / 1 Indicates that the collected digits are private, e.g. PIN entry, and the framework should not log them to any EDR.
Note that this disables only the logging of the digits by the service logic and framework. The SRF is a separate, independent node element and this flag does not prevent the SRF from logging the collected digits.
(Default = the default behavior configured for the application).

SCC-DO-BLEG-TERMINATION-ATTEMPT

The SCC-DO-BLEG-TERMINATION-ATTEMPT is sent by the LogicApp to the LhoSipApp to request that a B-Leg
be set-up by sending out a new B-Leg INVITE, and proxying the RTP connection details.

The LhoSipApp in this case is acting as a Signaling Plane Back-to-Back User Agent (B2BUA) as defined in RFC 7092. Specifically, as a “Signaling-only” B2BUA as per RFC 7092, section 3.1.2.

If an (internal or external) SRF resource is currently open then it will be disconnected.

After sending this message, the service logic should send no further messages until it receives one of the following messages from the LhoSipApp:

The attributes of the SCC-DO-BLEG-TERMINATION-ATTEMPT message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.no_answer_timeout Integer Specify how long the INVITE will be permitted to try before we CANCEL.
(Default = a system-configured default value).
.address_digits (+)Hex String [Required] The digits part of the new To address for the B-Leg.
The protocol and domain parts of the address will be determined automatically.
.extra_headers Object Additional user headers to add for this outbound B-Leg SIP INVITE.
The object key is the header name.
The object value is an array of header values.
(Default = do not add extra outbound SIP INVITE user headers).
.max_call_secs Integer Specifies the maximum permitted call duration in seconds.
The LhoSipApp may enforce minimum and maximum bounds for this value.
(Default = use the max_call_secs configured on the LhoSipApp).
.monitored 1 Set this value to indicate that this is a "Monitored" call attempt. At most one of monitored or charged may be specified.
The call will have SIP re-INVITE activity tests sent to check that the call is still active.
If this call attempt is answered, then the service logic must use the .monitor_check method to monitor the call until it completes.
(Default = the call is not monitored).
.monitor_interval_secs Integer Specifies the interval in seconds between the SIP re-INVITE activity tests and the associated monitor reports sent back to the service logic.
The LhoSipApp will enforce minimum and maximum bounds for this value.
Valid only when monitored = 1.
(Default = use the activity_interval_secs configured on the LhoSipApp).
.charged 1 Set this value to indicate that this is a "Charged" call attempt. At most one of monitored or charged may be specified.
The call will have SIP re-INVITE activity tests sent to check that the call is still active.
If this call attempt is answered, then the service logic must use the .charge_check method to control call charging until it completes.
(Default = the call is not charged).
.grant_secs Integer [Required] Specifies the interval in seconds for the initial SIP re-INVITE activity tests and the associated first charge report sent back to the service logic.
The LhoSipApp will enforce minimum and maximum bounds for this value.
Valid only when charged = 1.

SCC-DO-CHARGE-EXTEND

The SCC-DO-CHARGE-EXTEND is sent by the LogicApp to the LhoSipApp to request that a B-Leg
be set-up by sending out a new B-Leg INVITE, and proxying the RTP connection details.

The LhoSipApp in this case is acting as a Signaling Plane Back-to-Back User Agent (B2BUA) as defined in RFC 7092. Specifically, as a “Signaling-only” B2BUA as per RFC 7092, section 3.1.2.

If an (internal or external) SRF resource is currently open then it will be disconnected.

After sending this message, the service logic should send no further messages until it receives one of the following messages from the LhoSipApp:

The attributes of the SCC-DO-CHARGE-EXTEND message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.grant_secs Integer [Required] Specifies the interval in seconds for the subsequent SIP re-INVITE activity tests and the subsequent charge reports sent back to the service logic.
The LhoSipApp will enforce minimum and maximum bounds for this value.

SCC-DO-SHUTDOWN

The SCC-DO-SHUTDOWN is sent by the LogicApp to the LhoSipApp to indicate that service logic processing has failed unexpectedly and cannot continue. The LhoSipApp will perform any necessary SIP transaction closure, using final result, CANCEL, or BYE as applicable. The LhoSipApp will raise a warning, in addition to the service logic warning which usually arises.

No further SCC-... messages should be exchanged after this message is sent.

The attributes of the SCC-DO-SHUTDOWN message are:

Field Type Description
error String [Required] A descriptive error message to record in the warning.

SCC-HANDLE-ALEG-INBOUND-INVITE

The SCC-HANDLE-ALEG-INBOUND-INVITE message is generated by the LhoSipApp and is sent to the LogicApp when an inbound INVITE is received by the LhoSipApp. The LhoSipApp is configured with the name of the LogicApp to which the SCC-HANDLE-ALEG-INBOUND-INVITE should be sent.

When the SCC-HANDLE-ALEG-INBOUND-INVITE arrives at the LogicApp, there must be a configured LhoSipLuaService present to receive and process it. The LhoSipLuaService will examine the request contents and compare that to its configured triggers list (or database equivalent) in order to determine which LUA script to execute.

The actual logic for selecting and loading the LUA script depends on the specific service. The matching and loading will typically come from a database, e.g. for the N2ACD-SIP implementation for Toll-Free SIP call handling.

After receiving SCC-HANDLE-ALEG-INBOUND-INVITE, the call is “controlled” by the service logic.
The service logic must (within the service logic timer) send one of the following SIP call control messages:

The attributes of the SCC-HANDLE-ALEG-INBOUND-INVITE message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.call_id String [Required] The SIP Call ID from the received INVITE Request.
.from Table [Required] The decoded object representation of the "From" header.
.header String [Required] The original "From" header value, complete.
.display_name String The Display Name, if present.
.parameters Table A map of top-level parameter values (not the address parameters).
This will include the tag, and could include isup-oli or other site-specific parameters.
A parameter, e.g. ;urgent will be present with a value of UNDEF.
.address Table [Required] Container for the Address attributes.
.uri String [Required] The complete encoded URI including address parameters, but not including any < >.
.protocol String [Required] The protocol, sip or tel.
.user String [Required] The user part of the address, preceding the @.
.host String The host part of the address, if present.
.port Integer The port number part of the address, if explicitly present.
.parameters Table The inner address parameters (not the top-level parameters).
This will include the transport parameter (if explicit), and could include otg or other site-specific parameters.
A parameter, e.g. ;exdirectory will be present with a value of UNDEF.
.to Table [Required] The decoded object representation of the "To" header.
The table structure is identical to the structure described for the "From" header.
.privacy Table This table will be present only when both the sip_privacy_header parameter is enabled for the application, and the Privacy header is present in the received A-Leg SIP INVITE.
In this case, this table will have entries with keys matching each of the Privacy attributes which are present in this header, each with the value 1.
For example if the Privacy header has value user;id then this table will be { user = 1, id = 1}.
(Default = The header was not present, or the feature is not enabled for the app)
.extra_headers Table A table of extra headers "of interest" from the received A-Leg SIP INVITE.
These are only headers specifically configured in the `<invite_headers>` configuration block.
Each table entry is a non-empty list of raw header values parse for that header name.
The header name key is upper/lower case as defined in the `name` attribute of the `<invite_header>` configuration, even though the matching for the header name in the SIP INVITE is performed using case-insensitive matching.
(Default = no headers of interest were matched)
.calling_party (+)Hex String [Required] Calling Party address digits.
This is the part of the P-Asserted-Identity or From address that precedes the @.
It is guaranteed to contain only 0-9A-F digits.
.called_party (+)Hex String [Required] Called Party address digits.
This is the part of the To address which precedes the @.
It is guaranteed to contain only 0-9A-F digits.
.normalised_calling_party (+)Hex String [Required] Normalised Calling Party address digits.
This is the calling_party after any configured 'called_party' normalisation rules have been applied.
It is guaranteed to contain only 0-9A-F digits.
.normalised_called_party (+)Hex String [Required] Normalised Called Party address digits.
This is the called_party after any configured 'called_party' normalisation rules have been applied.
It is guaranteed to contain only 0-9A-F digits.
.pending_tn (+)Hex String [Required] Pending termination number digits.
The normalised pending termination number inferred from the INVITE.
It is guaranteed to contain only 0-9A-F digits.
.isup Object A container for any SIP-I ISUP message parsed from the received SIP INVITE Request.
.iam Table The decoded representation of the ISUP Initial Address Message, if one was present in the received SIP INVITE Request.
This has structure as described in the N2::ISUP::IAM Codec documentation.

SCC-HANDLE-ALEG-PROCEEDED

The SCC-HANDLE-ALEG-PROCEEDED message is sent from the LhoSipApp to the LogicApp as a response to SCC-DO-ALEG-PROCEEDING once the proceeding is succesfully complete, because either:

  1. Reliable 100rel provisional responses (i.e. PRACK) were not required, or
  2. Reliable 100rel provisional responses was required, and the PRACK was received.

After receiving SCC-HANDLE-ALEG-PROCEEDED, the call is still “controlled” by the service logic and both decline and proceeding methods may be used.

The service logic must (within the service logic timer) send one of the following SCC control messages:

The attributes of the SCC-HANDLE-ALEG-PROCEEDED message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.reason Proceeded [Required] The reason why this message was sent. The value is fixed.

If the proceeding attempt did not succeed, then the LhoSipApp will indicate this by sending either SCC-HANDLE-ALEG-ABANDON-FINAL (if the call was cancelled) or SCC-HANDLE-SHUTDOWN (if there is a SIP error or timeout while waiting for the PRACK).

SCC-HANDLE-ALEG-INTERACTION-COMPLETE-ONGOING

The SCC-HANDLE-ALEG-INTERACTION-COMPLETE-ONGOING message is sent from the LhoSipApp to the LogicApp as a response to SCC-DO-ALEG-INTERACTION-INTERNAL or SCC-DO-ALEG-INTERACTION-EXTERNAL if the interaction completes with the A-Leg still active.

After receiving SCC-HANDLE-ALEG-INTERACTION-COMPLETE-ONGOING, the call is still “controlled” by the service logic. The service logic must (within the service logic timer) send one of the following SCC control messages:

The attributes of the SCC-HANDLE-ALEG-INTERACTION-COMPLETE-ONGOING message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.error String An optional interaction error related to a problem in playing the announcement or collecting input.
.digits #*A-F0-9 Input digits collected from user.
May include * or # characters according to the MS/SRF's interpretation.
The .digits and .error are mutually exclusive.
In theory, the MS/SRF should return no digits at all in the case where insufficient digits are entered. However, that behavior can vary according to SRF manufacturer, and the service logic should always validate the number of digits returned.
.decline_ok 0 / 1 Indicates if the service logic may still send the SCC-DO-ALEG-DECLINE-FINAL message.
(Default = 0, decline is not permitted)

SCC-HANDLE-ALEG-INTERACTION-ABANDONED-FINAL

The SCC-HANDLE-ALEG-INTERACTION-ABANDONED-FINAL message is sent from the LhoSipApp to the LogicApp as a response to SCC-DO-ALEG-INTERACTION-INTERNAL or SCC-DO-ALEG-INTERACTION-EXTERNAL if the interaction completes with the A-Leg no longer active.

After receiving SCC-HANDLE-ALEG-INTERACTION-ABANDONED-FINAL, the call is no longer “controlled” by the service logic.

No further SCC-... messages should be exchanged after this message is sent.

The attributes of the SCC-HANDLE-ALEG-INTERACTION-ABANDONED-FINAL message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.reason Abandoned [Required] The reason why this message was sent. The value is fixed.

Note that it is possible to have digits returned even if the interaction was abandoned. This may happen with some SRF behaviors, and/or some timing conditions.

SCC-HANDLE-ALEG-ABANDON-FINAL

The SCC-HANDLE-ALEG-ABANDON-FINAL message is sent from the LhoSipApp to the LogicApp at any time when the A-Leg abandons the call.

At this SIP level, this will be when the A-Leg sends CANCEL (in the case that no final response has yet been sent to the originator), or when the A-Leg sends BYE (in the case where the B-Leg is being established by a re-INVITE).,

After receiving SCC-HANDLE-ALEG-ABANDON-FINAL, the call is no longer “controlled” by the service logic.

No further SCC-... messages should be exchanged after this message is sent.

The attributes of the SCC-HANDLE-ALEG-ABANDON-FINAL message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.reason Abandoned [Required] The reason why this message was sent. The value is fixed.
.talk_dsm Integer The total talk-time in deci-seconds as measured by the SIP call control app.
This field is present only when the call was successfully established.
It will include confirmed time up to the successful BYE sequence, or the preceding successful activity test (if any).
(Default = 0, no talk-time was confirmed)

SCC-HANDLE-BLEG-ANSWER-FINAL

The SCC-HANDLE-BLEG-ANSWER-FINAL message is sent from the LhoSipApp to the LogicApp as a response to SCC-BLEG-TERMINATION-ATTEMPT if and when the termination attempt is successful, (i.e. the B-Leg confirms the call with a 2XX final response and the ACK is successful) and when the service logic is not monitoring the call.

The call is now in progress. The LhoSipApp will stay in the signalling path in order to pass-through the BYE, performing its role as a SIP back-to-back user agent (B2BUA).

However, for B-Legs initated by SCC-BLEG-TERMINATION-ATTEMPT without monitoring, the call is no longer “controlled” by the service logic after receiving SCC-HANDLE-BLEG-ANSWER-FINAL.

No further SCC-... messages should be exchanged after this message is sent.

The attributes of the SCC-HANDLE-BLEG-ANSWER-FINAL message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.reason Answered [Required] The reason why this message was sent. The value is fixed.

SCC-HANDLE-BLEG-ANSWER-ONGOING

The SCC-HANDLE-BLEG-ANSWER-ONGOING message is sent from the LhoSipApp to the LogicApp as a response to SCC-BLEG-TERMINATION-ATTEMPT if and when the termination attempt is successful, (i.e. the B-Leg confirms the call with a 2XX final response and the ACK is successful) and when the service logic is monitoring/charging the call.

The call is now in progress. The LhoSipApp will stay in the signalling path in order to pass-through the BYE, performing its role as a SIP back-to-back user agent (B2BUA).

The service logic is also staying in the control path for the duration of the call, and is responsible for “sweeping” the subsequent SCC messages which may be sent to the service:

After receiving SCC-HANDLE-BLEG-ANSWER-ONGOING or SCC-HANDLE-MONITOR-REPORT, the service logic may force the call to be ended by sending:

Note that “.decline” is never OK after this message.

The attributes of the SCC-HANDLE-BLEG-ANSWER-ONGOING message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.monitored 1 This call is monitored by the service logic (not charged).
Exactly one of monitored or charged must be present in this message.
.charged 1 This call is charged by the service logic.
Exactly one of monitored or charged must be present in this message.
.reason Answered [Required] The reason why this message was sent. The value is fixed.
.max_call_secs Integer [Required] The actual maximum permitted call duration in seconds to be used for this call.
This value may differ from the requested value, it may have defaults, minimum, or maximum limits applied.
.monitor_interval_secs Integer [Required] The actual monitor reporting interval call duration in seconds to be used for this call.
This value may differ from the requested value, it may have defaults, minimum, or maximum limits applied.

SCC-HANDLE-BLEG-FAILURE-ONGOING

The SCC-HANDLE-BLEG-FAILURE-ONGOING message is sent from the LhoSipApp to the LogicApp as a response to SCC-DO-BLEG-TERMINATION-ATTEMPT if and when the termination attempt fails due to being declined by the B-Leg.

After receiving SCC-HANDLE-BLEG-FAILURE-ONGOING, the call is still “controlled” by the service logic. The service logic must (within the service logic timer) send one of the following SCP control messages:

The attributes of the SCC-HANDLE-BLEG-FAILURE-ONGOING message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.reason "No Answer" / "No Route" / "Declined" [Required] The reason why the B-Leg could not be established.
.code Integer The received SIP B-Leg final response status code, in the range 300-699.
This is present, except for the case where .reason = "No Route".
.decline_ok 0 / 1 Indicates if the service logic may still send the SCC-DO-ALEG-DECLINE-FINAL message.
(Default = 0, decline is not permitted)

SCC-HANDLE-BLEG-TEARDOWN-ONGOING

The SCC-HANDLE-BLEG-TEARDOWN-ONGOING message is sent from the LhoSipApp to the LogicApp as a response to SCC-DO-BLEG-TERMINATION-ATTEMPT if and when the termination attempt succeeds, and then the call ends because of B-Leg hangup.

After receiving SCC-HANDLE-BLEG-TEARDOWN-ONGOING, the call is still “controlled” by the service logic. The service logic must (within the service logic timer) send one of the following SCP control messages:

Note that “.decline” is never OK after this message.

The attributes of the SCC-HANDLE-BLEG-TEARDOWN-ONGOING message are:

Field Type Description
scc Object [Required] The SCC control parameters for the message.
.reason "Hangup" [Required] The reason why this message was sent. The value is fixed.
.talk_dsm Integer [Required] The total talk-time in deci-seconds as measured by the SIP call control app.

SCC-HANDLE-SHUTDOWN

The SCC-HANDLE-SHUTDOWN is sent by the LhoSipApp to the LogicApp to indicate that call processing has failed unexpectedly and cannot continue. The LhoSipApp has perform any necessary SIP transaction closure, using final result, CANCEL, or BYE as applicable, and has raised a warning.

No further SCC-... messages should be exchanged after this message is sent.

The attributes of the SCC-DO-SHUTDOWN message are:

Field Type Description
error String [Required] The descriptive error message raised in the warning.