# RESTful Application Development Guide

# Call Notification

## Operations

The RESTful Call Notification interfaces allow an application to set up and remove call notifications (in which the application is informed of a particular state - busy, unreachable, etc. - of the call) or to set up and remove call direction notifications (in which the application is queried for information on handling a call that is in a particular state).

In the listings below, bold indicates a required attribute, <> a descriptive comment.

Note: | An HTML version of this information is at `http://host:port/rest/call_notification/index.html` where host and port depend on the Oracle Communications Services Gatekeeper installation.

### Start Call Notification

Sets up a call notification

#### Request

##### URI

`http://host:port/rest/call_notification/call-notification`

##### Request Content-Type

application/json

##### Body

`{`

`` `"addresses"``: ["String"],`<The addresses to be monitored>

`` `"reference"``: {`

`` `"correlator"``:"String", <`A correlator used to identify the notification>

`` `"endpoint"``: "URI",`<The endpoint address to which the notification should be delivered. This should be a channel name that begins: “/bayeux/${appInstanceId}”>.

`` `"interfaceName"``: "String" <`Descriptive only, a string to identify the notification`>`

`},`

`"criteria": ["Busy|NotReachable|NoAnswer|CalledNumber"]` <Call events for which notification is required. If this is not specified, all events trigger notification. See Table 9-1 for more information>

`}`

Table 9-1 Criteria values
Value | Meaning
--- | ---
`Busy` | Called party is busy
`NotReachable` | Called party is not reachable
`NoAnswer` | Called party does not answer
`CalledNumber` | A call between two parties is being attempted.

##### HTTP Method

PUT

#### Response

Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications.

##### Header

key= “Location” value = “host:port/rest/call_notification/notifications”

The URI of the pub-sub server

#### Error Response

Service Exception

Policy Exception

### Stop Call Notification

Stops a previously set up notification

#### Request

##### URI

`http://host:port/rest/call_notification/call-notification/${correlator}`

${correlator}: The correlator passed in with the initial request

##### HTTP Method

DELETE

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

### Start Call Direction Notification

Sets up a call direction notification.

Note: | Because Call Direction Notifications require a response from the application to Oracle Communications Services Gatekeeper, the descriptions of the notifications include a reply-to private channel on the pub-sub server and a description of the data that must be returned. The application publishes the appropriate information to the pub-sub server channel, to which Oracle Communications Services Gatekeeper is subscribed.

#### Request

##### URI

`http://host:port/rest/call_notification/call-direction`

##### Request Content-Type

application/json

##### Body

`{`

`` `"addresses"``: ["String"],`<The addresses to be monitored>

`` `"reference"``: {`

`` `"correlator"``:"String", <`A correlator used to identify the notification>

`` `"endpoint"``: "URI",`<The endpoint address to which the notification should be delivered. This should be a channel name that begins: “/bayeux/${appInstanceId}”>

`` `"interfaceName"``: "String" <`Descriptive only, a string to identify the notification`>`

`},`

`"criteria": ["Busy|NotReachable|NoAnswer|CalledNumber"]` <Call events for which notification is required. If this is not specified, all events trigger notification. See Table 9-2 for more information>

`}`

##### HTTP Method

PUT

Table 9-2 Criteria values
Value | Meaning
--- | ---
`Busy` | Called party is busy
`NotReachable` | Called party is not reachable
`NoAnswer` | Called party does not answer
`CalledNumber` | A call between two parties is being attempted.

#### Response

Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications.

##### Header

key= “Location” value = “host:port/rest/call_notification/notifications”

The URI of the pub-sub server

#### Error Response

Service Exception

Policy Exception

### Stop Call Direction Notification

Stops a previously set up call direction notification

#### Request

##### URI

`http://host:port/rest/call_notification/call-direction/${correlator}`

${correlator}: The correlator passed in with the initial request

##### HTTP Method

DELETE

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

## Notifications

The content of notifications delivered to the designated endpoint

### Notify Called Number

`{"notifyCalledNumber": {`

`` `"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}`

### Notify Busy

`{"notifyBusy": {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}`

### Notify No Answer

`{"notifyNoAnswer": {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}`

### Notify Not Reachable

`{"notifyNotReachable": {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}`

### Handle Called Number

`{``"reply-to:"`${replyToChannel)`",`<The endpoint address to which the handle instructions from the application should be delivered. This is a private Bayeux channel set up by Oracle Communications Services Gatekeeper.>

