API Description for Extended Web Services

Get
Adobe Reader

Messaging User Interaction

The following sections provide detailed information about the Messaging User Interaction service capability:

Web Service

The Messaging User interaction Web Service provides an application with functions to interact with end users. The application interacts with end users through text messages, for example SMS or USSD messages.

SMS based user interaction provides application initiated SMSes with a transaction ID to connect requesting/prompting SMSes with end user's replies.

USSD messages from an application can be purely informative or they can prompt the end user to reply. USSD messages can also be used by the end user to initiate service sessions with applications. When initiating service sessions or replying to an application generated USSD message, the end user can only use the terminal's key set (0-9, *, #). The application can use any type of character supported by the end user's terminal.

createUI

Creates a user interaction session with a terminal.

Table 8-1 createUI(participant)

Parameter Name	Type	Description
Input
participant	xsd:string	Address of the telephony terminal in URI format (tel:<address>).
Returns
uiSessionTicket	xsd:int	Identifier for the session. Both this identifier and the ticket identifying the login session, see applicationLogin, (supplied in the security header of the call) must be synchronized in subsequent calls.
Exceptions
UIException		See UIException.
GeneralException		See GeneralException.

addNetworkUIListener

Subscribes for notifications on events related terminal initiated user interaction sessions.

The combination of a matching aPartyAddressExpression, bPartyAddressExpression and userInteractionCode triggers the Web Service located at endpoint.

Table 8-2 addNetworkUIListener(endPoint, aPartyAddressExpression, bPartyAddressExpression, userInteractionCode, serviceCode, requesterID)

Parameter Name	Type	Description
Input
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is `http://www.acompany.com:8080/axis/services/UserInteractionListener`
aPartyAddressExpression	xsd:string	The originating address or address range for which the notification is requested in URI format (tel:<address>). Wildcards, like * and ? are supported.
bPartyAddressExpression	xsd:string	Destination address or address range for which the notification is requested in URI format (tel:<address>). Only useful in cases when the destination is other than the application, for example when listening to message based user interaction sessions.
userInteractionCode	xsd:string	A 2-digit code indicating the UI to be triggered. Defined by the operator.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
addNetworkUIListenerReturn	xsd:string	An ID for the listener. This ID is used when disabling the notification. See removeNetworkUIListener.
Exceptions
UIException		See UIException.
GeneralException		See GeneralException.

closeUI

Terminates a user interaction session.

Table 8-3 closeUI(uiTicket)

Parameter Name	Type	Description
Input
uiSessionTicket	xsd:string	ID of the user interaction session, retrieved when it was created. See createUI.
Returns
Void
Exceptions
UIException		See UIException.
GeneralException		See GeneralException.

removeNetworkUIListener

Removes a previously registered network triggered user interaction listener.

Table 8-4 removeNetworkUIListener(notificationTicket, requesterID)

Parameter Name	Type	Description
Input
listenerID	xsd:string	ID of the listener, retrieved when it was registered. See addNetworkUIListener.
requesterID	xsd:string	The application ID as given by the operator.
Returns
Void
Exceptions
UIException		See UIException.
GeneralException		See GeneralException.

sendInfo

Send predefined information via SMS or USSD to the telephony terminal. Asynchronous method. The result will be notified on the user interaction listener.

Table 8-5 sendInfo(uiTicket, endPoint, info, noRepeats, language, serviceCode, requesterID)

Parameter Name	Type	Description
Input
uiTicket	xsd:string	Ticket identifying the user interaction session. The ID was retrieved when createUI or processUINotification was invoked.
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is `http://www.acompany.com/axis/services/MessagingListener`
info	impl:UserInformation	Defines the type of user interaction resource to be used. See UserInformation.
noRepeats	xsd:int	The number of times the message, defined in the parameter info, shall be repeated. For message based user interaction sessions, this parameter is ignored.
language	xsd:string	Language code for the message. Defined by the operator.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendInfoReturn	xsd:int	Ticket to identify the request-response pairs within the user interaction session.
Exceptions
UIException		See UIException.
GeneralException		See GeneralException.

sendInfoWait

Send predefined information via SMS or USSD to the telephony terminal. Synchronous method.

Table 8-6 sendInfoWait(uiTicket, info, noRepeats, language, waitTimeoutSeconds, serviceCode, requesterID)

Parameter Name	Type	Description
Input
uiTicket	xsd:string	Ticket identifying the user interaction session. The ID was retrieved when createUI or processUINotification was invoked.
info	impl:UserInformation	Defines the type of user interaction resource to be used. See UserInformation.
noRepeats	xsd:int	The number of times the message, defined in the parameter info, shall be repeated. For message based user interaction sessions, this parameter is ignored.
language	xsd:string	Language code for he message. Defined by the operator.
waitTimeoutSeconds	xsd:int	The time to wait for the message to be delivered to the telephony terminal. An UIException exception occurs if this time is overdue.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
void
Exceptions
UIException		See UIException.
GeneralException		See GeneralException.

