The SipMidCallPlayAnnouncement feature plays a queue of announcements to the configured party during mid session.
Details
Feature script name |
SipMidCallPlayAnnouncement |
|---|---|
Applicable contexts |
SIP service |
Prerequisite Features |
Any feature setting the MidcallAnnouncementId session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature. |
Typical feature execution points |
SipAccess_ServiceTimer, SipAccess_PartyResponse, SipMidSession_PartyRequest, SipMidSession_PartyResponse, and any other mid-session execution point where an announcement may be desired, such as SipMidSession_CreditLimitReached. |
Timer usage |
Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry. |
The announcements are played by the MRF. The Language and the ID of the announcements to be played are set in the MidCallAnnouncementQueue, MidcallAnnouncementId and LanguageConfig session variables. If the MidcallAnnouncementId session variable is not set (null) or set to 0, the MidCallAnnouncementQueue is checked. If the queue is also clear, no announcement is played and the feature returns without error or side effect to the dialog.
Another feature must be executed prior to the SipMidCallPlayAnnouncement feature to set the LanguageConfig and the MidcallAnnouncementId or queue.
All announcements which are played by the feature are appended to the PlayedAnnouncementIDs session state variable. This list of announcements is used by the standard CDR mappers and may be used in custom CDR mappers.
The LanguageConfig String is a language code in RFC 3066 format. Use of the LanguageConfig session state field is optional. The feature will search for a profile using the LanguageConfig and MidcallAnnouncementId as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the MidcallAnnouncementId.
If there are multiple announcements scheduled (eg the MidcallAnnouncementId field has been set as well as at least one entry in the queue, or simply multiple entries in the queue), each announcement will be attempted on a new MRF dialog when each previous announcement completes (whether or not it played successfully). Each subsequent announcement necessitates sending another Re-INVITE to the calling party. If the MRF times out at any point, the MRF session will be torn down appropriately and the call will proceed as normal including queued announcements (or be ended, as in the above scenario).
Call flows
Mid-call low-credit announcement
In this scenario, a feature installed in SipAccess_CreditAllocatedPostCC analyzes the CCA-U and determines that the charged party has low credit. The feature script then runs the MidCallPlayAnnouncement feature. Points of interest are highlighted and explained below the diagram.
Request from PlayedParty arrives while waiting for answer to PassiveParty hold INVITE
In this scenario, the PlayedParty sends an INVITE or an UPDATE while Sentinel is waiting for the PassiveParty to respond to the hold INVITE. The request is rejected and the announcement is set up as normal.
PassiveParty does not accept being put on hold
The feature will simply end the announcement and allow the session to continue.
MRS unresponsive after initial provisional response
When the INVITE request is sent to MRS, Sentinel receives a provisional 100 Trying response which cancels the SIP-Stack-internal request timeout timer; however, no further response is received.
Sentinel fires its own ‘noResponse’ timer which ultimately times out.
The PlayAnnouncement feature handles the timer event (the feature must be installed in the SipAccess_ServiceTimer execution point) and sends a CANCEL to MRS. The leg is subsequently released.
The PAShouldEndSessionWhenFinished session state field indicates whether the feature should send endSession to the core or not. The call may continue afterwards.
Resume call during announcement
For this call flow to work, the Interruptable flag is set to true in the announcement configuration. This tells the feature that the announcement can be stopped by either the call being resumed by the passive party for hold cases, or the call ended if the passive party was to end it with a BYE.
A call is put on hold with a long-running announcement. When the holding party resumes the call, a feature detects the resume request and sets the RequestIsResume session state field.
When the announcement feature runs and sees this, as well as the interruptable flag, it will stop the announcement and re-connect the two parties for the call to proceed.
Leg Manager inputs
| Leg | Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|---|
callingParty |
InviteRequest |
org.jainslee.resources.sip.SipRequest |
See Easysip Javadoc |
INVITE received from (and respectively, in the NetworkInitiated case, sent to) the calling party |
Runtime exception handled by feature runner |
Session state inputs and outputs
Inputs
| Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
Selection key (for example, |
For selecting configuration data |
Increment InputParameterErrors |
SDP |
String |
Text |
Session description |
Outgoing request will not contain SDP |
LanguageConfig |
String |
An optional String input containing a language code. The RFC 3066 defines language codes, but the feature does not validate the format. |
The value of this fields will be used to get the proper announcement profile. Default is null. |
If null the profile search will not consider the language |
MidcallAnnouncementId |
Integer |
Non-negative |
ID of the announcement to be played — 0 indicates no announcement to play Increment InvalidAnnouncementIDs |
Check the announcement queue |
MidCallAnnouncementQueue |
List<Integer> |
Non-negative |
ID of the announcements to be played |
Report featureHasFinished |
PlayedAnnouncementIDs |
int[] |
List of announcement IDs |
Announcements which have already been played |
Initialized to an empty array |
PAShouldEndSessionWhenFinished |
boolean |
Indicates whether the feature will call |
Default is false |
|
MidCallAnnouncementPlayedParty |
String |
Leg name indicating which party the announcement will be played to |
Linked leg will be passivated during announcement |
Play to callingParty |
RequestIsResume |
boolean |
Indicates whether the current request is a resume. Set by other features to be read by this one. |
Default is false |
Outputs
| Name | Type | Format | Description |
|---|---|---|---|
PlayedAnnouncementIDs |
int[] |
List of announcement IDs |
Updated with the announcement ID once it is played |
MidcallAnnouncementId |
Integer |
Non-negative, non-zero, announcement in progress |
Set to zero once announcement has been played, and null when all announcements are finished |
PAShouldEndSessionWhenFinished |
boolean |
Set to true if the feature is invoked in the CreditLimitReached execution point. Can be cleared by a subsequent feature |
|
MidCallAnnouncmeentQueue |
List<Integer> |
List of scheduled announcement IDs |
A queue of announcements to play. As each announcement is played, it is removed from the queue. |
Error scenarios
| Scenario | Handling |
|---|---|
Null sessionstate MidcallAnnouncementId |
Increment MissingAnnouncementIDs |
MidcallAnnouncementId session state field is ⇐ 0 |
Increment InvalidAnnouncementIDs |
Null sessionstate SentinelSelectionKey |
Increment InputParameterErrors |
ACI not provided to the announcement feature |
Increment InputParameterErrors |
SipSession object not provided to the announcement feature in the activity context interface |
Increment InputParameterErrors |
Announcement properties not found for announcement ID |
Increment InputParameterErrors |
Announcement resource config not found for resource config ID |
Increment ConfigurationErrors |
Failed to send INVITE to Media Server |
Increment SipSendErrors |
Error received from MRF on Invite |
Send Ack with Rejection to played party |
Error received from MRF on Cancel due to played party BYE |
Increment SipErrors |
MediaServer response timeout to INVITE |
Send Ack with Rejection to played party |
MediaServer response timeout to Cancel |
Increment SipErrors |
Failed to send 200 Prack response |
Increment SipSendErrors |
Failed to send ACK to MRF |
Increment SipSendErrors |
Failed to send BYE to MRF |
Increment SipSendErrors |
Failed to send CANCEL to MRF |
|
Failed to send 183 response due to unable to access INVITE from SIPSession |
Increment InputParameterErrors |
Failed to send 183 response |
Increment SipSendErrors |
Common cleanup actions
Here are some common cleanup actions:
-
If a BYE was received from the played or passive party during the feature, release the other party as well as the MRF leg.
-
If both parties are still present, re-link the legs for B2BUA behaviour.
-
Cancel the NoResponseTimer.
-
Add the AnnouncementId to the sessionstate PlayedList.
-
Release the MRF Leg (may have been done already).
-
Increment FeatureFSMCompletions.
-
If the PAShouldEndSessionWhenFinished session state field is true, call endSession.
-
Finish.
Announcement configuration
Announcements are referenced by ID. The following table shows configuration parameters for provisioning them.
| Parameter | Type | Description |
|---|---|---|
Description |
String |
Description of the announcement |
Id |
String |
Announcement id (number) plus optional language (eg. 20:en_NZ) |
AnnouncementURL |
String |
URL of the announcement |
Delay |
Integer |
Delay interval between announcement repetitions (in ms) |
Duration |
Integer |
Maximum duration of the announcement (in ms) |
Locale |
String |
Locale of the announcement as a string |
MimeType |
String |
MimeType of the announcement as a string |
Repeat |
Integer |
How many times the media server should repeat the announcement. (-1 means 'forever') |
ResourceConfig |
String |
Name of the profile holding the media resource configuration |
SuspendCharging |
Boolean |
True if charging is suspended during the announcement (only applies to Mid Call Announcements) |
Interruptable |
Boolean |
True if the announcement is interruptable (only applies to Mid Call Announcements) |
EnforceOneWayMedia |
Boolean |
True if media should be unidirectional from the MRF to the played party for the announcement. The feature will modify SDP directionality attributes between the MRF and played party to do this. (only applies to Mid Call Announcements) |
Example
Here is an example announcement table configuration:
| ID | Description | AnnouncementURL | Delay | Duration | Locale | MimeType | Repeat | ResourceConfig | SuspendCharging | Interruptable | EnforceOneWayMedia |
|---|---|---|---|---|---|---|---|---|---|---|---|
15 |
Play message "You have insufficient credit to make this call" |
file:msg_15.wav |
0 |
4000 |
en |
audio/vnd.wave |
0 |
default |
true |
false |
false |
17 |
Play tone |
500 |
100 |
audio/vnd.wave |
2 |
default |
false |
false |
false |
The ResourceConfig is a reference by ResourceId to an entry in the Resource Configuration table with the resource configuration.
Resource configuration
| Parameter | Type | Description |
|---|---|---|
ResourceId |
String |
ID of this resource configuration |
MediaServerURI |
String |
The configured value for the media server URI |
RouteDirectToResource |
Boolean |
The configured value for the route direct to resource |
ServiceParameterType |
String |
The configured value for the service parameter type (for example, play, voicexml) |
NoResponseTimeout |
Long |
The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE or CANCEL |
ICSCFURI |
String |
The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false |
Configuration profile naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id |
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id:language |
SipAnnouncementResourceConfigProfileTable |
Announcement resource addresses and other resource configuration data |
SentinelSelectionKey:resourceConfigName |
