Voice Call Control RESTful API

Voice Call Control RESTful API

February 19, 2013

The OneAPI Call Control interface allows a Web application to start and manage a phone call. The call can be between two or more parties, which can be people, or can include an automated process (such as IVR). You can find some examples of why you may want to do this in our use cases.

Resources and URIs

OneAPI 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.

The URIs used are listed below.

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

example.com is replaced by the hostname of the OneAPI server you are accessing. apiVersion optionally indicates the version of OneAPI Call Control you are accessing – the default is the latest version supported by that server.

Request parameters

Please see the examples below for a description of the request parameters.

Representation formats

The response content type for the Call Control API is application/JSON.

Examples and Exceptions

Create a call

Request:

POST /exampleAPI/thirdpartycall/callSessions HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: nnnn
Accept: application/json

{"callSessionInformation": {
    "clientCorrelator": "104567",
    "participant": [
    { "participantAddress": "tel:+4912345678901",
       "participantName": "Max Muster"},
    {"participantAddress": "tel:+4412345678901",
      "participantName": "Peter E. Xample"
        }
    ]
}}

Parameters:

The JSON payload is a callSessionInformation object containing:

clientCorrelator (optional) a nonce String which uniquely identifies the request

A participant array, with each array member object containing participantName and participantAddress . The array may contain an unlimited number of participants, if this is more than the OneAPI server supports then a policy exception will be returned (see ‘Response Codes and Exceptions’ section)

Response:

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"
}}

Response:
HTTP 201 Created
The Location header is the URI of the call. This includes the ID of the call session (cs001 in the example). This is also available in the JSON payload as resourceURL

The JSON payload is a callSessionInformation object confirming the clientCorrelator (if provided) and each participant’s participantName and participantAddress. In addition, each participant has a participantStatus. This is one of:

  • CallParticipantInitial (call in process of being established)
  • CallParticipantConnected
  • CallParticipantTerminated

Also included for each participant is a resourceURL through which the participant status may be queried.

The startTime pair indicates the call session start time in UTC

The resourceURL is the URL with which the call session may be queried. The Boolean terminated pair indicates if the call has been terminated.

Add a participant to the call

Request:

POST /exampleAPI/thirdpartycall/
callSessions/cs002/participants HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: nnnn
Host: example.com:80

{"callParticipantInformation": {
    "clientCorrelator": "224567",
    "participantAddress": "tel:+1567890123456",
    "participantName": "John E. Xample"
}}

The URL to POST to includes call ID provided when the call was created (cs002 in the example).

Parameters
A callParticipantInformation object, containing:
an optional clientCorrelator nonce in case of request failure
Pairs for participantName and participantAddress

Response:

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

{"callParticipantInformation": {
    "clientCorrelator": "224567",
    "participantAddress": "tel:+1567890123456",
    "participantName": "John E. Xample",
    "participantStatus": "CallParticipantInitial",
    "resourceURL": "http://example.com/exampleAPI/1/thirdpartycall/
callSessions/cs002/participants/pt002"
}}

HTTP 201 Created

The Location header is the URI of the call. This includes the ID of the call session (cs001 in the example).

The JSON payload is a callParticipantInformation object confirming the clientCorrelator (if provided) and each participant’s name and address. In addition, each participant has a participantStatus. This is one of:

  • CallParticipantInitial
  • CallParticipantConnected
  • CallParticipantTerminated

Also included for each participant is a resourceURL through which the participant status may be queried.

Get information about an existing call

Request:

GET /exampleAPI/thirdpartycall/callSessions/cs001 HTTP/1.1
Host: example.com:80

Make sure to include the call sessionID provided when you created the call session (cs001 in the example)

Response:

HTTP/1.1 200 OK
Content-Type: application/json
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"
}}

HTTP 200 OK

The JSON payload is a callSessionInformation object confirming the clientCorrelator (if provided) and a participant array for each participant’s name and address. In addition, each participant has a participantStatus. This is one of:

  • CallParticipantInitial (call in process of being established)
  • CallParticipantConnected
  • CallParticipantTerminated

Also included for each participant is a resourceURL through which the participant status may be queried; and if CallParticipantConnected

the startTime pair indicates the time the participant joined the call (in UTC).

The resourceURL is the URL with which the call session may be queried. The Boolean terminated pair indicates if the call has been terminated.

Get information about a call participant

Request:

GET /exampleAPI/thirdpartycall/callSessions/
cs001/participants/pt001 HTTP/1.1
Accept: application/json
Host: example.com:80