sendInfoAndCollect

Send predefined information to the telephony terminal via SMS or USSD and collect user input from the end user via SMS or USSD. Asynchronous method. The result, containing user input, will be notified on the user interaction listener.

Table 8-7 sendInfoAndCollect(uiTicket, endPoint, info, minimumLength, maximumLength, endSequence, startTimeoutSeconds, interCharTimeoutSeconds, language, serviceCode, requesterID)

Parameter Name	Type	Description
Input
uiTicket	xsd:string	Ticket identifying the user interaction session. The ID was retrieved when createUI or processUINotification was invoked.
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is `http://www.acompany.com/axis/services/MessagingListener`
info	impl:UserInformation	Defines the type of user interaction resource to be used. See UserInformation.
minimumLength	xsd:int	The minimum length of input for this request to be considered successful. If a timeout or endSequence is encountered before the minimum length is met, it is considered an error. For message based user interaction sessions, this parameter is ignored.
maximumLength	xsd:int	The maximum length of input. When maximumLength digits have been collected, the request is considered successful, and sent back to the application. For message based user interaction sessions, this parameter is ignored.
endSequence	xsd:string	The character or characters that will terminate a variable length input. When this sequence is encountered in the input, and the total number of characters (including end sequence) is greater or equal to minimum length, the request is considered successful and sent back to the application. If the total length is less than minimum length it is considered an error. For message based user interaction sessions, this parameter is ignored.
startTimeoutSeconds	xsd:int	The first character timeout timer. If no character has been input before this timer releases, the input is considered an error. For message based user interaction sessions, this parameter is ignored.
interCharTimeoutSeconds	xsd:int	The timeout timer between characters. If this timer releases, the input is considered an error if the total length of the input is less than minimum length, otherwise a success. For message based user interaction sessions, this parameter is ignored.
language	xsd:string	Language code for the message. Defined by the operator.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendInfoAndCollectReturn	xsd:int	Ticket to identify the request-response pairs.
Exceptions
MessagingException		See UIException.
GeneralException		See GeneralException.

sendInfoAndCollectWait

Send predefined information to the telephony terminal via SMS or USSD and collect user input from the end user via SMS or USSD. Synchronous method.

Table 8-8 sendInfoAndCollectWait(uiTicket, info, minimumLength, maximumLength, endSequence, startTimeoutSeconds, interCharTimeoutSeconds, language, waitTimeoutSeconds, serviceCode, requesterID)

Parameter Name	Type	Description
Input
uiTicket	xsd:string	Ticket identifying the user interaction session. The ID was retrieved when createUI or processUINotification was invoked.
info	impl:UserInformation	Defines the type of user interaction resource to be used. See UserInformation.
minimumLength	xsd:int	The minimum length of input, for this request to be considered successful. If a timeout or endSequence is encountered before the minimum length is met, it is considered an error. For message based user interaction sessions, this parameter is ignored.
maximumLength	xsd:int	The maximum length of input. When maximumLength digits have been collected, the request is considered successful, and sent back to the application.For message based user interaction sessions, this parameter is ignored.
endSequence	xsd:string	The character or characters that will terminate a variable length input. When this sequence is encountered in the input, and the total number of characters (including end sequence) is greater or equal to minimum length, the request is considered successful and sent back to the application. If the total length is less than minimum length it is considered an error. For message based user interaction sessions, this parameter is ignored.
startTimeoutSeconds	xsd:int	The first character timeout timer. If no character has been input before this timer releases, the input is considered an error. For message based user interaction sessions, this parameter is ignored.
interCharTimeoutSeconds	xsd:int	The timeout timer between characters. If this timer releases, the input is considered an error if the total length of the input is less than minimum length, otherwise a success. For message based user interaction sessions, this parameter is ignored.
language	xsd:string	Language code for he message. Defined by the operator.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendInfoAndCollectWait Return	xsd:string	Collected end user input.The format of this string is determined by the criteria given to the sendInfoAndCollect method.
Exceptions
MessagingException		See UIException.
GeneralException		See GeneralException.

Exceptions

UIException

Exception of this type are raised when there are error conditions related to the Messaging User Interaction Web Service. Other error conditions are reported using GeneralException.

GeneralException

This exception is raised when the applications session has expired or there are communication problems with the underlying platform.

Complex data types

UserInformation

Name-value pair, defining the type of user interaction resource to be used. This data is operator defined.

Table 8-9

Name	Type	Description
userInformationType	tns7:UserInformationType	Name part of the name-value pair. See UserInformationType.
value	xsd:anyType	Value part of the name-value pair.

UserInformationType

User information types. Defines the type of data defined in UserInformation. Enumeration (xsd:string) with the following values.

Table 8-10

