4 Developing a SIP User Interaction Application

This chapter describes how to develop a SIP application that provides user interaction functionality.

About User Interaction Functionality

User interaction is the method of having a SIP application interacting with a call party during the application logic processing.

The following forms of user interaction exist:

Playing an announcement, when an announcement is played to a call party
Information collection, when DTMF digits are collected from the calling party and an announcement can be optionally played to the call party
Playing a tone

An application may perform a user interaction operation during different points of call:

During call establishment, when the application provides an announcement to a call party prior to completing the call establishment process. This announcement is called pre-call announcement.
During active call, when the application provides an announcement to a call party during an active call. This announcement is called mid-call announcement.
During call release, when the application provides an announcement to a call party prior to completing the call release process. This announcement is called post-call announcement.

To provide the user interaction functionality, the application receives a SIP INVITE message sent by Oracle Communications Service Broker, and sends a new SIP INVITE targeted to an MRF. The application performs this action by setting the To header of the SIP INVITE to the address of the MRF.

Figure 4-1 shows the high level architecture for an application that creates a user interaction session.

Figure 4-1 Architecture for Creating a User Interaction Session by the Application

Creating User Interaction Session by Application

Note:

Both the application and Service Broker can place an SDP on a SIP 183 Session In Progress message. Therefore, to guarantee a reliability of this message which triggers a CAP ConnectToResource, the application and Service Broker must request a SIP PRACK by setting the Require header of the SIP 183 Session In Progress to rel100.

About the Media Resource Table

Service Broker has a media resource table configuration. When receiving an INVITE from the application, Service Broker extracts the content of the To header and uses this content as an MRF alias. Service Broker queries the media resource table for this alias to determine the following parameters:

Media resource type: Service Broker supports internal media resource only

Note:
The terms external and internal referred to MSC. An external resource is a stand–alone gsmSRF (IP) while internal resource is an gsmSRF integrated within the MSC.
Media Resource Address: the address of the media resource
Answer indication: a flag used by Service Broker to instruct an MSC about sending a backward answer message through the ISUP connection

Upon determination of a media resource to be used, Service Broker acts towards the SIP application as an MRF, responds to the application with SIP 200 OK. The SIP 200 OK message includes an SDP created by Service Broker.

Figure 4-2 shows the high level architecture for Service Broker that confirms the MRF dialog created by the application.

Figure 4-2 Architecture for Sending SIP 200 OK from Service Broker to the Application

Sending SIP 200 OK from Service Broker to Application

When the application receives the SIP 200 OK message, the application updates the SDP to the initiating side. This is done by propagating the SDP received from Service Broker towards the SIP dialog created by Service Broker.

To update the SDP to the initiating side, the application uses one of the following SIP messages:

SIP 183 SESSION PROGRESS: usually, in a pre-call announcement scenario
SIP reINVITE: usually, in a mid-call and post-call announcement scenario

Figure 4-3 shows the high level architecture for an application that updates the SDP to the call initiating side (pre-call announcement scenario).

Figure 4-3 Architecture for Updating the SDP to the Initiating Side

Based on the specific MRF alias, Service Broker performs a CAP ConnectToResource (CTR) operation.

Suspending Call Processing for Pre-Call Announcements

Note:

The functionality described in this section is relevant only for those applications that work over CAP phase 4 networks because only CAP phase 4 networks provide multileg capabilities.

An application can create a call leg and connect this leg to a media resource for playing announcement or collecting information. To be able to play an announcement or collect information on the leg answer, the application needs to instruct Service Broker to suspend sending a ContinueWithArguments operation when Service Broker received an ERB Answer armed as EDP-R Answer.

While Service Broker is in the suspension mode, the application sends to Service Broker a SIP INVITE with the To header set to the alias of the MRF. After the MRF played the announcement or the leg terminated the call, Service Broker sends a ContinueWithArguments to the leg.

To set Service Broker in the suspension mode on the leg answer, the application needs to set the x-wsc-cps header to "late".

Figure 4-4 shows a call flow when an application creates a leg by sending a SIP INVITE message to Service Broker. To force Service Broker to suspend sending a ContinueWithArguments operation, the application sets the x-wcs-cps header to "late". After the announcement is played, and Service Broker sent the DisconnectFromResource operation, Service Broker continues the call by sending the ContinueWithArguments. Similarly, Service Broker can continue the call if the leg sends an ERB Disconnect operation.

Notice that the x-wcs-cps header set to "late" is added to the leg SIP INVITE message rather than to the SIP INVITE to the MRF alias.

Figure 4-4 Instructing Service Broker to Suspend Call Processing

You can use the call suspension only for network-initiated legs.

Communicating with a Media Resource

To communicate with a media resource, the application sets the To header in the INVITE sent to Service Broker to an MRF alias for which Service Broker is configured to use an internal resource.

To instruct the MSC to use an internal media resource for user interaction, Service Broker sends a CAP ConnectToResource operation to the MSC.

