8 Web Service interface definition

29.199-023GPPOpen Service Access (OSA)Parlay X web servicesPart 2: Third party callTS

8.1 Interface: ThirdPartyCall

This interface provides the ability to setup a call session, add and delete a call participant, transfer a call participant from one call session into another call session, determine the status of an individual call participant or a complete call session, and finally to end a call session.

8.1.1 Operation: MakeCallSession

The invocation of MakeCallSession requests to set-up a call session between two addresses, a first CallParticipant (“A-Party”) and a second CallParticipant (“B-Party”), provided that the invoking application is allowed to connect them. Optionally, the caller’s (“A-Party’s”) name is provided. Optionally a call session with only a single CallParticipant (“A-party”) can be set-up, for example to play media to the call participant using mediaCall capabilities (e.g. playMedia).Optionally the application can also indicate the charging information (Charging). Optionally, the media type(s) to be used for the participants in the call session can be requested (MediaInfo). A service policy details if multimedia application control is supported. If the parameter MediaInfo is omitted, the media type(s) shall be negotiated by the underlying network. A CallSessionIdentifier is returned on invocation of the MakeCallSession. This CallSessionIdentifier may be used to retrieve the call session status for all the call participants including their media type information with the operation getCallSessionInformation. With the operation getCallParticipantInformation this information may be retrieved for a single call participant.

During call set-up, the first CallParticipant (“A-Party”) might wait for the second CallParticipant (“B-Party”) to answer the call hearing ringback tone. MakeCallSession creates a call session with one or two call participants and generates a new CallSessionIdentifier which is identified by the string returned in the MakeCallSessionResponse operation. The invocation returns as soon as the request is received by the system, i.e. the actual call session is established asynchronously.

In order to receive the information on call status the application has to explicitly invoke the GetCallSessionInformation operation for the CallSessionIdentifier returned.

8.1.1.1 Input message: MakeCallSessionRequest

Part name

Part type

Optional

Description

CallParticipants

xsd:anyURI[1..2]

No

It contains the address of the first participant, and if supplied the second participant, involved in the call session.

CallingParticipantName

xsd:string

Yes

It contains the name of the caller, e.g. the name on whose behalf the call session is being established.

Charging

common:ChargingInformation

Yes

Charge to apply to the call session

MediaInfo

common: MediaInfo [0..unbounded]

Yes

It identifies one or more media type(s) for the call, i.e. the media type(s) to be applied to the participants in the call session. For each media type the media direction: incoming, outgoing, or bidirectional shall be indicated. An empty array shall have the same meaning as if the parameter is omitted. If the parameter MediaInfo is omitted, the media type(s) shall be negotiated by the underlying network.

ChangeMediaNotAllowed

xsd: boolean

No

If true, no call participant (user) in the call will be permitted to change media type during the call. If false the end user may change media type after the call is established as no network protection mechanism is set up to prevent participant (end user) initiated change of media type.

8.1.1.2 Output message : MakeCallSessionResponse

Part name

Part type

Optional

Description

CallSessionIdentifier

xsd:string

No

It identifies the specific call session created

8.1.1.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0008 – Charging not supported.
  • POL0011 – Media type not supported
  • POL0012 – Too many description entries specified
  • POL0013 – Addresses duplication.

8.1.1a Operation: AddCallParticipant

The invocation of AddCallParticipant requests to add a call participant to an existing call session.
The AddCallParticipant operation takes two mandatory parameters, the first being the call session identifier to which the participants should be added, and the second being the participant to add (contains the URI of the participant). Optionally, the media type(s) that shall be added for the specific call participant may be requested using MediaInfo.
If the parameter MediaInfo is omitted, the media type(s) shall be negotiated by the underlying network. The call session or call participant status, including information on media types, can be retrieved using the operations getCallParticipantInformation, and getCallSessionInformation.

All occurrences of invalid call session or participant address shall result in an invalid input value exception.

8.1.1a.1 Input Message : AddCallParticipantRequest

Part name

Part type

Optional

Description

CallSessionIdentifier

xsd:string

No

It identifies the existing call session. This must be a non-null value as it identifies a pre-existing call session in the network

CallParticipant

xsd:anyURI

No

It contains the address of the user to add to the existing call session identified by the CallSessionIdentifier

MediaInfo

common: MediaInfo [0..unbounded]

Yes

It identifies one or more media type(s) for the participant to be added in the call session. For each media type the media direction: incoming, outgoing, or bidirectional shall be indicated. An empty array shall have the same meaning as if the parameter is omitted.If the parameter MediaInfo is omitted, the media type(s) shall be negotiated by the underlying network.

8.1.1a.2 Output message : AddCallParticipantResponse

Part name

Part type

Optional

Description

None

8.1.1a.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0261 – Call Session already terminated.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0011 – Media type not supported
  • POL0240 – Too many participants. – from 3GPP TS 29.199-12 [7]

