| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the operations in the Audio Call interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Audio Call interface to get an audio file from Text to Speech file, Voice XML file from an independent location and send it to a terminal.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at
http://host:port/rest/audio_call/index.html
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The Play Audio Message operation sends an audio file (such as .WAV) to a single terminal. If the request contains more than one URI, the operation will fail.
To play the audio message at a specific terminal, provide the address of the terminal that is to receive the message, the URL of the audio (.wav) file, and, optionally, the information for billing the call. In effect, this is a request to set up a call to the user (the terminal) and play the audio file.
The call to play the audio file at the terminal is done asynchronously and can be monitored by retrieving its status. If the Play Audio Message operation is successful, the response body will contain the call identifier for the actual call when the audio file is played at the terminal. Use this call identifier to check on the request status.
http://host:port/rest/audio_call/audiocalls
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for the Play Audio Message operation accepts the following parameters:
address. String. Required. The SIP-formatted URI of the party who must receive the audio message.
audioUrl. String. Required. The URI of the audio file that is to be played.
charging: a JSON object. Optional. This object defines the cost charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description. String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount: Number (integer, or decimal). Optional. The amount to be charged.
code. String. Optional. The charging code, from an existing contractual description.
currency. String. Optional. The currency identifier as defined in ISO 4217 [9].
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"address": "URI",
"audioUrl": "URI",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
}
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The call identifier for the actual call when the audio file is played at the terminal is returned in the body of the response as the value of the result attribute.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "String"}
Example 13-1 Play Audio Message Request
GET /rest/audio_call/audiocalls HTTP/1.1
X-Session-ID: app:65671150306510708
Authorization: Basic YxBwXzFfdToxMjM0NTY3oA=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host:10.182.100.142:8001
Content-Length: 125
Content-Type: application/json
{
"audioUrl":"file://opt/OC/share/jsr309-TCK-media/dtmfs-1-9.wav",
"address":"sip:alice@10.182.100.142.10072",
"charging":
{
"description":"Message for Alice",
"amount":"11",
"code":"1111",
"currency":"rmb"
}
}
Example 13-2 Play Audio Message Response
HTTP/1.1 201 Created
Date: Fri, 05 Nov 2010 02:03:09 GMT
Content-Length: 95
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":"app-6nbs6twem41p|5624bd08b079138534263491b78d49e9@10.182.100.142|-40d94a935cd12af0"}
The Play Text Message operation sends a Text-to-Speech to a single terminal. The text is read through a text to speech engine and based on a specified format. If the request contains more than one URI, the operation will fail.
To play the text message at a specific terminal, provide the address of the terminal that is to receive the message, the text message and its language format, and, optionally, the information for billing the call. In effect, this is a request to set up a call to the user (the terminal) and play the text file.
The call to play the text message at the terminal is done asynchronously and can be monitored by retrieving its status. If the Play Text Message operation is successful, the response body will contain the call identifier for the actual call that is to play the text message at the terminal. Use this call identifier to check on the request status.
http://host:port/rest/audio_call/textcalls
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for the Play Audio Message operation accepts the following parameters:
address. String. Required. The SIP-formatted URI of the party who must receive the text message.
text. String. Required. The text to be read as text-to-speech (the "voice" structure in Speech Synthesis Markup Language (SSML) format.
language. String. Required. The language in which the message is to be played, using ISO 639 format.
charging. a JSON object. Optional. This object defines the cost charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description. String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code. String. Optional. The charging code, from an existing contractual description.
currency. String. Optional. The currency identifier as defined in ISO 4217 [9].
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"address": "URI",
"language": "String",
"text": "String",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
}
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The call identifier for the actual call when the text-to-speech file is played at the terminal is returned in the body of the response as the value of the result attribute.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "String"}
Example 13-3 Play Text Message Request
GET /rest/audio_call/textcalls HTTP/1.1
X-Session-ID: app:65671150306510708
Authorization: Basic YxBwXzFfdToxMjM0NTY3oA=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host:10.182.100.142:8001
Content-Length: 125
Content-Type: application/json
{
"address":"sip:alice@10.182.100.142.10072",
"text":"WHATSTHIS",
"language":"WHATSTHIS",
"charging":
{
"description":"Message for Alice",
"amount":"11",
"code":"1111",
"currency":"rmb"
}
}
Example 13-4 Play Text Message Response
HTTP/1.1 201 Created
Date: Fri, 05 Nov 2010 02:03:09 GMT
Content-Length: 95
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":"app-6nbs6twem41p|5624bd08b079138534263491b78d49e9@10.182.100.142|-40d94a935cd12af0"}
The Play Text Message operation sets up a request to send a specified VoiceXML content located at a specific voice URL to a single terminal. If the request contains more than one URI, the operation will fail.
To play the voice xml message at a specific terminal, provide the address of the terminal that is to receive the message, the location of the VoiceXML file, and, optionally, the information for billing the call. In effect, this is a request to set up a call to the user (the terminal) and play the text file.
The call to play the text message at the terminal is done asynchronously and can be monitored by retrieving its status. If the Play Text Message operation is successful, the response body will contain the call identifier for the actual call that is to play the text message at the terminal. Use this call identifier to check on the request status.
http://host:port/rest/audio_call/voicexmlcalls
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for the Play Audio Message operation accepts the following parameters:
address. String. Required. The SIP-formatted URI of the party who must receive the text message.
voiceXmlUrl. String. Required. The location of the VoiceXML file.
charging. a JSON object. Optional. This object defines the cost charging properties for the call. A call with no charging parameters can be entered as "charging": null. If a charge is to be applied, provide values for the following in the charging object:
description. String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount: Number (integer, or decimal). Optional. The amount to be charged.
code. String. Optional. The charging code, from an existing contractual description.
currency. String. Optional. The currency identifier as defined in ISO 4217 [9].
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"address": "URI",
"voiceXmlUrl": "URI",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
}
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The call identifier for the actual call when the VoiceXML is played at the terminal is returned in the body of the response as the value of the result attribute.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "String"}
Example 13-5 Play VoiceXML Message Request
GET /rest/audio_call/voicexmlcalls HTTP/1.1
X-Session-ID: app:65671150306510708
Authorization: Basic YxBwXzFfdToxMjM0NTY3oA=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host:10.182.100.142:8001
Content-Length: 125
Content-Type: application/json
{
"address":"sip:alice@10.182.100.142.10072",
"voiceXmlUrl":"http://some_url/mesg_recorded.vxml",
"charging":
{
"description":"Message for Alice",
"amount":"11",
"code":"1111",
"currency":"rmb"
}
}
Example 13-6 Play VoiceXML Message Response
HTTP/1.1 201 Created
Date: Fri, 05 Nov 2010 02:03:09 GMT
Content-Length: 95
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":"app-6nbs6twem41p|5624bd08b079138534263491b78d49e9@10.182.100.142|-40d94a935cd12af0"}
The Get Message Status operation retrieves the status of a previously set up request, which in this case is the status of an audio file bound for a single terminal.
To retrieve the status of the audio file, provide the appropriate correlator. This correlator is the string value of the result attribute from the response body for the appropriate Play (Audio/Text/VoiceXML) Message operation.
If the Get Message Status operation is successful, the response body contains a JSON data object indicating whether the audio file is pending, playing, has played or an error has occurred.
http://host:port/rest/audio_call/call?getMessageStatus=${getMessageStatus}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${getMessageStatus} contains the call identifier from the response body for the appropriate Play (Audio/Text/VoiceXML) Message operation as the string value for the correlator attribute.
The ${getMessageStatus} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"correlator": "String"}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The status of the specific audio file is returned in the body of the response as the value of the result attribute:
Played
Playing
Pending
Error
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "Played|Playing|Pending|Error"}
Example 13-7 Get Message Status Request
GET /rest/audio_call/call?getMessageStatus=%7B%22correlator%22%3A%22app-6nbs6twem41p%7c5624bd08b079138534263491b78d49e9%4010.182.100.142%7c-40d94a935cd12af0 HTTP/1.1 X-Session-ID: app:6567114150306510708 Authorization: Basic YXBwXzFfdToxMjM0NTY30A= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.142.8001
The End Message operation terminates an application's previously set up request to play the specified audio file.
To stop a previously set up request to play an audio file, provide the appropriate correlator. This correlator is the string value of the result attribute from the response body for the appropriate Play (Audio/Text/VoiceXML) Message operation.
http://host:port/rest/audio_call/call?endMessage=${endMessage}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
endMessage contains the call identifier from the response body for the appropriate Play (Audio/Text/VoiceXML) Message operation as the string value for the correlator attribute.
The ${endMessage} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"correlator": "String"}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The response body contains a data object with the current status of the audio file as the value of the result attribute. The value can be one of the following:
Played
Playing
Pending
Error
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "Played|Playing|Pending|Error"}
Example 13-9 End Message Request
DELETE /rest/audio_call/end-call?endMessage=%7B%22correlator%22%3A%22app-gfim8nqt869v%7cb4142a2f38d1d1e6341c897734c93a91%4010.182.100.142%7c-40d94a935cd12af0%22%7D HTTP/1.1 X-Session-ID: app:6567114150306510708 Authorization: Basic YXBwXzFfdToxMjM0NTY30A= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.132.8001
|
 Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|