Upon sending the CAP ConnectToResource, Service Broker sends a SIP INFO message to the application. The INFO message is sent through the dialog created by the application and does not include an SDP.

Figure 4-5 shows the high level architecture for an application that uses an internal media resource.

Figure 4-5 Architecture for Sending CAP CTR from Service Broker to the MSC

Sending CAP CTR from Service Broker to MSC

At this point, the application may use one of the following types of user interaction:

Play announcement
Collect information

The following sections provide information on each of these forms of user interaction.

Playing an Announcement

The following interaction between the application, Service Broker, and MSC occurs when the application requests Service Broker to play an announcement:

Service Broker sends a CAP ConnectToResource message to the MSC.
Service Broker sends a SIP INFO to the application.
The application acknowledges the receipt of the SIP INFO by sending a SIP 200 OK to Service Broker.
Finally, the application sends a SIP INFO to Service Broker. This message includes a XER, BER, or MSCML representation of the CAP PlayAnnouncement operation.

Note:

Service Broker is provided with a set of XSD files that define the structure of CAP operations in the XER format. The XSD file for each CAP phase is stored in the directory with the corresponding name in the /protocols/inap/ directory in /samples/service_controller.samples.zip. For example, the XSD file that defines the structure of CAP phase 4 operations is stored in /protocols/inap/cap4/ directory.

Notice that playing an announcement requires setting up a connection to the SRF/IP using a CAP ConnectToResource prior to the playing the announcement.

When the application sends a CAP PlayAnnouncement as an MSCML representation, the announcement is specified in the url attribute of the <audio> element. However, SS7 MRF, expects the announcement ID to be represented as an integer. Service Broker translates the MSCML's url to the announcement ID as defined in the announcement table in the configuration of the IM-SCF. See the discussion on configuring media resources parameters in the IM-SCF in Oracle Communications Service Broker Modules Configuration Guide for more information.

Service Broker receives the SIP INFO message and sends a CAP PlayAnnouncement operation to the MSC. At this point, the MSC plays an announcement to the call party.

Figure 4-6 shows the high level architecture for an application that uses an internal media resource for playing announcements.

Figure 4-6 Architecture for Using an Internal Media Resource for Playing Announcements

Using Internal Resource to Play Announcements

If the requestAnnouncementCompleteNotification parameter is set to True in the XER, when the announcement playing is completed, the MSC sends a CAP SpecializedResourceReport (SRR) message to Service Broker.

Then Service Broker sends a SIP INFO message to the application through the SIP dialog created by the application. The INFO message contains a XER, BER, or MSCML representation of the CAP SpecializedResourceReport operation. Figure 4-7 shows the architecture for sending an SRR from Service Broker to an application.

Figure 4-7 Architecture for Sending SRR from Service Broker to the Application

Sending SRR from Service Broker to Application

At this point, the application can perform one of the following actions:

Continuing the user interaction session by playing an additional announcement. Notice that to allow the application to play multiple announcements, the disconnectFromIPForbidden parameter must be set to True in the XER or BER. Otherwise the SRF connection is terminated when the announcement completes. The application plays the announcement by repeating the process of sending a SIP INFO message that contains a CAP PlayAnnouncement XER, BER, or MSCML representation.
Terminating the user interaction session, when the application terminates the user interaction session and then either allows the call to continue or rejects the call.

Figure 4-8 and Figure 4-9 show the detailed sequence diagram for an application that uses an internal media resource for playing announcement.

Figure 4-8 Application Uses an Internal Resource to Play Announcement

Using Internal Resource to Play Announcement