8.1.1b Operation: TransferCallParticipant

The invocation of TransferCallParticipant enables a call transfer, effectively transferring a call participant from one call session into another call session.

The TransferCallParticipant method takes three parameters, the first being the call session identifier (destination call session) where the participants should be moved to and the second being the source call session where the participant to transfer is currently located. The third parameter is to identify the call participant to transfer (contains the URL of the participant). Upon completion of the TransferCallParticipant operation, the call participant is implicitly deleted from the source call session.

In transferring the call participant to the new destination call session, the participant information is not affected. When, as a result of transferring a call participant, the source call session is left without any call participant, the source call session is terminated.

All occurrences of invalid call session or participant address shall result in an invalid input value exception

8.1.1b.1 Input Message : TransferCallParticipantRequest

Part name

Part type

Optional

Description

DestinationCallSessionIdentifier

xsd:string

No

It identifies the existing target call session to which the call participant to transfer shall be moved.

SourceCallSessionIdentifier

xsd:string

No

It identifies the existing source call session, which contains the call participant to transfer.

CallParticipant

xsd:anyURI

No

This is the address of the participant to be transferred from the source call session, which is identified by the SourceCallSessionIdentifier.

8.1.1b.2 Output message : TransferCallParticipantResponse

Part name

Part type

Optional

Description

None

8.1.1b.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0261 – Call Session already terminated.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0240 – Too many participants. – from 3GPP TS 29.199-12 [7]

8.1.2 Operation: GetCallParticipantInformation

The invocation of GetCallParticipantInformation retrieves the current call participant status, CallParticipantInformation, of the call participant identified by CallParticipant, within the call session identified by the CallSessionIdentifier. This method can be invoked multiple times by the application even if the call has already ended. However, after the call has ended, status information will be available only for a limited period of time that is specified in the service policy ‘StatusRetentionTime’.

The getCallParticipantInformation method takes two parameters into the method, the first being the call session identifier where the participants information should be retrieved and the second being the call participant identifier (contains the URL of the participant).

All occurrences of invalid call session or call participant address shall result in an invalid input value exception

8.1.2.1 Input message: GetCallParticipantInformationRequest

Part name

Part type

Optional

Description

CallSessionIdentifier

xsd: string

No

It identifies the specific call session

CallParticipant

xsd:anyURI

No

It identifies a specific call participant address within the call session

8.1.2.2 Output message : GetCallParticipantInformationResponse

Part name

Part type

Optional

Description

result

common: CallParticipantInformation

No

It identifies the status of the requested call participant

8.1.2.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0261 – Call Session already terminated.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.1.3 Void

8.1.4 Void

8.1.5 Operation: GetCallSessionInformation

The invocation of GetCallSessionInformation retrieves the CallSession information regarding the call session identified by CallSessionIdentifier parameter. The information provided in the CallSession includes the call participant information. This method can be invoked multiple times by the application even if the session has already ended. However, after the session has ended, status information will be available only for a limited period of time that is specified in the service policy ‘StatusRetentionTime’.

All occurrences of invalid call session shall result in an invalid input value exception

8.1.5.1 Input message: GetCallSessionInformationRequest

Part name

Part type

Optional

Description

CallSessionIdentifier

xsd: string

No

It identifies a specific call session

8.1.5.2 Output message : GetCallSessionInformationResponse

Part name

Part type

Optional

Description

result

common: CallSession

No

It identifies the status of the session

8.1.5.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0261 – Call Session already terminated.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.1.6 Operation: DeleteCallParticipant

The invocation of DeleteCallParticipant removes the call participant identified by CallParticipant from the call session identified by CallSessionIdentifier, and implicitly terminates that participants involvement in the call session.

The deleteCallParticipant method takes two parameters, the first being the call session identifier where the participant to delete is located. The second parameter identifies the call participant to be deleted (contains the URL of the participant).

All occurrences of invalid call session or participant address shall result in an invalid input value exception

8.1.6.1 Input message: DeleteCallParticipantRequest

Part name

Part type

Optional

Description

CallSessionIdentifier

xsd: string

No

It identifies a specific call session.

CallParticipant

xsd: anyURI

No

It identifies a specific call participant within the identified call session.

8.1.6.2 Output message: DeleteCallParticipantResponse

Part name

Part type

Optional

Description

None

8.1.6.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0261 – Call Session already terminated.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.1.7 Operation: EndCallSession

The invocation of EndCallSession terminates the call session identified by CallSessionIdentifier.

The call to all participants is ended.

All occurrences of invalid call session shall result in an invalid input value exception

8.1.7.1 Input message: EndCallSessionRequest

Part name

Part type

Optional

Description

CallSessionIdentifier

xsd: string

No

It identifies a specific call session

8.1.7.2 Output message: EndCallSessionResponse

Part name

Part type

Optional

Description

None

8.1.7.3 Referenced faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0261 – Call session already terminated.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.