API Description for Extended Web Services

Get
Adobe Reader

Call User InterAction

The following sections provide detailed information about the Call User InterAction service capability:

Web Service

The call user interaction Web Service provides an application with functions for callbased user interaction session. This allows an application to perform dialogue handling with one or several end user using IVRs and DTMF as a means of communication.

A call user interaction session depends on an existing call session, which means that a call session must be created before any call user interaction sessions can be created.

When a call user interaction session has been created, a callUiTicket is returned. The callUiTicket is used to identify a call user interaction session.

abortAction

Abort a previously started sendInfo or sendInfoAndCollect request. Invocations of sendInfoWait and sendInfoAndCollectWait can not be aborted using this method.

Table 5-1 abortAction(callUiTicket, assignmentId)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
assignmentId	xsd:int	Identifier of the request to be aborted. The assignmentmentID was returned when sendInfo or sendInfoAndCollect was invoked.
Returns
Void.
Exceptions
CallUIException		See CallUIException.
GeneralException		See GeneralException.

close

Closes a call user interaction session. The CallUITicket is destroyed and all resources in the network are released.

Table 5-2 close(callUiTicket)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
Returns
Void.
Exceptions
CallUIException		See CallUIException.
GeneralException		See GeneralException.

createCallUserInteraction

Creates a call user interaction session. Only the session is created, which means that no announcements will be played, nor will no information be collected from the end user until additional methods are invoked.

A call user interaction session uses an ongoing call session, created by the call control Web Service. To connect a call user interaction session with an ongoing call session, the callTicket identifying the call session is used as inparameter when creating a call user interaction session.

Note that some network equipment may only allow CallUserInteraction sessions to be created under certain circumstances, for example with only one participant in the call.

The call user interaction session is identified by the returned callUiTicket.

Table 5-3 createCallUserInteraction(callTicket, participant)

Parameter Name	Type	Description
Input
callTicket	xsd:string	Ticket that identifies the call session to establish a call user interaction session on.
participant	xsd:string	Address, in URI format (tel:<address>), to the end user, which also must be a participant in the call session, to establish a call user interaction session with. Use "*" to establish call user interaction sessions with all participants in the call. See Address expressions for information on format.
Returns
createCallUserInteractionReturn	xsd:string	A ticket identifying the call user interaction 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
CallUIException		See CallUIException. This exception is raised if the participant could not be added.
GeneralException		See GeneralException.

sendInfo

Sends an announcement to an end user. The response is reported back to the application using the call user interaction listener interface.

Table 5-4 sendInfo(callUiTicket, endPoint, info, nrOfRepeats, language, serviceCode, requesterID)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction 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/CallListener`
info	tsn7:UserInformation	See UserInformation for information on format. The information to send to the IVR. Depends on the IVR equipment used to play announcements. For example, this may be the ID of a prerecorded announcement or a text to be announced.
nrOfRepeats	xsd:int	How many times the announcement message should be repeated.
language	xsd:string	Indicator for language to be used in the announcement. Depends on the IVR equipment used.
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	Id for this unique request in the call user interaction session. Also referred to as assignmentID.
Exceptions
CallUIException		See CallUIException. This exception is raised if the participant could not be added.
GeneralException		See GeneralException.

sendInfoAndCollect

Plays an announcement to and collects information from an end user. The application execution continues without waiting for the participant to enter information. The information collected from the user is returned using the Web Service defined and registered by the application, see sendInfoResult.

Table 5-5 sendInfoAndCollect(callUiTicket, endPoint, info, minimumLength, maximumLength, endSequence, startTimeoutSeconds, interCharTimeoutSeconds, language, serviceCode, requesterID)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction 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/CallUserInteractionListener`
info	tsn7:UserInformation	See UserInformation for information on format. The information to send to the IVR. Depends on the IVR equipment used to play announcements. For example, this may be the ID of a prerecorded announcement or a the text to be announced.
minimumLength	xsd:int	The minimum length of input given by the end user 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.
maximumLength	xsd:int	The maximum length of input allowed for the end user. When maximumLength digits have been collected, the request is considered successful and the result is sent back to the application.
endSequence	xsd:string	The character or characters that will terminate a variable length input (for example a phone number). 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.
startTimeoutSeconds	xsd:int	The first character timeout timer. If no information has been collected from the end user before this timer releases, the input is considered to be faulty.
interCharTimeoutSeconds	xsd:int	The timeout timer between characters collected from the end user. If this timer releases, the input is considered to be faulty if the total length of the input is less than minimum length, otherwise it is considered to be valid.
language	xsd:string	Indicator for language to be used in the announcement. Depends on the IVR equipment used.
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	Id for this unique request in the call user interaction session. Also referred to as assignmentID.
Exceptions
CallUIException		See CallUIException. This exception is raised if the participant could not be added.
GeneralException		See GeneralException.

sendInfoAndCollectWait

Plays an announcement to and collects information from an end user. The application execution holds until the information is collected from the end user or a timeout is triggered.