`"data":`{`"handleCalledNumber"``: {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}}`

##### Handle Called Number Response

Applications respond to the Handle Called Number notification by publishing this data to the `reply-to:` channel provided in the notification.

{`"handleCalledNumberResponse"`: {`"result"`: {

`"actionToPerform"`: "Route|Continue|EndCall", <What Oracle Communications Services Gatekeeper should do with the call. See Table 9-3 for more information>

"charging": {<This entire attribute is optional>

`"description"``: "String",`<Text to be used for information and billing>

`"amount": "BigDecimal",`<The amount to be charged>

`"code": "String",`<A charging code, from an existing contractual description>``

`"currency": "String"`<A currency identifier as defined in ISO 4217 [9]>

},

`"routingAddress": "URI"`<The address to which the call should be routed>

}}}

Table 9-3 Handle Response
Value | Meaning
--- | ---
Route | Re-route the call to a specified address
Continue | Handle the call in the normal way
EndCall | Terminate the call

### Handle Busy

`{``"reply-to:"`${replyToChannel)`",`<The endpoint address to which the handle instructions from the application should be delivered. This is a private Bayeux channel set up by Oracle Communications Services Gatekeeper.>

`"data":`{`"handleBusy"``: {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}}`

##### HandleBusyResponse

Applications respond to the Handle Busy notification by publishing this data to the `reply-to:` channel provided in the notification.

{`"handleBusyResponse"`: {`"result"`: {

`"actionToPerform"`: "Route|Continue|EndCall", <What Oracle Communications Services Gatekeeper should do with the call. See Table 9-3 for more information>

"charging": {<This entire attribute is optional>

`"description"``: "String",`<Text to be used for information and billing>

`"amount": "BigDecimal",`<The amount to be charged>

`"code": "String",`<A charging code, from an existing contractual description>``

`"currency": "String"`<A currency identifier as defined in ISO 4217 [9]>

},

`"routingAddress": "URI"`<The address to which the call should be routed>

}}}

### Handle No Answer

`{``"reply-to:"`${replyToChannel)`",`<The endpoint address to which the handle instructions from the application should be delivered. This is a private Bayeux channel set up by Oracle Communications Services Gatekeeper.>

`"data":`{`"handleNoAnswer"``: {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}}`

##### Handle No Answer Response

Applications respond to the Handle No Answer notification by publishing this data to the `reply-to:` channel provided in the notification.

{`"handleNoAnswerResponse"`: {`"result"`: {

`"actionToPerform"`: "Route|Continue|EndCall", <What Oracle Communications Services Gatekeeper should do with the call. See Table 9-3 for more information>

"charging": {<This entire attribute is optional>

`"description"``: "String",`<Text to be used for information and billing>

`"amount": "BigDecimal",`<The amount to be charged>

`"code": "String",`<A charging code, from an existing contractual description>``

`"currency": "String"`<A currency identifier as defined in ISO 4217 [9]>

},

`"routingAddress": "URI"`<The address to which the call should be routed>

}}}

### Handle Not Reachable

`{``"reply-to:"`${replyToChannel)`",`<The endpoint address to which the handle instructions from the application should be delivered. This is a private Bayeux channel set up by Oracle Communications Services Gatekeeper.>

`"data":`{`"handleNotReachable"``: {`

`"calledParty"``: "URI",`<The address of the called party>

`` `"callingParty"``: "URI",`<The address of the calling party>

`` `"correlator"``: "String",`<The correlator passed in with the set up request>

`"callingPartyName": "String"` <The name of the calling party>

`}}}`

##### Handle Not Reachable Response

Applications respond to the Handle Not Reachable notification by publishing this data to the `reply-to:` channel provided in the notification.

{`"handleNoAnswerResponse"`: {`"result"`: {

`"actionToPerform"`: "Route|Continue|EndCall", <What Oracle Communications Services Gatekeeper should do with the call. See Table 9-3 for more information>

"charging": {<This entire attribute is optional>

`"description"``: "String",`<Text to be used for information and billing>

`"amount": "BigDecimal",`<The amount to be charged>

`"code": "String",`<A charging code, from an existing contractual description>``

`"currency": "String"`<A currency identifier as defined in ISO 4217 [9]>

},

`"routingAddress": "URI"`<The address to which the call should be routed>

}}}

## Errors

The content of possible error messages.

### Service Exception

{`"error"`:{

`"type":`"org.csapi.schema.parlayx.common.v2_1.ServiceException"

`"message"`:"String"

}}

### Policy Exception

{`"error"`:{

`"type"`:"org.csapi.schema.parlayx.common.v2_1.PolicyException"

`"message"`:"String"

}}