Figure 4-9 Application Uses an Internal Resource to Play Announcement (cont'd)

Playing an Announcement and Collecting Information

To play an announcement and collect information, the application receives the SIP INFO, acknowledges the SIP INFO with SIP 200 OK, and sends a new SIP INFO message towards Service Broker. The SIP INFO message is sent through the SIP dialog created by the application and contains a XER, BER, or MSCML representation of the CAP PromptAndCollectUserInformation (PnC) operation.

Service Broker receives the SIP INFO and sends a CAP PromptAndCollectUserInformation operation to the MSC. At this point, the MSC plays the announcement to the call party and collects user information (DTMF digits).

Notice that playing an announcement and collecting information requires setting up a connection to the SRF/IP using a CAP ConnectToResource prior to the playing the announcement and collection information.

Figure 4-10 shows the high level architecture for an application that uses an external resource for playing announcement and collecting information.

Figure 4-10 Architecture for Using an External Resource for Playing Announcements

Using External Resource to Playing Announcements

The following example shows how you can define a XER representation of a CAP PromptAndCollectUserInformation message to request Service Broker to play the announcement whose ID is 6023 and collect user information.

<Cap4>
 <promptAndCollectUserInformation>
  <collectedInfo>
   <collectedDigits>
    <maximumNbOfDigits>1</maximumNbOfDigits>
    <firstDigitTimeOut>15</firstDigitTimeOut>
    <interDigitTimeOut>5</interDigitTimeOut>
   </collectedDigits>
  </collectedInfo>
  <informationToSend>
   <inbandInfo>
    <messageID>
     <elementaryMessageID>6023</elementaryMessageID>
    </messageID>
   </inbandInfo>
  </informationToSend>
  <callSegmentID>01</callSegmentID>
 </promptAndCollectUserInformation>
</Cap4>

Alternatively, you can send a CAP PromptAndCollectUserInformation in an MSCML representation. In this case, you use the MSCML's <playcollect> tag.

In the <playcollect> tag, you can use the following attributes:

maxdigits
firstdigittimer
interdigittimer
returnkey

You need to set the elementary message ID of the announcement in the url attribute of the audio tag.

The following example shows how you can define an MSCML message to request Service Broker to play the announcement whose ID is 6023.

<?xml version="1.0" encoding="UTF-8"?>
<MediaServerControl>
   <request>
      <playcollect id='1' maxdigits='6' firstdigittimer='15000' interdigittimer='5000' returnkey='#'>
         <prompt>
            <audio url='6023'/>
         </prompt>
      </playcollect>
   </request>
</MediaServerControl>

The application can instruct Service Broker to request from the MSC a notification that the announcement starts by setting the requestAnnouncementStartedNotification parameter to True. In this case, the MSC notifies Service Broker about this event by sending to Service Broker a CAP SpecializedResourceReport (SRR).

Then Service Broker sends a SIP INFO to the application. This SIP INFO message contains a XER representation or BER representation of the CAP SpecializedResourceReport operation.

Figure 4-11 shows the architecture for sending a SIP INFO message from Service Broker to an application.

Figure 4-11 Architecture for Sending SIP INFO from Service Broker to the Application

Sending SIP INFO from Service Broker to Application

When playing the announcement and collecting user information is completed, the MSC sends a CAP PromptAndCollectUserInformation result operation that contains the information collected from the user. Then Service Broker sends a SIP INFO message to the application through the SIP dialog created by the application. The INFO message contains a XER, BER, or MSCML representation of the CAP PromptAndCollectUserInformation result operation.

Figure 4-12 shows the high level architecture for an application that receive user information.

Figure 4-12 Architecture for Sending SIP INFO to the Application

For the example of a XER representation of the CAP phase 4 PromptAndCollectUser Information Result, see "Playing an Announcement and Collecting Information".

At this point, the application can perform one of the following actions:

Continuing the user interaction session by playing an additional announcement. Notice that to continue the user interaction after the first information collection is completed, the disconnectFromIPForbidden parameter must be set to True in the XER or BER. The application can perform this action by repeating the procedure of sending a SIP INFO message that contains a CAP PromptAndCollectUserInformation XER representation as described in "Playing an Announcement and Collecting Information".
Terminating the user interaction session. The application performs this action by terminating the user interaction session. Then the application either allows the call to continue or rejects the call.

Figure 4-13 and Figure 4-14 show the detailed sequence diagram for an application that uses an internal media resource for collecting information.

Figure 4-13 Application Uses an Internal Resource for Collecting Information

Using Internal Resource to Collect Information

Figure 4-14 Application Uses an Internal Resource for Collecting Information (cont'd)

Playing a Tone

An application can request Service Broker to play a tone by sending to Service Broker a SIP INFO operation that contains a XER, BER, or MSCML representation of a CAP PlayTone operation. If the application sends a PlayTone in a XER or BER representation, In this operation, the application needs to specify to whom Service Broker should play the tone - legID or CallSegment.

Notice that while announcement playing and information collection require setting up a connection to the SRF/IP using a CAP ConnectToResource prior to the operation, playing a tone does not require setup of the user interaction session. However, the application cannot play a tone while the call segment is in an active user interaction session.

The following example shows how you can define a XER representation of a CAP PlayTone:

<?xml version="1.0" encoding="UTF-8"?>
<Cap4>
   <playTone>
      <legOrCallSegment>
         <callSegmentID>1</callSegmentID>
      </legOrCallSegment>
      <bursts></bursts>
   </playTone>
</Cap4>

The following example shows how you define an MSCML representation of a CAP PlayTone. Because MSCML does not provide any special tag for playing tones, you use the <play> tag. This tag is also used for in PlayAnnouncement operations. To distinguish between PlayTone and PlayAnnouncement, set the url attribute of the <audio> tag to tone.

<?xml version="1.0" encoding="UTF-8"?>
<MediaServerControl>
   <request>
      <play id='1'>
         <prompt><audio url='tone'/></prompt>
      </play>
   </request>
</MediaServerControl>

When you use a XER, BER, and MSCML representation of a PlayTone, Service Broker replaces the LegID depending on the leg on which the SIP INFO is received. In addition, in XER and BER, Service Broker replaces the CallSegmentID, depending on the leg on which the SIP INFO is received.