The Metaswitch Call Notification API is a prototype call notification API based on a subset of the OMA Call Notification API. In particular the Metaswitch Call Notification API implements call event and call direction notifications with a minor addition to support annoucements.

Tip See: {introduction-to-rest-and-openapi} for an introduction to REST (REpresentational State Transfer) APIs.

Capabilities of the Call Notification API

The SIP AS (MSW-CN client), in the following diagram, receives a SIP message from the S-CSCF and determines if a call event or call direction should be generated (in terms of call leg, point-in-call and so on), The MSW-CN server sends a notification request to an MSW-CN server if a call event or call direction is required.

MSW-CN client
Implementation of the client role of the MSW-CN API

MSW-CN server
Implementation of the server role of the MSW-CN API

Notification
An API request, made from the MSW-CN API client to an MSW-CN API server, containing a notification of a call/session related event (for a particular call/session)
MSW-CN API

There are two types of notification made by an MSW-CN client to an MSW-CN server.

  • Call Event: For call event notifications

    • An MSW-CN client notifies an MSW-CN server of events on a call/session.
      Call processing continues.
      This is analogous to an SSF sending event-reports, armed with notify-&-continue, to an SCF

  • Call Direction: For call direction notifications, where the client waits for instructions in the notification response.

    • An MSW-CN client notifies an MSW-CN server of events on a call/session.
      The MSW-CN client blocks ongoing call processing and waits for instructions from the MSW-CN server (in the response to the notification).
      This is analogous to an SSF sending event-reports, that had been armed with suspend, to an SCF where the BCSM blocks waiting-for-instructions.

The {arch-rest-api-framework } generates an OpenAPI specification description of MSW-CN into Resource Adaptor Type that Rhino applications use.

Tip The API definition is: msw-call-notification-rest-api/msw-call-notification-api/src/api.yaml.

The following sections illustrate aspects of the MSW-CN API and how it is realized in Java va the REST API framework.

Call Event and Call Direction Notifications

The YAML description below shows that an HTTP POST request, with a request URL including /callevent/notification corresponds to a call event notification. The body of the request is a CallEventNotification JSON object. A 200 OK response indicates the request was received. Any other response corresponds to an error.

YAML for Call Event Notification
/callevent/notification:
post:
  summary: A new Call Event notification
  operationId: callEventNotification
  tags:
    - notification
  requestBody:
    required: true
    description: call event notification
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/CallEventNotification"
  responses:
    '204':
      description: |
        The 204 No Content HTTP status code is returned if the data was received successfully
    default:
      description: unexpected error

The YAML description below shows that an HTTP POST request, with a request URL including /calldirection/notification corresponds to a call direction notification. The body of the request is a CallEventNotification JSON object. A 200 OK response indicates the request was received successfully. The body of the response is a Action JSON object. Any other response corresponds to an error.

YAML for Call Direction Notification
/calldirection/notification:
post:
  summary: A new Call Direction notification
  operationId: callDirectionNotification
  tags:
    - notification
  requestBody:
    required: true
    description: call direction notification
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/CallEventNotification"
  responses:
    '200':
      description: |
        The 200 OK HTTP status code is returned if the data was received successfully.
        The response body contains the request 'Action to take'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Action'
    default:
      description: unexpected error

The REST API framework generates a number of Java interfaces, enums and classes from the YAML specification. For example, an application uses the NotificationApi below to create Call Direction and Call Event notification requests.

Code Generated NotificationApi
package com.opencloud.openapi.demo.msw_cn.api;

import com.opencloud.slee.rest.common.*;
import com.opencloud.openapi.demo.msw_cn.model.*;

public interface NotificationApi {
    // Create a RestRequestBuilder for request: CallDirectionNotification
    RestRequestBuilder createCallDirectionNotificationRequest(
          CallEventNotification callEventNotification);

    // Create a RestRequestBuilder for request: CallEventNotification
    RestRequestBuilder createCallEventNotificationRequest(
          CallEventNotification callEventNotification);

    // Send a request
    OutgoingRestActivity sendRequest(
          RestRequestBuilder requestBuilder) throws IOException;
}
Tip

A concrete example showing how the MSW-CN API can be used can be seen in rest-demo-feature-modules/msw-send-call-notification/

See: Sending CallDirection and CallEvent notification requests for a code excerpt showing sending a Call Direction request

When Notifications can be Sent

Notifications are sent at certain points in the basic call model. These are:

Point-in-Call Calling/Called Notification Type Description

CALLEDNUMBER

Calling

Call Direction and Call Event

A call session between two parties, a calling participant and a called participant (called number) is being attempted

BUSY

Called

Call Direction and Call Event

Called party is busy

NOTREACHABLE

Called

Call Direction and Call Event

Called party is not reachable

NOANSWER

Called

Call Direction and Call Event

Called party doesn’t answer

ANSWER

Called

Call Event

Called Participant has confirmed (answered) the call

DISCONNECTED

Calling + Called

Call Direction and Call Event

Called (or calling) party disconnected
YAML CallEvents Enum
CallEvents:
  type: string
  enum:
    - Busy
    - NotReachable
    - NoAnswer
    - CalledNumber
    - Answer
    - Disconnected
YAML CallNotificationTypes Enum
CallNotificationTypes:
  type: string
  enum:
    - CallEvent
    - CallDirection
YAML AddressDirection Enum
AddressDirection:
  type: string
  enum:
    - Calling
    - Called

Actions Available in a Call Direction Response

A Call Direction response contains an Action object in the response body. The action describes the actionToPerform.

Action Description

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. An action may optionally include an annoucementId. Sentinel will play the announcement to the calling party before ending the call.
YAML Action Component
Action:
  required:
    - actionToPerform
  properties:
    actionToPerform:
      $ref: '#/components/schemas/ActionValues'
    routingAddress:
      type: string
      format: uri
    announcementId:
      type: string
YAML ActionValues Enum
ActionValues:
  type: string
  enum:
    - Route
    - Continue
    - EndCall
Previous page Next page