4 Developing a SIP User Interaction Application

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

Providing 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 two forms of user interaction exist:

• Playing an announcement, when an announcement is played to a call party

• Information collection, when an announcement is played to a call party and DTMF digits are collected from the call party

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 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

About the Media Resource Table

Service Broker has a media resource table configuration. When receiving the INVITE from an 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 determines whether an external or an internal media resource is used

  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.

  When an external resource is used, Service Broker uses a CAP EstablishTemporaryConnection (ETC) operation. When an internal resource is used, Service Broker uses a CAP ConnectToResource (CTR) operation.

• 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

When the application receives the SIP 200 OK message, the application updates the SDP towards 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 towards 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 towards the call initiating side (pre-call announcement scenario).

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

Based on the specific MRF alias, Service Broker performs one of the following CAP operations:

• CAP EstablishTemporaryConnection (ETC)

• CAP ConnectToResource (CTR)

Suspending Call Processing for Pre-Call Announcements

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 ERB-R Answer from the leg.

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 (see "Terminating a User Interaction Session" for more information), 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 and Figure 4-5 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

Figure 4-5 Instructing Service Broker to Suspend Call Processing (Cont'd)

You can use this call processing suspension mechanism with both internal and external media resources. However, you can use the call suspension only for network-initiated legs.

Using an External Media Resource

To use an external 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 external resource.

To instruct an MSC to use an external media resource for user interaction, Service Broker sends a CAP ETC operation towards the MSC. This operation instructs the MSC to set up an ISUP connection towards an Intelligent Peripheral (IP) node. When the IP is invoked, it sends a CAP AssistRequestInstructions (ARI) operation towards Service Broker.

Figure 4-6 and Figure 4-7 show the high level architecture for an application that uses the external resource.

Figure 4-6 Architecture for Sending CAP ETC from Service Broker to the MSC

Service Broker receives the CAP ARI and sends a SIP INFO message towards the application. The INFO message is sent through the dialog created by application. Service Broker attaches a XER representation of the CAP ARI to the SIP INFO body.

Figure 4-7 Architecture for Sending SIP INFO from Service Broker to the Application (CAP ARI)

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

• Play announcement

• Collect information

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

Playing an Announcement

To play an announcement, the application receives a SIP INFO that contains the CAP ARI, acknowledges the SIP INFO with SIP 200 OK, and sends a new SIP INFO message towards Service Broker. The application sends SIP INFO through the SIP dialog created by the application. The SIP INFO message contains a XER representation of a CAP PlayAnnouncement operation.

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

Figure 4-8 and Figure 4-9 show the high level architecture for an application that uses an external resource for playing announcement.

Figure 4-8 Architecture for Sending SIP INFO from the Application to Service Broker (CAP PA)

Figure 4-9 Architecture for Sending SDR from Service Broker to the Application (CAP SRR)

The following example shows a XER representation of CAP phase 4 PlayAnnouncement. In this example, the message ID is 6000.

<Cap4>
 <playAnnouncement>
  <informationToSend>
   <inbandInfo>
    <messageID>
     <elementaryMessageID>6000
     </elementaryMessageID>
    </messageID>
   </inbandInfo>
  </informationToSend>
 </playAnnouncement>
</Cap4>

When the announcement playing is completed, the IP sends a CAP SpecializedResourceReport (SRR) operation towards Service Broker. Service Broker then sends SIP INFO towards the application through the SIP dialog created by the application. The INFO contains a XER representation of the CAP SpecializedResourceReport operation.

The following example shows a XER representation of CAP phase 4 SpecializedResourceReport.

<Cap4>
 <specializedResourceReport>
  <allAnnouncementsComplete/>
 </specializedResourceReport>
</Cap4>

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

• Continuing the user interaction session by playing additional announcement. The application performs this action by repeating the process of sending a SIP INFO message that contains a CAP PlayAnnouncement XER representation as described in "Playing an Announcement".

• 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

Terminating a User Interaction Session

To terminate a user interaction session, the application takes the following actions:

• Sending a SIP BYE request through the dialog created by the application (this is the MRF dialog).

• Updating the SDP towards the initiating side. This is done by sending a SIP 183 SESSION PROGRESS or a SIP reINVITE towards the initiating side. The SIP 183 SESSION PROGRESS or SIP reINVITE contain SDP with the “i” attribute set to “0”.

Upon receiving the SIP 183 SESSION PROGRESS or SIP reINVITE message, Service Broker sends a CAP DisconnectForwardConnection (DFC) operation towards the MSC.

Figure 4-10 shows the high level architecture for an application that terminates user interaction session.

Figure 4-10 Architecture for Terminating a User Interaction Session by the Application

Figure 4-11 and Figure 4-12 show the detailed sequence diagram of the application that uses an external media resource for playing announcement.

Figure 4-11 Application Uses External Resource for Playing Announcements

Figure 4-12 Application Uses External Resource for Playing Announcement (cont'd)

Playing an Announcement and Collecting Information

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

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

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

Figure 4-13 Architecture for Sending SIP INFO from the Application to Service Broker (CAP PnC)

The following example shows a XER representation of CAP PromptAndCollectUserInformation

<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>

When the user interaction is started, that is an announcement is played, the IP sends a CAP SpecializedResourceReport (SRR) operation towards Service Broker. Service Broker then sends a SIP INFO message towards the application through the SIP dialog created by application. The INFO message contains a XER representation of CAP SpecializedResourceReport operation.

Note:

IP sends SRR only when this operation is requested in the PromptAndCollectUserInformation operation using the RequestAnnouncementStartedNotification set to "true".

Figure 4-14 Architecture for Sending SIP INFO from Service Broker to the Application (CAP SRR)

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

Figure 4-15 shows the high level architecture for an application receiving user information.

Figure 4-15 Architecture for Sending SIP INFO to the Application (CAP PnC Result)

The following example shows a XER representation of CAP PromptAndCollectUserInformation result.

<Cap4>
 <promptAndCollectUserInformationResult>
  <digitsResponse>2001</digitsResponse>
 </promptAndCollectUserInformationResult> 
</Cap4>

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

• To continue the user interaction session by playing additional announcement with or without information collection. The application performs this action by repeating the procedure of sending a SIP INFO message containing a CAP PlayAnnouncement or PromptAndCollectUserInformation XER representation as described in "Playing an Announcement" and "Playing an Announcement and Collecting Information".

• To terminate 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-16 and Figure 4-17 show the detailed sequence diagram for an application that uses an external media resource for collecting information.

Figure 4-16 Application Uses an External Resource for Collecting Information

Figure 4-17 Application Uses an External Resource for Collecting Information (cont'd)

Using an Internal Media Resource

To use an internal 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 towards the MSC.

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

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

Figure 4-18 Architecture for Sending CAP CTR from Service Broker to the 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

To play an announcement, the application receives a SIP INFO message, 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 representation of the CAP PlayAnnouncement operation.

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

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

Figure 4-19 Architecture for Using an Internal for Playing Announcements

For the example of a XER representation of CAP phase 4 PlayAnnouncement, see "Playing an Announcement".

When the announcement playing is completed, the MSC sends a CAP SpecializedResourceReport (SRR) message towards Service Broker. Then Service Broker sends a SIP INFO message towards the application through the SIP dialog created by the application. The INFO message contains a XER representation of the CAP SpecializedResourceReport operation. Figure 4-20 shows the architecture for sending an SRR from Service Broker to an application.

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

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

• Continuing the user interaction session by playing additional announcement. The application performs this action by repeating the process of sending a SIP INFO message that contains a CAP PlayAnnouncement XER representation as described in "Playing an Announcement".

• 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-21, Figure 4-22, and Figure 4-23 show the detailed sequence diagram for an application that uses an internal media resource for playing announcement.

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

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

Figure 4-23 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 representation of the CAP PromptAndCollectUserInformation (PnC) operation.

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

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

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

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

When user interaction is started, that is an announcement is played, the MSC sends a CAP SpecializedResourceReport (SRR) operation towards Service Broker. Service Broker then sends a SIP INFO towards the application through the SIP dialog created by the application. The INFO message contains a XER representation of the CAP SpecializedResourceReport operation. Figure 4-25 shows the architecture for sending a SIP INFO message from Service Broker to an application.

Figure 4-25 Architecture for Sending SIP INFO from Service Broker to the 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 towards the application through the SIP dialog created by the application. The INFO message contains a XER representation of the CAP PromptAndCollectUserInformation result operation.

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

Figure 4-26 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 additional announcement. 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 as described in "Terminating a User Interaction Session".

Figure 4-27, Figure 4-28, and Figure 4-29 show the detailed sequence diagram for an application that uses an internal media resource for collecting information.

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

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

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

SIP MRF Integration for User Interaction Functionality

Service Broker enables a SIP application to use a SIP MRF to provide user interaction functionality. To do so, the application creates an MRF dialog as described in "Using an External Media Resource" and "Using an Internal Media Resource".

Depending on the MRF alias used by the application, Service Broker sends a CAP EstablishTemporaryConnection or CAP ConnectToResource towards the MSC. The EstablishTemporaryConnection or ConnectToResource is set with a destination number as configured in the Service Broker's Media resources table.

The MSC sends an ISUP IAM towards a Media Gateway Controller (MGC) that creates a SIP dialog towards the SIP MRF.

Figure 4-30 shows the high level architecture for MRF integration.

Figure 4-30 Architecture for MRF Integration

From this point, the MRF exchanges information (for example, voiceXML) with the application using a dedicated interface (for example, HTTP).

Using this method, the application should correlate the HTTP session with the SIP MRF dialog created towards Service Broker. This is done using the alias used by the application and propagated by Service Broker through the MSC and MGC towards the MRF.

Figure 4-31 and Figure 4-32 show the detailed sequence diagram of an application that uses a SIP MRF for user interaction.

Figure 4-31 Application Uses a SIP MRF for User Interaction

Figure 4-32 Application Uses a SIP MRF for User Interaction (cont'd)