We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Telecom AS API Specification - FIWARE Forge Wiki

Telecom AS API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the S3C Telecom AS API

Voice Call Control API

The S3C Telecom AS APIs are to be developped on the GSMA OneAPI Specifications. It allows to manage outgoing calls from a service logic via a REST interface. This implementation of the OneAPI Voice Call Control API meets the RESTFull specification standards. It is possible :

  • to create a call between participants,
  • to get information about a call (is the call terminated?),
  • to get information about a call's participant,
  • to add a participant to a call,
  • to hang up a participant,
  • to delete a call,
  • to receive notifications about a participant according criteria as when the participant answers or as when the participant is busy,
  • to play an audio message to participant,
  • to be notified of any keypad interaction.

Intended Audience

This specification is intended for both software developers and reimplementers of this API. For the former, this document provides a full specification of how to use the API, ie Voice Call Control. For the latter, this specification provides a full specification of how to provide a code fully supporting the protocol described in the GSMA OneAPI portal.

In order to use this specifications, the reader should firstly have a general understanding of the appropriate Generic Enabler(s) supporting the API (FIWARE.OpenSpecification.I2ND.S3C).

API Change History

This version of the API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
June, 2013 initial version

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at FIWARE.I2ND.S3C Telecom AS API Specification. For more details about the S3C GE that this API is based upon, please refer to FIWARE.I2ND.S3C Open Specification.

Legal Notice

Please check the following Legal Notice to understand the rights to use FI-WARE Open Specifications.

General Voice Call Control API Information

Resources Summary

Please refer to the GSMA OneAPI Specifications.

Representation Format

The Voice Call Control API supports JSON format.

Resource Identification

The resource identification used by this API is based on the URI scheme described by HTTP protocol specification as defined by IETF RFC-2616 ( https://www.ietf.org/rfc/rfc2616.txt )

OneAPI Voice Call Control may be accessed via a RESTful API. A RESTful API utilises HTTP commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This resource is addressed by a URI; and what is returned by the server is a representation of that resource depending on its current state. HTTP POST, GET and DELETE commands are used. The URIs of the resources are:

Basic call management

* http://example.com/{api version}/thirdpartycall/callSessions

Create a call between two or more parties

* http://example.com/{api version}//thirdpartycall/callSessions/{callSessionID}/participants

Add or remove participants from the call Get information about the participants

* http://example.com/{api version}//thirdpartycall/callSessions/{callSessionID}

Get information about an existing call End a call

Advanced call management

* http://example.com/{api version}/callnotification/subscriptions/callEvent

Subscribe to notifications of certain events within calls

* http://example.com/{api version}/callnotification/subscriptions/callEvent/{subscriptionID}

View your notification criteria Stop receiving notifications

Playing audio messages to the participants

* http://example.com/{api version}/ audiocall/messages/audio

Play an audio message

* http://example.com/{api version}/audiocall/messages/audio/{abc123}

Stop an audio message Get the status of an audio message (to whom has it been played)

Playing an audio message and accepting keypad interaction from participants

* http://example.com/{api version}/audiocall/interactions/collection

Play an audio file to call participants and collect their keypad interactions

* http://example.com/{api version}/audiocall/interactions/collection/{abc123}

Terminate an audio message/keypad interaction

* http://example.com/{api version}/callnotification/subscriptions/collection

Be notified of any keypad interaction from participants to your audio message Stop receiving such notifications

For more detailed specifications please refer to the OneAPI web site.

Links and References

Some responses may contais reference to other resources managed by the enabler. Those links are represented as a standard URL tagged with the word “resourceURL” (see example below)

Example of links provided in an operation response (provided by GSMA OneAPI Specifications):

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/exampleAPI/
thirdpartycall/callSessions/cs001
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"callSessionInformation": {
   "clientCorrelator": "104567",
   "participant": [
    {"participantAddress": "tel:+4912345678901",
      "participantName": "Max Muster",
      "participantStatus": "CallParticipantConnected",
      "resourceURL": "http://example.com/exampleAPI/1/thirdpartycall/callSessions/cs001/participants/pt001",
       "startTime": "2010-06-28T17:50:51"
    },
    {"participantAddress": "tel:+4412345678901",
       "participantName": "Peter E. Xample",
       "participantStatus": "CallParticipantInitial",
       "resourceURL": "http://example.com/exampleAPI/1/thirdpartycall/callSessions/cs001/participants/pt002"
    }
   ],
   "resourceURL": "http://example.com/exampleAPI/1/thirdpartycall/callSessions/cs001",
   "terminated": "false"
}}

Limits

The list of normal response code(s) and the list of error response code(s) is listed by GSMA OneAPI Specifications.

Versions

The version of the API is embedded in the server root path e.g.

https://localhost/vccV1/

Extensions

There are no extention available on this enabler.

Faults

Synchronous and Asynchronous faults are described in GSMA OneAPI Specifications.

API Operations

In the following section, we just list the different operations that are allowed by the enabler. Thes operations are listed on the GSMA OneAPI Specifications.

Basic Call Management

Create a call between two or more parties

Add or remove participants from the call

Get information about the participants

Get information about an existing call

End a call

Advanced call management

Subscribe to notifications of certain events within calls

View your notification criteria

Stop receiving notifications

Playing audio messages to the participants

Play an audio message

Stop an audio message

Get the status of an audio message (to whom has it been played)

Playing an audio message and accepting keypad interaction from participants

Play an audio file to call participants and collect their keypad interactions

Terminate an audio message/keypad interaction

Be notified of any keypad interaction from participants to your audio message

Stop receiving such notifications

Technnical specifications

General Overview

The Voice Call Control API is implemented in the form of a generic enabler (V.C.C.E) interacting with other enablers via a SOAP interface. The V.C.C.E is managed by a service logic via REST API specified by GSMA. Image:archiAS.jpg

V.C.C.E is composed of four functionnal modules :

  • Connector : this module allows the interactions with the operator enablers

via a SOAP interface. It sends commands and received a notification at network events such as the hang up of a participant and network failures.

  • Persistence Storage : this module stores and manages all informations of

intercations with the service logic and the operator enablers.

  • OneAPI Interface : this module allows the interaction with the service logic

via the Voice Call Control RESTful API. It handles the notifications transmitted to service logic.

  • OneAPI Manager : it is the enabler's heart. For example, it interprets the

« creation of a call » commands is received from service logic, it stores the most pertinent data and translates the command to SOAP request understandable by operator enablers.

Personal tools
Create a book