The SipPlayAnnouncement feature plays a queue of announcements to the calling party during call establishment.
Description
Feature script name |
SipPlayAnnouncement |
|---|---|
Applicable contexts |
SIP service |
Prerequisite features |
Any feature setting the AnnouncementID session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature. |
Typical feature execution points |
SipAccess_PartyResponse, SipAccess_PartyRequest, SipMidSession_PartyResponse, SipMidSession_PartyRequest, SipAccess_ServiceTimer, and any SipAccess execution points where an announcement may be triggered, such as SipAccess_SubscriberCheck. |
Timer usage |
Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry. |
The announcement is played by the MRF. The id and the language of the announcements to be played are set in the AnnouncementID and LanguageConfig session variables. If the AnnouncementID session variable is not set (null) or set to 0, no announcement is played and the feature returns without error or side effect to the dialog.
Another feature must be executed prior to the SipPlayAnnouncement feature to set the AnnouncementID and the LanguageConfig.
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 AnnouncementID as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the AnnouncementID as key.
The SipPlayAnnouncement feature supports UE preconditions if present.
Example Callflows
Play Announcement without Preconditions - OCS Rejects Call
In this scenario, the CCA-I returns with result code 4012 (credit limit reached); and a feature setting the EndSessionAfterAnnouncement session state field to a non-zero value is installed in the SipAccess_CreditLimitReached execution point and runs before PlayAnnouncement, which is also installed in the same execution point. B-Party is never contacted.
The MRF dialog is similar for other types of pre-call announcements, including successful calls.
If the A-Party cancels at any point, the MRF SIP dialog will be torn down appropriately. If there are multiple announcements scheduled (eg the AnnouncementID 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 183 to the calling party, which will be translated to an UPDATE as needed by the Sequential Forked SDP Mediation feature. 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).
Early media play announcement with preconditions and VoWiFi
In this scenario, the caller has resources available as the bearer is WiFi, so there is no value in resource reservation from the caller’s perspective.
Preconditions are in use in case the terminating party does not have resources available at INVITE time. However in this call flow the terminating party is the MRF which does have resources available.
The initial INVITE from the UE will contain these media attributes related to QoS.
a=sendrecv a=curr:qos local sendrecv a=curr:qos remote none a=des:qos mandatory local sendrecv a=des:qos none remote sendrecv
The 183 from the TAS towards the UE will not contain a conf line like this
a=conf:qos remote sendrecv
If in the initial INVITE the UE includes P-Early-Media: supported then the TAS must insert the P-Early-Media: sendrecv header in the 183 response.
This is because some devices includes a P-Early-Media: supported header in the initial INVITE and some MRFs do not include it in the 183 response.
Some devices will not play early media unless they receive the P-Early-Media header in the 183 response.
Early media play announcement with preconditions and VoLTE
This case differs from the WiFi case as LTE allows the use of radio resource reservation.
Therefore the INVITE from A indicates that the current state is inactive.
The MRF already has resources available.
The initial INVITE from the UE will contain these media attributes related to QoS.
a=inactive a=curr:qos local none a=curr:qos remote none a=des:qos mandatory local sendrecv a=des:qos none remote sendrecv
The 183 from the MRF will contain a conf line like this, instructing A to UPDATE when its resources are available
a=conf:qos remote sendrecv
If in the initial INVITE the UE includes P-Early-Media: supported then the TAS must insert the P-Early-Media: sendrecv header in the 183 response sent upstream.
This is because some devices include a P-Early-Media: supported header in the initial INVITE and some MRFs do not include it in the 183 response.
Some devices will not play early media unless they receive the P-Early-Media header in the 183 response.
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 (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 Common cleanup actions |
SDP |
String |
Text |
Session description |
Outgoing request will not contain SDP |
AnnouncementID |
Integer |
non-negative |
ID of the current announcement to be played — 0, negative values and |
Poll the |
EarlyMediaAnnouncementQueue |
List<Integer> |
A list of positive integers |
A list of IDs of the subsequent announcements to be played — entries such as |
If the queue itself is null, report featureHasFinished. If one of the entries is null or invalid, increment InvalidAnnouncementIDs and play the next one in the queue. |
PlayedAnnouncementIDs |
int[] |
List of announcement IDs |
Announcements which have already been played |
Initialized to an empty array |
EndSessionAfterAnnouncement |
int |
The feature will call endSession with the provided error code upon completion if non-zero |
Default value is 0 — does not end session |
|
LanguageConfig |
String |
The RFC 3066 defines language formats, but the feature does not validates the format. |
The feature will use the LanguageConfig supplied by the session state field as an input and use it to retrieve the proper announcement profile. |
The default value is null, a null value runs the default profile without language configuration. |
Outputs
| Name | Type | Format | Description |
|---|---|---|---|
PlayedAnnouncementIDs |
int[] |
List of announcement IDs |
Updated with the announcement ID once it is played |
AnnouncementID |
Integer |
non-negative |
Set to id of current announcement to play (either by a preceding feature or by polling the early media announcement queue). Set to zero once all announcements have been played |
Error scenarios
| Scenario | Handling |
|---|---|
Null, negative or 0 found in EarlyMediaAnnouncementQueue |
Increment InvalidAnnouncementIDs + retrieve next entry |
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 |
Increment SipErrors |
MediaServer response timeout |
Increment SipErrors |
Failed to send 200 Prack response |
Increment SipSendErrors |
Report end Session with 500 |
ServerError to SIP Sentinel core |
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: |
|
|---|
Announcement configuration
Announcements are referenced by id and language code. The configuration of each announcement id is provisioned in the following table:
| 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 hold 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) |
EndSessionOnFailure |
Boolean |
True if the call should be ended if this announcement fails to play. (Only applies to Early Media 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 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. It is used by the announcement configuration profile to reference this configuration. |
MediaServerURI |
String |
The configured value for the media server URI |
RouteDirectToResource |
Boolean |
The configured value for the route direct to resource. If true, the service sends the Play Announcement INVITE directly to the media server (i.e. using Request URI) (values: true or false) |
ServiceParameterType |
String |
The configured value for the service parameter type e.g. play, voicexml |
NoResponseTimeout |
Long |
The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE. |
ICSCFURI |
String |
The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false. |
Example resource configuration profile:
| ResourceId | MediaServerURI | RouteDirectToResource | ServiceParameterType | NoResponseTimeout | ICSCFURI |
|---|---|---|---|---|---|
default |
sip:annc-audio@localhost:5260;lr;transport=tcp |
true |
play |
1000 |
icscfhost:5054 |
voice |
sip:dialog@mediaserver:5061;lr;transport=udp |
true |
voicexml |
1000 |
icscfhost:5054 |
Configuration profile naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id (for example, |
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id (for example, |
SipAnnouncementResourceConfigProfileTable |
Announcement resource addresses and other resource configuration data |
SentinelSelectionKey:resourceConfigName (for example, |
Provisioning interfaces
The feature is provisioned using the Sentinel Features REST API or web interface.
