API Description for Parlay X

Network-Initiated Third Party Call

The following sections describe the Network-initiated third party call API used for handling calls initiated from the telephone network:

Call API

Data Types

Exceptions

Call API

handleBusy

Invoked from the network to an application. Informs the Parlay X gateway how to handle incoming calls from the callingParty when trying to set up a call and the calledParty's call status is busy. The return value is decided by the application.

Table 5-1 handleBusy(callingParty, calledParty)

Parameter Name	Type	Description
Input
callingParty	EndUserIdentifier	URI of the calling party.
calledParty	EndUserIdentifier	URI of the called party.
Returns
	Action	Indicates the action to be performed by the gateway, see Action. Continue: results in normal handling of the busy event in the network, for example, playing of a busy tone to the callingParty. EndCall: results in the call being terminated; the exact tone or announcement that will be played to the callingParty is operator-specific. Route: results in the call being re-routed to a calledParty specified by the application.

Possible exceptions
UnknownEndUserException
ApplicationException
InvalidArgumentException

handleNotReachable

Invoked from the network to an application. Informs the Parlay X gateway how to handle incoming calls from the callingParty when trying to set up a call and the calledParty's call status is not reachable. The return value is decided by the application

Table 5-2 handleNotReachable(callingParty, calledParty)

Parameter Name	Type	Description
Input
callingParty	EndUserIdentifier	URI of the calling party.
calledParty	EndUserIdentifier	URI of the called party.
Returns
	Action	Indicates the action to be performed by the gateway, see Action. Continue: results in normal handling of the `not reachable' event in the network, for example, playing of a busy tone to the callingParty. EndCall: results in the call being terminated; the exact tone or announcement that will be played to the callingParty is operator-specific. Route: results in the call being re-routed to a calledParty specified by the application.

Possible exceptions
ApplicationException
InvalidArgumentException
UnknownEndUserException

handleNoAnswer

Invoked from the network to an application. Informs the Parlay X gateway how to handle incoming calls from the callingParty when trying to set up a call and the called parties does not answer. The return value is decided by the application

Table 5-3 handleNoAnswer(callingParty, calledParty)

Parameter Name	Type	Description
Input
callingParty	EndUserIdentifier	URI of the calling party.
calledParty	EndUserIdentifier	URI of the called party.
Returns
	Action	Indicates the action to be performed by the gateway, see Action. Continue results in normal handling of the no answer event in the network, for example, playing of a busy tone to the callingParty. EndCall results in the call being terminated; the exact tone or announcement that will be played to the callingParty is operator-specific. Route, results in the call being re-routed to a calledParty specified by the application.

Possible exceptions
ApplicationException
InvalidArgumentException
UnknownEndUserException

handleCalledNumber

Invoked from the network to an application. Informs the Parlay X gateway how to handle incoming calls from the callingParty to the calledParty before the actual call-setup is performed.

This is can be used when using calledParty as a common telephone number, and depending on the callingParty's telephone number, the call is routed to a destination number located geographically closest to the callingParty. The return value is decided by the application

Table 5-4 handleCalledNumber(callingParty, calledParty)

Parameter Name	Type	Description
Input
callingParty	EndUserIdentifier	URI of the calling party.
calledParty	EndUserIdentifier	URI of the called party.
Returns
	Action	Indicates the action to be performed by the gateway, see Action. Continue: results in normal handling, that is the call will be routed to the calledParty number, as originally dialled. EndCall: results in the call being terminated; the exact tone or announcement that will be played to the callingParty is operator-specific. Route: results in the call being re-routed to a calledParty specified by the application.

Possible exceptions
ApplicationException
InvalidArgumentException
UnknownEndUserException

handleOffHook

Invoked from the network to an application. Informs the Parlay X gateway how to handle incoming calls from the callingParty when trying to set up a call and the called party is off hook. The return value is decided by the application

Table 5-5 handleOffHook(callingParty)

Parameter Name	Type	Description
Input
callingParty	EndUserIdentifier	URI of the calling party.
Returns
	Action	Indicates the action to be performed by the gateway, see Action. Continue: results in normal handling of the off hook event in the network, for example, the calling party can enter digits and, when enough digits are entered, the call is routed based on this information. EndCall: results in the call being terminated; the exact tone or announcement that will be played to the callingParty is operator-specific. Route: results in the call being re-routed to a calledParty specified by the application.

Possible exceptions
ApplicationException
InvalidArgumentException
UnknownEndUserException

Data Types

Table 5-6 Data types specific for network initiated calls

Data type	Description
Action	Structure containing the following parameters:
	actionToPerform	Indicates the action as described in ActionValues. Datatype: ActionValues, see below.
	routingAddress	The address to be used in case the action indicates `Route' Datatype: EndUserIdentifier
	charging	OPTIONAL. If present, represents the name of an operator-specific charging plan that defines who to charge for the call and how much. If no charge plan is specified, the callingParty will be charged, based on an operator-specific charging policy. Datatype: String
ActionValues	The ActionValues data type is an enumeration with the following values:
	Route	Request to (re-)route the call to the address indicated with routingAddress.
	Continue	Request to continue the call without any changes. This will result in normal handling of the event in the network
	EndCall	Request to end the call. This will result in termination of the call. The callingParty will receive a tone or announcement.

Exceptions

No exceptions defined specifically for network initiated calls.