Value	Description
UI_INFO_ID	Use parameter value in datatype UserInformation as an ID of a message defined in an underlying network node. Parameter value in UserInformation shall be xsd:string.
UI_INFO_DATA	Use parameter value in datatype UserInformationData as data to be distributed to an underlying network node.
UI_INFO_ADDRESS	Use parameter value in datatype UserInformation as an address to a message defined in an underlying network node. Parameter value in UserInformation shall be xsd:string.
UI_INFO_BIN_DATA	Use parameter value in datatype UserInformation as binary data to be sent to and underlying network node. Parameter value in UserInformation shall be xsd:string.

UserInformationData

Holder of data to send to an underlying network node.

Table 8-11

Name	Type	Description
infoData	xsd:string	Data to be sent.
infoDataEncodingScheme	xsd:string	For message based user interaction sessions, this parameter is ignored, however it must not be null.

UIEventDataTypeCode

Defines the type of data retrieved. Enumeration (xsd:string) with the following values.

Table 8-12

Value	Description
EVENT_DATA_TYPE_UNDEFINED	The format of the data is undefined.
EVENT_DATA_TYPE_UNSPECIFIED	The format of the data is unspecified.
EVENT_DATA_TYPE_TEXT	The data is in text format.

Listener interface

The Messaging User Interaction listener interface defines the methods that the underlying platform invokes on a Web Service that is implemented by an application. When an application performs asynchronous requests from the Messaging User Interaction Web Service, the responses are delivered according to this interface.

deactivate

Used by the underlying system to inform the application that the session identified by uiSessionTicket is no longer valid. The application can not use the session no more.

Table 8-13 deactivate(assignmentId)

Parameter Name	Type	Description
Input
assignmentId	xsd:string	ID of the session. The ID was returned when createUI was invoked.
Returns
Void.
Exceptions
-

sendInfoResult

Successful responses to invocations of asynchronous are reported using this method.

Table 8-14 sendInfoResult(assignmentId, resultCode, collectedInfo)

Parameter Name	Type	Description
Input
assignmentId	xsd:int	ID of the session. The ID was returned when createUI was invoked.
resultCode	impl:UIResultCode	Defines the result of an invocation of the method sendInfo (page 49) or sendInfoAndCollect (page 52). See UIResultCode.
collectedInfo	xsd:string	The user input if it was a sendInfoAndCollect request and result code is INFO_COLLECTED (see UIResultCode), otherwise empty string. The format of the string is determined by the criteria given to in sendInfoAndCollect or sendInfoAndCollectWait.
Returns
Void.
Exceptions
-

sendInfoError

Failed responses to invocations of asynchronous are reported using this method.

Table 8-15 sendInfoError(assignmentId, errorCode, errorMsg)

Parameter Name	Type	Description
Input
assignmentId	xsd:int	ID of the session. The ID was returned when createUI was invoked.
errorCode	xsd:string	Error code.
errorMsg	xsd:string	Textual error description.
Returns
Void.
Exceptions
-

Complex data types

UIResultCode

Defines the result of an invocation of the method sendInfo or sendInfoAndCollect.

Enumeration (xsd:string) with the following values.

Table 8-16

Value	Description
RESULT_UNDEFINED	The result of the operation is unknown.
INFO_SENT	Information sent to the telephony terminal.
INFO_COLLECTED	Information collected from the user of the telephony terminal.
NO_INPUT	No input collected from the user of the telephony terminal.
TIMEOUT	The request to collect information from the user of the telephony terminal timed out. The timeout value is defined by the operator.

Network Listener interface

The Messaging User Interaction Network Listener interface defines the methods that the underlying platform invokes on a Web Service that is implemented by an application.

In contrast to the Listener interface it listens to user interaction sessions initiated from the network, an ultimately from an telephony terminal.

That is, When an application performs asynchronous requests from the Messaging User Interaction Web Service, the responses are delivered according to this interface.

deactivate

Used by the underlying system to inform the application that the session identified by uiSessionTicket is no longer valid. The application can not use the session no more.

Table 8-17 deactivate(notificationTicket)

Parameter Name	Type	Description
Input
assignmentId	xsd:string	ID of the session. The notification registration that caused this notification. The ID was returned when createUI was invoked.
Returns
Void.
Exceptions
-

processUINotification

Successful responses to invocations of asynchronous are reported using this method.

Table 8-18 processUINotification(notificationTicket, uiTicket, originator, destination, userInteractionCode, dataTypeCode, dataString)

Parameter Name	Type	Description
Input
notificationTicket	xsd:string	ID of the session. The ID was returned when addNetworkUIListener was invoked.
uiTicket	xsd:string	ID of the session.
originator	xsd:string	Address, in URI format (tel:<address>), of the telephony terminal that initiated the user interaction session.
destination	xsd:string	Address, in URI format (tel:<address>), of the application or service.
userInteractionCode	xsd:string	A 2-digit code indicating the UI that was triggered. Defined by the operator.
dataTypeCode	impl:UIEventDataTypeCode	Defines the type of data retrieved. See UIEventDataTypeCode.
dataString	xsd:string	The data sent from the underlying network node.
Returns
Void.
Exceptions
-