The URL to GET includes the callID provided when the call was created (cs001 in the example) and the participantID (pt001 in the example)

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"callParticipantInformation": {
    "clientCorrelator": "224567",
    "participantAddress": "tel:+1567890123456",
    "participantName": "John E. Xample",
    "participantStatus": "CallParticipantConnected",
    "resourceURL": "http://example.com/exampleAPI/1/thirdpartycall/
callSessions/cs002/participants/pt002",
    "startTime": "2010-06-28T17:51:51"
}}

HTTP 200 OK

The JSON payload is a callParticipantInformation object confirming the clientCorrelator (if provided) the participant address, name and status.

The status is one of:

  • CallParticipantInitial (call in process of being established)
  • CallParticipantConnected
  • CallParticipantTerminated . If the value is CallParticipantTerminated , then an additional pair of terminationCausewill be provided, which indicates why the participant is no longer in the call. This can be one of:
    • CallParticipantNoAnswer
    • CallParticipantBusy
    • CallParticipantNotReachable
    • CallParticipantHangUp
    • CallParticipantAborted

Also included for each participant is a resourceURL through which the participant status may be queried; and if
CallParticipantConnected
, the startTime pair indicates the time the participant joined the call (in UTC).

Remove a participant from the call

Request:

DELETE /exampleAPI/thirdpartycall/callSessions/
cs001/participants/pt001 HTTP/1.1
Accept: application/json
Host: example.com:80

The URL to DELETE includes the callID provided when the call was created (cs001 in the example) and the
participantID
(pt001 in the example)

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"callParticipantInformation": {
    "clientCorrelator": "224567",
    "duration": "134",
    "participantAddress": "tel:+1567890123456",
    "participantName": "John E. Xample",
    "participantStatus": "CallParticipantTerminated",
    "resourceURL": "http://example.com/exampleAPI/1/
thirdpartycall/callSessions/cs002/participants/pt002",
    "startTime": "2010-06-28T17:51:51",
    "terminationCause": "CallParticipantAborted"
}}

HTTP 200 OK

The JSON payload is a callParticipantInformation object confirming the clientCorrelator (if provided) the participant address, name and the participantStatus of CallParticipantTerminated

Also included is a resourceURL through which the participant status may be queried; the startTime pair indicating at which time the participant joined the call (in UTC), and the duration they were on the call (in seconds).

The terminationCause confirms that the participant was explicitly aborted from the call session.

End a call session

Request:

DELETE /exampleAPI/thirdpartycall/
callSessions/cs001 HTTP/1.1
Accept: application/json
Host: example.com:80

The URL to DELETE includes the callID provided when the call was created (cs001 in the example).

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"callSessionInformation": {
    "clientCorrelator": "204567",
    "participant": [
        {
            "duration": "135",
            "participantAddress": "tel:+1234567890123",
            "participantName": "Mary E. Xample ",
            "participantStatus": "CallParticipantTerminated",
            "resourceURL": "http://example.com/exampleAPI/1/
thirdpartycall/callSessions/cs002/participants/pt001",
            "startTime": "2010-06-28T17:50:51",
            "terminationCause": "CallParticipantAborted"
        },
        {
            "clientCorrelator": "224567",
            "duration": "134",
            "participantAddress": "tel:+1567890123456",
            "participantName": "John E. Xample",
            "participantStatus": "CallParticipantTerminated",
            "resourceURL": "http://example.com/exampleAPI/1/
thirdpartycall/callSessions/cs002/participants/pt002",
            "startTime": "2010-06-28T17:51:51",
            "terminationCause": "CallParticipantAborted"
        }
    ],
    "resourceURL": "http://example.com/exampleAPI/1/
thirdpartycall/callSessions/cs002",
    "terminated": "true"
}}

HTTP 200 OK

The Location header is the URI of the call. This includes the ID of the call session (cs001 in the example)

The response includes a statement of the call, including participants, how long they were on the call for, and confirmation that they have been disconnected.

The JSON payload is a callParticipantInformation object confirming the clientCorrelator (if provided) and a participant array.

Each object in the participant array contains a duration pair, showing how long the participant was in the call (in seconds) and a pair to confirm the terminationCause CallParticipantAborted (i.e., the call was explicitly ended, which may be relevant for logging purposes).

The other participant parameters are the same as for ‘Get information about existing call’ above.