Table 5-6 sendInfoAndCollectWait(callUiTicket, info, minimumLength, maximumLength, endSequence, startTimeoutSeconds, interCharTimeoutSeconds, language, waitTimeoutSeconds, serviceCode, requesterID)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
info	tsn7:UserInformation	See UserInformation for information on format. The information to send to the IVR. Depends on the IVR equipment used to play announcements. For example, this may be the ID of a prerecorded announcement or a the text to be announced.
minimumLength	xsd:int	The minimum length of input given by the end user 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.
maximumLength	xsd:int	The maximum length of input allowed for the end user. When maximumLength digits have been collected, the request is considered successful and the result is sent back to the application.
endSequence	xsd:string	The character or characters that will terminate a variable length input (for example a phone number). 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.
startTimeoutSeconds	xsd:int	The first character timeout timer. If no information has been collected from the end user before this timer releases, the input is considered to be faulty.
interCharTimeoutSeconds	xsd:int	The timeout timer between characters collected from the end user. If this timer releases, the input is considered to be faulty if the total length of the input is less than minimum length, otherwise it is considered to be valid.
language	xsd:string	Indicator for language to be used in the announcement. Depends on the IVR equipment used.
waitTimeoutSeconds	xsd:int	The time to wait for end user input to complete. If this time expires, a CallUIException with error code RESOURCE_TIMEOUT will be thrown.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
sendInfoAndCollectWaitReturn	xsd:string	Input collected from the end user.
Exceptions
CallUIException		See CallUIException.
GeneralException		See GeneralException.

sendInfoWait

Plays an announcement to an end user. The application execution holds until the end user the announcement is played to terminates the call, the announcement has been played (including repeats), or a timer expires.

Table 5-7 sendInfoWait(callUiTicket, info, nrOfRepeats, waitTimeoutSeconds, language, serviceCode, requesterID)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
info	tsn7:UserInformation	See UserInformation for information on format. The information to send to the IVR. Depends on the IVR equipment used to play announcements. For example, this may be the ID of a prerecorded announcement or a the text to be announced.
nrOfRepeats	xsd:int	The number of times the announcement shall be repeated. Zero (0) indicates that the announcement shall be repeated until the end user terminates the call or the timer expires.
waitTimeoutSeconds	xsd:int	The time to wait for and end user to terminate the call user interaction session. If this time expires, a CallUIException with error code RESOURCE_TIMEOUT will be thrown.
language	xsd:string	Indicator for language to be used in the announcement. Depends on the IVR equipment used.
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
CallUIException		See CallUIException.
GeneralException		See GeneralException.

Exceptions

CallUIException

Exceptions of this type are raised when there are error conditions related to the call user interaction Web Service. Other error conditions are reported using the exception GeneralExcepetion.

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. Defines which type of information to send to the IVR.

Table 5-8

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

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

infoData	xsd:string	Data to be sent.
infoDataEncodingScheme	xsd:string	Encoding scheme.

Listener interface

The call 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 call user interaction Web Service, the responses are delivered according to this interface.

deactivate

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

Table 5-11 deactivate(callUiTicket)

Parameter Name	Type	Description
Input
callUITicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
Returns
Void.
Exceptions
-

sendInfoError

Errors related to call user interaction sessions are reported using this method.

Table 5-12 sendInfoError(callUiTicket, participant, assignmentId, CallUIErrorCode errorCode)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
participant	xsd:string	The end user for which the error is related.
assignmentId	xsd:int	The ID identifying the request. This ID was retrieved when the application invoked sendInfo or sendInfoAndCollect in the call user interaction Web Service.
errorCode	CallUIErrorCode	See CallUIErrorCode. Type of error.
Returns
Void.
Exceptions
-

sendInfoResult

Results of call user interaction dialogues initiated by invocation of the asynchronous methods sendInfo and sendInfoAndCollect are reported using this method.

Table 5-13 sendInfoResult(callUiTicket, participant, assignmentId, CallUIResultCode resultCode, info)

Parameter Name	Type	Description
Input
callUiTicket	xsd:string	Identifier for the call user interaction session retrieved when createCallUserInteraction was invoked.
participant	xsd:string	The end user for which the error is related.
assignmentId	xsd:int	The ID identifying the request. This ID was retrieved when the application invoked sendInfo or sendInfoAndCollect in the call user interaction Web Service.
resultCode	CallUIErrorCode	See CallUIResultCode. Type of result.
info	xsd:string	The user input if it was a sendInfoAndCollect request and result code is INFO_COLLECTED, otherwise empty string. The format of this string is determined by the criteria given to the sendInfoAndCollect method.
Returns
Void.
Exceptions
-

Complex data types

CallErrorEvent

Array of call error codes, see CallUIErrorCode for information on the individual records in the array.

CallUIErrorCode

Enumeration with one of the following values:

ERROR_UNDEFINED
ILLEGAL_INFO
ID_NOT_FOUND
RESOURCE_UNAVAILABLE
ILLEGAL_RANGE
IMPROPER_USER_RESPONSE
ABANDON
RESOURCE_TIMEOUT

CallUIResultCode

Enumeration with one of the following values:

RESULT_UNDEFINED
INFO_SENT
INFO_COLLECTED
NO_INPUT
TIMEOUT