The resourceURL is the URL with which the call session may be queried. The Boolean terminated pair indicates that the call has been terminated

Subscribe to notifications of events in calls

Request:

POST /exampleAPI/callnotification/
subscriptions/callEvent HTTP/1.1
Content-Type: application/json
Content-Length: nnnn
Accept: application/json
Host: example.com

{"callEventSubscription": {
    "callbackReference": {
        "notifyURL": "http://application.example.com/
notifications/CallNotificationURL"},
    "clientCorrelator": "112345",
    "filter": {
        "address": [
            "tel:+15555550101",
            "tel:+15555550102"
        ],
        "addressDirection": "Called",
        "criteria": [
            "Answer",
            "Busy"
        ]
    }
}}

The JSON to POST includes:

callEventSubscription object containing:

callbackReference object containing a notifyURL pair (the URL that the OneAPI service should POST updates to)

An optional clientCorrelator

A filter object containing:

an address array of all the calls that you want to subscribe to event notifications from

addressDirection (Called or Calling). OneAPI Call Control lets you register for events whether a call is made to a particular number, or from a particular number.

criteria is an array of call events that you want to be notified about. Legal values are:

  • Busy
  • NotReachable
  • NoAnswer
  • CalledNumber (notify me when a number is called)
  • Answer the call was answered
  • Disconnected the call was disconnected

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/exampleAPI/1/
callnotification/subscriptions/callEvent/sub001
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"resourceReference": {
    "resourceURL": "http://example.com/exampleAPI/1
/callnotification/subscriptions/callEvent/sub001"}}

HTTP 201 Created

The Location header is the URL of the subscription. This includes the ID of the subscription (sub001 in the example).

For convenience the resourceURL pair of the resourceReference Object also contains the URL of the subscription.

View your notification criteria

Request:

GET /exampleAPI/callnotification/
subscriptions/callEvent/sub001 HTTP/1.1
Host: example.com

The URL to GET includes the callID provided when the call was created (sub001 in the example).

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"callEventSubscription": {
    "callbackReference": {
        "notifyURL": "http://application.example.com/
notifications/CallNotificationURL"},
    "clientCorrelator": "112345",
    "filter": {
        "address": [
            "tel:+15555550101",
            "tel:+15555550102
        ],
        "addressDirection": "Called",
        "criteria": [
            "Answer",
            "Busy"
        ]
    },
    "resourceURL": 
        "http://example.com/exampleAPI/1/
callnotification/subscriptions/callEvent/sub001"
}}

HTTP 200 OK

The response simply reflects the JSON payload that was POSTed when the subscription was created (“Subscribe to notifications of events in calls” above)

What will be POSTed to you when an event occurs

Request:

POST /notifications/CallNotificationURL HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnnn
Host: application.example.com

{"callEventNotification": {
    "callSessionIdentifier": "B12345",
    "calledParticipant": "tel:+15555550101",
    "callingParticipant": "tel:+15555550102",
    "callingParticipantName": "Peter E. Xample",
    "eventDescription": {
        "callEvent": "Busy",
        "description": "optional service-specific information"  },
    "link": [
        { "href": "http://example.com/exampleAPI/
1/callnotification/subscriptions/callEvent/sub001",
            "rel": "CallEventSubscription"},
        { "href": "http://example.com/exampleAPI/
1/thirdpartycall/callSessions/cs001",
            "rel": "CallSessionInformation"}
    ],
    "notificationType": "CallEvent"
}}

The POST will be made to the notifyURL you provided.

The callEventNotification object contains the following objects:

callSessionIdentifier

A list of the calledParticipants numbers

The callingParticipant ‘s number (from whom the call originated)

The callingParticipantName

eventDescription containing:
callEvent which will be one of:

  • Busy – Called party is busy.
  • NotReachable – Called party is not reachable.
  • NoAnswer – Called party doesn’t answer.
  • CalledNumber – A call session between two parties, a calling participant and a called participant (called number) is being attempted.
  • Answer – Called Participant has confirmed (answered) the call.
  • Disconnected – Called (or calling) party disconnected

An optional description with any service-specific information.

link array with href pairs related to the CallEventSubscription and CallSessionInformation (indicated by the rel value)

The notificationType to indicate this is a CallEvent

Response:

HTTP/1.1 204 No Content
Date: Mon, 28 Jun 2010 17:51:59 GMT

The application should return HTTP status 204 to indicate the notification has been received.

Cancelling a subscription

Request:

DELETE /exampleAPI/1/callnotification/
subscriptions/callEvent/sub001 HTTP/1.1
Accept: application/json
Host: example.com


Include the subscriptionId created when the subscription was requested

Response:

HTTP/1.1 204 No Content
Date: Mon, 28 Jun 2010 17:51:59 GMT

HTTP status 204 indicates the subscription has been deleted

Play an audio message to call participants

Request:

POST /exampleAPI/audiocall/messages/audio HTTP/1.1
Accept: application/xml
Content-Length: nnnn
Content-Type: application/x-www-form-urlencoded
Host: example.com

callSessionIdentifier=B45678&
callParticipant= tel%3A%2B4912345678901&
callParticipant= tel%3A%2B4412345678901&
mediaUrl=http%3A%2F%2Fwww.example.com%2Fann1.mp3&
mediaType=audio%2Fmpeg&
clientCorrelator=22345

Mandatory Parameters

The callSessionIdentifier for which call the audio will be played in
mediaUrl is the URL-encoded URL of the file to play
mediaType is the URL-encoded MIME type of the file

Optional Parameters

A callParticipant parameter for each participant the message will be played to (default is every participant)
clientCorrelator is an optional nonce in case of request/response failure

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"audioMessage": {
    "callParticipant": [
        "tel:+4912345678901",
        "tel:+4412345678901"
    ],
    "callSessionIdentifier": "B45678",
    "clientCorrelator": "22345",
    "mediaType": "audio/mpeg",
    "mediaUrl": "http://www.example.com/ann1.mp3",
    "messageStatusList": {
        "messageStatus": [
            { "callParticipant": "tel:+4912345678901",
                "status": "Pending" },
            {  "callParticipant": "tel:+4412345678901",
                "status": "Pending" }
        ],
        "resourceURL": 
            "http://example.com/exampleAPI/1/
audiocall/messages/audio/msg123/statusList" },
    "resourceURL": "http://example.com/exampleAPI/
1/audiocall/messages/audio/msg123"
}}

HTTP 201 Created

The JSON audioMessage object binds the parameters passed in the request, and also includes a messageStatusList containing a messageStatus array. This contains pairs for each callParticipant and the message playback status, which can be one of:

  • Played – Message has been played
  • Playing – Message is currently playing
  • Pending – Message has not yet started playing
  • Error – An error has occurred, message will not be played
  • Terminated – The message was terminated by a request from the application.

The audioMessage status may be queried again via the resourceURL including the messageID (msg123 in the example) and /statusList at the end of the path.

Get the status of a played message

Request:

GET /exampleAPI/audiocall/messages/
audio/msg123/statusList HTTP/1.1
Accept: application/json
Host: example.com

The GET request includes the messageID (msg123 in the example)

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"messageStatusList": {
    "messageStatus": [
        {   "callParticipant": "tel:+4912345678901",
            "status": "Played" },
        {   "callParticipant": "tel:+4412345678901",
            "status": "Pending"}],
    "resourceURL": "http://example.com/exampleAPI/1/
audiocall/messages/audio/msg123/statusList"
}}

The JSON messageStatusList object contains a messageStatus array. This contains pairs for each callParticipant and the message playback status, which can be one of:

  • Played – Message has been played
  • Playing – Message is currently playing
  • Pending – Message has not yet started playing
  • Error – An error has occurred, message will not be played
  • Terminated – The message was terminated by a request from the application.

Stop playing a message

Request:

DELETE /exampleAPI/audiocall/
messages/audio/msg123 HTTP/1.1
Accept: application/json
Host: example.com

The GET request includes the messageID (msg123 in the example)

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"audioMessage": {
    "callParticipant": ["tel:+4912345678901",
                                "tel:+4412345678901"],
    "callSessionIdentifier": "B45678",
    "clientCorrelator": "22345",
    "mediaType": "audio/mpeg",
    "mediaUrl": "http://www.example.com/ann1.mp3",
    "messageStatusList": {
        "messageStatus": [
            {  "callParticipant": "tel:+4912345678901",
               "status": "Played"},
            {  "callParticipant": "tel:+4412345678901",
                "status": "Terminated"}],
        "resourceURL": "http://example.com/exampleAPI/1/
audiocall/messages/audio/msg123/statusList"},
    "resourceURL": "http://example.com/exampleAPI/1/
audiocall/messages/audio/msg123"
}}

HTTP 200 OK

The JSON response to the deletion is a statement of metadata about the call, including whether the message was successfully played to each participant.

The JSON audioMessage object binds the parameters passed in the request, and also includes a messageStatusList containing a messageStatus array. This contains pairs for each callParticipant and the message playback status, which can be one of:

  • Played – Message has been played
  • Playing – Message is currently playing
  • Pending – Message has not yet started playing
  • Error – An error has occurred, message will not be played
  • Terminated – The message was terminated by a request from the application.

Play an audio message to collect user interactions with it

Request:

POST /exampleAPI/audiocall/
interactions/collection HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnnn
Host: example.com

{"digitCapture": {
    "callParticipant": "tel:+4912345678901",
    "callSessionIdentifier": "F14567",
    "clientCorrelator": "62345",
    "digitConfiguration": {
        "interruptMedia": "false",
        "maxDigits": "1",
        "minDigits": "1"
    },
    "playingConfiguration": {
        "interruptMedia": "false",
        "mediaType": "audio/mpeg",
        "messageFormat": "Audio",
        "playFileLocation": 
            "http://www.example.com/msg1.mp3"
    }
}}

This method allows your application to set up how user’s interact with an audio message you are playing. For example, users may choose to press ‘1’ to go through to Customer Services, or you may have a phone-voting application for a video that is being streamed on your website.

Parameters

The digitalCapture object contains pairs for:

callSessionIdentifier (mandatory) , or a link pair that points to the REST resourceURL for the call

callParticipant (optional), which user the message is to be played and their interaction collected. If omitted, it applies to all participants,

clientCorrelator (optional), a nonce in case of request failure when POSTing.

digitConfiguration (mandatory) object describes the user interaction (the digits that they enter from their keypad). It contains:

  • InterruptMedia (Boolean, mandatory) Indicates whether the application allows the end user to interrupt, or pause, the prompt
  • maxDigits (optional) the max number of digits that will be collected
  • minDigits(optional), the minimum number of digits that will be collected. If this value is provided and is not achieved, then the resulting behaviour is dependent on the media playnack server (for example it may prompt the user again to enter a digit(s).)
    • If no minDigits value is provided, then the default value is 1.

playingConfiguration (mandatory) describes the playback of the audio essage. It contains:

  • playFileLocation (mandatory) , the URL of audio file to play
  • mediaType (optional), the MIME type of the audio message
  • interruptMedia (Boolean, mandatory) Indicates whether the application allows the end user to interrupt, or pause, the prompt.

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"resourceReference": 
{"resourceURL": "http://example.com/exampleAPI/1/
audiocall/interactions/collection/int123"}}

HTTP 201 Created

The resourceReference object contains the resourceURL pair, which provides a URL to query the configuration you created, and includes the identifier (int123 in the example)

Read the configuration of an existing user interaction session

Request:

GET /exampleAPI/audiocall/
interactions/collection/int123 HTTP/1.1
Accept: application/json
Host: example.com

Include the identifier of the existing session in the resource URL

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"digitCapture": {
    "callParticipant": "tel:+4912345678901",
    "callSessionIdentifier": "F14567",
    "clientCorrelator": "62345",
    "digitConfiguration": {
        "interruptMedia": "false",
        "maxDigits": "1",
        "minDigits": "1" },
    "playingConfiguration": {
        "interruptMedia": "false",
        "mediaType": "audio/mpeg",
        "messageFormat": "Audio",
        "playFileLocation": "http://www.example.com/msg1.mp3"},
    "resourceURL": "http://example.com/exampleAPI/
audiocall/interactions/collection/int123"}}

HTTP 200 OK

The response simply reflects the configuration you POSTed when creating the interaction session – see above for parameter description.

Subscribe to notifications of user interaction with a played message

Request:

POST /exampleAPI/1/callnotification/
subscriptions/collection HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: nnnn
Accept: application/xml
Host: example.com

notifyURL=http%3A%2F%2Fapplication.example.com%2F
notifications%2FMediaInteractionNotificationURL&
callSessionIdentifier=A1234&
clientCorrelator=312345

Mandatory parameters

notifyURL – the URL that the OneAPI will POST event notifications to
callSessionIdentifier – the call that you are playing the audio message in

Optional parameter

clientCorrelator – nonce in case of request failure

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/exampleAPI/1/callnotification/subscriptions/collection/sub001
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"playAndCollectInteractionSubscription": {
    "callSessionIdentifier": "A1234",
    "callbackReference": {"notifyURL": 
        "http://application.example.com/notifications/
MediaInteractionNotificationURL"},
    "clientCorrelator": "312345",
    "resourceURL": "http://example.com/exampleAPI/1/
callnotification/subscriptions/collection/sub001"
}}

HTTP 201 created

The request parameters are reflected, along with a resourceURL to enable read and delete of this subscription (a subscriptionID is included in the path)

What will be POSTed to you when a user enters digits

Request:

POST /notifications/
MediaInteractionNotificationURL HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnnn
Host: application.example.com

{"mediaInteractionNotification": {
    "callParticipant": "tel:+15555550101",
    "link": {
        "href": "http://example.com/exampleAPI/
callnotification/subscriptions/recording/sub001",
        "rel": "MediaInteractionSubscription"
    },
    "mediaInteractionResult": "1943",
    "notificationType": "PlayAndCollect"
}}

The POST will be made to the notifyURL you provided.

The link object includes the subscriptionID (the value of the href pair).

The user who has entered the digits is identified by the callParticipant pair.

The digits that the user has entered are the value of the mediaInteractionResult pair.

Response:

HTTP/1.1 204 No Content
Date: Thu, 04 Jun 2009 02:51:59 GMT

Indicates request processed successfully but no data is returned

Read the configuration of an existing subscription

Request:

GET /exampleAPI/callnotification/
subscriptions/collection/sub001 HTTP/1.1
Accept: application/json
Host: example.com

GET the resourceURL provided when the notification subscription was created

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Mon, 28 Jun 2010 17:51:59 GMT

{"playAndCollectInteractionSubscription": {
    "callSessionIdentifier": "A1234",
    "callbackReference": {"notifyURL": 
        "http://application.example.com/notifications/
MediaInteractionNotificationURL"},
    "clientCorrelator": "312345",
    "resourceURL": "http://example.com/exampleAPI/1/
callnotification/subscriptions/collection/sub001"
}}

HTTP 200

The response simply reflects the configuration of the subscription you created.

Stop an existing subscription to user interaction notifications

Request:

DELETE /exampleAPI/1/callnotification/
subscriptions/collection/sub001 HTTP/1.1
Accept: application/json
Host: example.com

Include the subscription identifier in the resource URL

Response:

HTTP/1.1 204 No Content
Date: Mon, 28 Jun 2010 17:51:59 GMT

Indicates request processed successfully but no data is returned

Stop the audio message and user interaction session

Request:

DELETE /exampleAPI/audiocall/
interactions/collection/int123 HTTP/1.1
Accept: application/json
Host: example.com

Include the session identifier in the resource URL

Response:

HTTP/1.1 204 No Content
Date: Mon, 28 Jun 2010 17:51:59 GMT

Indicates request processed successfully but no data is returned

Response codes and exceptions

HTTP response codes are used to indicate:
200 – Success!
400 – Bad request; check the error message and correct the request syntax.
401 – Authentication failure, check your OneAPI provider’s authentication requirements.
403 – Forbidden; please provide authentication credentials.
404 – Not found: mistake in the host or path of the service URI.
405 – Method not supported: in OneAPI Location v1 only GET is supported.
503 – Server busy and service unavailable. Please retry the request.

More details on these at http://www.ietf.org/rfc/rfc2616.txt

Invalid address error:

HTTP/1.1 400  Bad Request
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"requestError": {
    "serviceException": {
        "messageId": "SVC0002",
        "text": " Invalid input value for message part %1",
        "variables": " accessToken abc123"
    }
}}

400 indicates an error

A serviceException describes the reason why the service cannot accept the request; for example if the registrationId was incorrect.

A policyException object means that the request syntax is valid, however an operator policy has been broken: in this example because the operator cannot support the batch size requested.

serviceException and policyException share the same body: an identifier pair for the exception (messageId), a text pair to describe it consistently (text), and a variables pair to indicate any specific cause of the error (variables). The variables relate to the %1 placeholder(s) in the text.

Testing

OneAPI has a Reference Implementation Portal which provide free testing facilities.

Questions and feedback

Please let us know any problems or suggestions for the Data Connection Profile API. Contact us.

Reference Material

OneAPI is a profile (subset) of Parlay REST v2.0. The full specifications and guidelines may be found at: http://www.openmobilealliance.org/Technical/current_releases.aspx

Back
Contact GSMA Legal Email Preference Centre Copyright © 2014 GSMA. GSM and the GSM Logo are registered and owned by the GSMA.