dialogic® powermedia™ xms restful api/media/manuals/xms/xms_restfulapide… · restful api...
TRANSCRIPT
Dialogic® PowerMedia™ Extended Media Server (XMS) RESTful API
Developer’s Guide
February 2012 05-2703-001
www.dialogic.com
Copyright and Legal Notice
Copyright © 2012 Dialogic Inc. All Rights Reserved. You may not reproduce this document in whole or in part without permission in writing from Dialogic Inc. at the address provided below.
All contents of this document are furnished for informational use only and are subject to change without notice and do not
represent a commitment on the part of Dialogic Inc. and its affiliates or subsidiaries (“Dialogic”). Reasonable effort is made to
ensure the accuracy of the information contained in the document. However, Dialogic does not warrant the accuracy of this information and cannot accept responsibility for errors, inaccuracies or omissions that may be contained in this document.
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC® PRODUCTS. NO LICENSE,
EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS
GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND
DIALOGIC, DIALOGIC ASSUMES NO LIABILITY WHATSOEVER, AND DIALOGIC DISCLAIMS ANY EXPRESS OR
IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF DIALOGIC PRODUCTS INCLUDING LIABILITY OR
WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT
OF ANY INTELLECTUAL PROPERTY RIGHT OF A THIRD PARTY.
Dialogic products are not intended for use in certain safety-affecting situations. Please see http://www.dialogic.com/company/terms-of-use.aspx for more details.
Due to differing national regulations and approval requirements, certain Dialogic products may be suitable for use only in
specific countries, and thus may not function properly in other countries. You are responsible for ensuring that your use of such
products occurs only in the countries where such use is suitable. For information on specific products, contact Dialogic Inc. at the address indicated below or on the web at www.dialogic.com.
It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this document, in
marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more patents or other intellectual
property rights owned by third parties. Dialogic does not provide any intellectual property licenses with the sale of Dialogic
products other than a license to use such product in accordance with intellectual property owned or validly licensed by Dialogic
and no such licenses are provided except pursuant to a signed agreement with Dialogic. More detailed information about such
intellectual property is available from Dialogic’s legal department at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada
H4M 2V9. Dialogic encourages all users of its products to procure all necessary intellectual property licenses required to
implement any concepts or applications and does not condone or encourage any intellectual property infringement and
disclaims any responsibility related thereto. These intellectual property licenses may differ from country to country and it
is the responsibility of those who develop the concepts or applications to be aware of and comply with different national
license requirements.
Dialogic, Dialogic Pro, Dialogic Blue, Veraz, Brooktrout, Diva, Diva ISDN, Making Innovation Thrive, Video is the New
Voice, VisionVideo, Diastar, Cantata, TruFax, SwitchKit, SnowShore, Eicon, Eiconcard, NMS Communications, NMS
(stylized), SIPcontrol, Exnet, EXS, Vision, PowerMedia, PacketMedia, BorderNet, inCloud9, I-Gate, ControlSwitch,
NaturalAccess, NaturalCallControl, NaturalConference, NaturalFax and Shiva, among others as well as related logos, are either
registered trademarks or trademarks of Dialogic Inc. and its affiliates or subsidiaries. Dialogic's trademarks may be used publicly
only with permission from Dialogic. Such permission may only be granted by Dialogic’s legal department at 9800 Cavendish
Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Any authorized use of Dialogic's trademarks will be subject to full
respect of the trademark guidelines published by Dialogic from time to time and any use of Dialogic’s trademarks requires proper acknowledgement.
The names of actual companies and products mentioned herein are the trademarks of their respective owners.
This document discusses one or more open source products, systems and/or releases. Dialogic is not responsible for your decision
to use open source in connection with Dialogic products (including without limitation those referred to herein), nor is Dialogic
responsible for any present or future effects such usage might have, including without limitation effects on your products, your business, or your intellectual property rights.
3
Table of Contents
1. Overview ....................................................................................................... 5 RESTful API Description ................................................................................... 6
Client Side Technologies ............................................................................... 6 RESTful API with HTTP Methods ........................................................................ 7
RESTful API Request/Response Model ............................................................. 7 XML Schema Definition ................................................................................. 8 Event Streaming .......................................................................................... 8
2. Resource-Based Components ....................................................................... 10 Application ID (appid) ................................................................................. 10
3. Call Resource ............................................................................................... 11 <call> Properties ......................................................................................... 14 <call_response> Properties ............................................................................ 16 <calls_response> Properties .......................................................................... 17 <call_action> Properties ................................................................................ 18 XML Schema Definitions for Call ...................................................................... 22
Call Action Scenarios .................................................................................. 25
4. Conference Resource ................................................................................... 30 <conference> Properties................................................................................ 34 <conference_response> Properties ................................................................. 35 <conf_action> Properties ............................................................................... 36 XML Schema Definition for Conference ............................................................. 38
Conference Example ................................................................................... 39
5. Event Handler .............................................................................................. 40 <eventhandler> Properties ............................................................................ 42 <eventsubscribe> Properties .......................................................................... 42 <eventhandler_response> Properties .............................................................. 43 <eventhandlers_response> Properties ............................................................. 43 XML Schema Definition for Eventhandler .......................................................... 43
Event Handler Example ............................................................................... 45
6. Events .......................................................................................................... 46 <event_data> Properties ............................................................................... 46 <event> Properties ....................................................................................... 46 Event Types ................................................................................................. 47
XML Schema Definition for Events ................................................................ 49
7. Appendix A .................................................................................................. 51
4
Revision History
Revision Release date Notes
05-2703-001 February 2012 Initial release of document.
05-xxxx-001-01 January 2012 Preliminary release of this document.
Refer to www.dialogic.com for product updates and for information about support policies, warranty information, and service offerings.
Overview
5
1. Overview
This guide provides information about the Dialogic® PowerMedia™ Extended Media Server
(herein referred to as PowerMedia XMS) RESTful API Interface, including available features
and resource-based component definitions.
The PowerMedia XMS RESTful API is one of several APIs that can be used to drive the XMS
multimedia server. The architectural diagram below shows how the RESTful interface fits into XMS.
Figure 1. PowerMedia XMS RESTful Call and Media Features
Two web servers are used in XMS:
Apache server
Controls a web-based interface for operations, administration and maintenance of the
server.
lighttp server
Processes call control and media commands delivered via the RESTful API as described in
this Guide. The lighttpd server includes a Fast Common Gateway Interface (FCGI) process, which allows efficient interfacing between the server processes.
The XMS server translates RESTful commands into the Host Media Processing (HMP) media
engine’s low-level API. The media engine itself handles SIP calls, plays and records multimedia and mixes multimedia conferences.
PowerMedia XMS provides two call control models:
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
6
1st party call control (1PCC) is where the application can send commands to the
PowerMedia XMS to establish SIP calls on the application’s behalf. In this model, the
application does not need to be involved in making or receiving SIP calls and related
SDP negotiation.
3rd party call control (3PCC) is where the application handles SIP calls and SDP
negotiation, and the PowerMedia XMS only performs media processing operations.
RESTful API Description
PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful) approach.
This web service is a software system designed to support interoperable machine-to-
machine interactions over a network, using the HTTP protocol.
A RESTful API consists of a series of requests and responses that are built around the
transfer of representations of “resources.” These resources accessed through Universal Resource Indicators (URIs).
A RESTful architecture is a client-server architecture where clients initiate requests to
servers and servers process the requests and return appropriate responses. The Dialogic®
PowerMedia XMS RESTful API is a media control interface using HTTP requests and responses to control the features provided by the product.
Client Side Technologies
The client side refers to the client that communicates with the PowerMedia XMS media
server and directs the server’s session with the caller. There is a great deal of flexibility in
selecting an appropriate client-side platform based on application needs and developer skill
set. Essentially, any language or operating system may be used to build a client. The main
requirement is that it supports HTTP and XML.
Several sample development platforms are listed below. Comments are included on
multithreading (important for the event handler) and any facilities to make HTTP and XML handling easy.
• Java - Object-oriented, operating system-independent programming environment.
Fully multithreaded. Several XSD/XML parsers available, as well as HTTP client
class libraries.
NOTE: The Dialogic verification demo used with PowerMedia XMS is a Java application.
• Python – operating system-independent interpreted scripting language. POSIX
threading available. HTTP protocol client library and Python XML/Schema processing tool are available.
• .NET – Integral Microsoft Windows component that supports building and running of
applications and XML Web services. HTTP module and XSD schema definition tool are available.
• Ruby –Open source scripting language. Multiprocessing model may be needed for event handler. HTTP client API and XSD validation tools are available.
• C/C++ - General purpose programming languages. Fully multithreaded. cURL library
(http://curl.haxx.se) may be used for HTTP processing and Xerces C++ XML
parser (http://xerces.apache.org/xerces-c) for XML.
Overview
7
RESTful API with HTTP Methods
In the RESTful API, four HTTP methods are used and can be translated to the actions shown in Table 1.
Table 1. HTTP Methods
HTTP
Method
Request (Action Taken) Response Body
GET Retrieve information for all
instances of a specific resource
type, or retrieve information regarding a specific resource.
Contents of resource information.
Applies to all instances of a
specific resource type or an individual resource.
POST Create a new resource. Contents of a newly created resource.
PUT Modify an existing resource. Contents of an updated resource.
DELETE Delete an existing resource. N/A
RESTful API Request/Response Model
The HTTP request/response model is the mechanism by which media control functionality is
invoked. A RESTful HTTP request is sent to the XMS REST Web Service. The HTTP response
carries the resulting response code of the operation as well as a response body if it applies
to the specific operation. The payload type used for the message body is XML.
For example, if a client wished to retrieve a list of all call resources currently active on the
PowerMedia XMS RESTful web service, it would issue an HTTP GET request. The following
HTTP GET request would be sent by the client to the PowerMedia XMS RESTful interface running on the web service with the IP address of <server>:
http://<server>/default/calls?appid=app
If successful, the response code to the HTTP GET would be 200 OK. The response body
would resemble the following sample:
<web_service version="1.0">
<calls_response size="2">
<call_response appid="master"
identifier="123zdasdkz”
href=http://<server>/default/calls/123zdasdkz
cpa = "yes"
signalling = "yes"
source_uri=sip:[email protected]
call_type="inbound" />
<call_response
identifier="178zdasdkz”
href=http://<server>/default/calls/178zdasdkz
cpa = "no"
signalling = "no"
sdp=[sdp]
call_type="3pcc" />
</calls_response>
</web_service>
The above example shows a client requesting information for all calls with a response of two
active identifiers along with the properties of each call resource.
If a client wanted to retrieve information for only a single specific call resource, it would invoke the following HTTP GET request. The specific call identifier is part of the GET URL.
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
8
http://<server>/default/calls/1279697438?appid=app
If successful, the response code to the HTTP GET would be 200 OK. The response body
would be as follows:
<web_service version="1.0">
<call_response appid="master"
identifier="1279697438”
href=http://<server>/default/calls/1279697438
cpa = "yes"
signalling = "yes"
source_uri=sip:[email protected]
call_type="inbound">
</calls_response>
</web_service>
Additional request/response examples are contained within Chapter 2. Resource-Based Components.
XML Schema Definition
PowerMedia XMS uses an XML schema definition (XSD) which formally describes the
structure, content and semantics of the XML payload for the PowerMedia XMS RESTful API
call and media commands.
There are many benefits to using an XSD. An XSD may be used to generate client-side code
allowing contents of XML documents to be treated as objects. Because XSD enforces type-
checking, it supports client-side validation of the XML payload before it is sent to the PowerMedia XMS RESTful call and media web service.
Definitions of individual elements are referenced throughout this Guide. The full XML
Schema Definition is provided in Appendix A of this Guide.
Event Streaming
While most RESTful applications fit well into the HTTP request/response model, telephony
applications must be able to handle unsolicited events such as digit detection and play
completion. HTTP supports other mechanisms that enable the handling of these events or client notifications.
This concept is called Comet or HTTP event streaming. In a normal HTTP interaction, the
client sends a request to the server, which processes it and sends the HTTP response. The
connection between the client and server is then closed. This process will take place
continuously as long as the web service is running; however, with HTTP event/data
streaming, a reliable TCP connection remains open after the response is sent from the server, allowing the server to continue to send raw data to the client without notice.
HTTP event streaming is implemented in the PowerMedia XMS RESTful web service
EventHandler resource. When the client wishes to receive asynchronous events, it uses an
HTTP POST to create an EventHandler and subscribe to specific event types. The client then
performs an HTTP GET on the newly created EventHandler and the PowerMedia XMS
RESTful web service responds with a 200 OK; however, the TCP connection remains
open. Any event data related to resources and event types are pushed to the client until the
Eventhandler is deleted by the client.
The following diagram provides an example scenario where a client creates an EventHandler and receives digit detection and play completion events:
Overview
9
Client Web ServiceHTTP POST
HTTP POST to create new EventHandler
http://<server>/default/eventHandlers?appid=master
<web_service version="1.0">
<eventhandler>
<eventsubscribe action="add" type="any" resourceid="any" resourcetype="any"/>
</eventhandler>
</web_service>
201 CREATED
201 CREATED Response
<web_service version="1.0">
<eventhandler_response identifier="a801ffa1-1e4b-4e11-85e6-c5d04c185401" appid="master"
href="http://server/defaultl/eventhandlers/a801ffa1-1e4b-4e11-85e6-c5d04c185401">
<eventsubscribe type="any" resourceid="any" resourcetype="any"/>
</eventhandler_response>
</web_service>
HTTP GET
HTTP GET to retireve events
http://<server>/defalut/eventhandlers/a801ffa1-1e4b-4e11-85e6-c5d04c185401?appid=master
200 OK
200 OK Response
No Body (TCP Connection remains open)
Event Data
Event Data
<web_service version="1.0">
<event type="dtmf" resourceid="7bfc5cc2-45c3-4ab9-bb41-67af4e43972c" resourcetype="call">
<data name="digits" value="1" />
<data name="transition_id" value="8bfc5cc2-45c3-4ab9-bb41-67af4e43972c" />
</event>
</web_service>
<web_service version="1.0">
<event type="end_play" resourceid="5974c8b5-8a3c-4a8e-ae82-8f7c8bd0efd5" resourcetype="player">
<data name="reason" value="EOF" />
<data name="duration" vaule="30s" />
<data name="transition_id" value="0974c8b5-8a3c-4a8e-ae82-8f7c8bd0efdd" />
</event>
</web_service>
Figure 2. Example of Event Streaming
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
10
2. Resource-Based Components
There are three resource-based component types supported by the PowerMedia XMS RESTful web service.
Call
Conference
Eventhandler
Each component definition is broken down into modular resource-based components. Each
component makes use of the various HTTP methods. The tables for each HTTP method
define the request body content type if a request body is allowed. In addition, the tables
supply the possible return code values as well as the response body content type. Each
resource component listed below also contains a sample payload for that specific resource
type. This XML content is used in both HTTP requests and responses when utilizing the interface. Refer to the specific chapter for information about these components.
Application ID (appid)
The appid shown in the URL request examples is for identifying the resources used, owned and created by the application. For example:
<web_service version="1.0">
<call_response
appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
signalling = "yes"
source_uri=[uri]
sdp=[sdp]
call_type="inbound" />
</web_service>
PowerMedia XMS allows you to define discrete application IDs (appid) so that multiple
applications may be simultaneously run on a single XMS server. The application ID indicates
the ownership of a RESTful resource so that each resource that is created has an associated
appid. The resources can only be viewed, modified, or deleted by the application with the
matching appid. The appid is used throughout the PowerMedia XMS RESTful API to identify the intended application.
NOTE: The appid is pre-defined in the Routing Screen on the PowerMedia XMS web-based
GUI which is used for post-operating system installation and configuration tasks. Refer to
the Dialogic® PowerMedia™ XMS Installation and Configuration Guide for detailed
information about the PowerMedia XMS Admin Console. There, new appids may be added or
unwanted appids can be removed. It also allows pattern matching on SIP URIs to direct
calls to a specific appid.
Call Resource
11
3. Call Resource
The Call Resource owns the creation and management of a media/signal connection between the remote media endpoint and the PowerMedia XMS RESTful web service.
The call resource has the following types:
Inbound
The call resource is created by the PowerMedia XMS RESTful web service when an incoming call is received. The application is then informed via the eventhandler.
Outbound
The call resource is requested by the application that wishes to make a media stream connection from the PowerMedia XMS RESTful web service to a SIP Termination.
3PCC
The call resource is requested by the application without requesting the PowerMedia
XMS RESTful web service to provide signaling control. The call resource will be created based on the SDP info that is provided by the application.
Media-related properties and actions associated with the media connection are defined in
this section. These include play, playcollect, playrecord, overlay, join/unjoin,
add_party/update_party/remove_party, and stop.
The following tables show the HTTP method that can performed on a call or calls:
URL: /calls?appid=[appid]
HTTP Method GET
Description Get all calls
Request XML Payload N/A
HTTP Return Code 200 OK if success
404 NOT FOUND
Response XML Payload <web_service version="1.0">
<calls_response size="2">
<call_response
appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
signalling = "yes"
source_uri=[uri]
sdp=[sdp]
call_type="inbound" />
<call_response
appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
signalling = "no"
sdp=[sdp]
call_type="3pcc" />
</calls_response>
</web_service>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
12
URL: /calls/[call_id]?appid=[appid]
HTTP Method GET
Description Get a call
Request XML Payload N/A
HTTP Return Code 200 OK if success
404 NOT FOUND
Response XML Payload <web_service version="1.0">
<call_response
appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
signalling = "yes"
source_uri=[uri]
sdp=[sdp]
call_type="inbound" />
</web_service>
URL: /calls?appid=[appid]
HTTP Method DELETE
Description Delete a call
Request XML Payload N/A
HTTP Return Code N/A
Response XML Payload N/A
URL: /calls/[call_id]?appid=[appid]
HTTP Method DELETE
Description Delete a call
Request XML Payload N/A
HTTP Return Code 204 Deleted if success
404 NOT FOUND
Response XML Payload N/A
Call Resource
13
URL: /calls?appid=[appid]
HTTP Method POST
Description Create a call
* Creating a outbound sip call
* Creating a call without sip call control
sdp has to be specifed
Request XML Payload <web_service version="1.0">
<call destination_uri="[email protected]"
cpa="on"
</call>
</web_service>
or
<web_service version="1.0">
<call signalling = "no"
sdp=[sdp]
</call>
</web_service>
HTTP Return Code 201 Created if success
404 NOT FOUND or 500 base Server side error
Response XML Payload <web_service version="1.0">
<call_response
appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
cpa = "yes"
signalling = "yes"
destination_uri= sip_uri
call_type="outbound" />
</web_service>
or
<web_service version="1.0">
<call_response appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
signalling = "no"
sdp=[sdp]
call_type="3pcc" />
</web_service>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
14
URL: /calls_id?appid=[appid]
HTTP Method PUT
Description Update a call
* Answer an inbound sip call
* Perform one of the following action per request
** play
** update_play
** playrecord
** playcollect
** overlay
** stop
** add_party
** update_party
** remove_party
** join
** unjoin
Request XML Payload <web_service version="1.0">
<call answer = "yes" >
<call_action>
<play> ...</play>
</call_action>
</call>
</web_service>
HTTP Return Code 200 OK if success
404 NOT FOUND or 500 base Server side error
Response XML Payload <web_service version="1.0">
<call_response appid="[appid]"
identifier="[call_id]"
href="[base_url]/calls/[call_id]?appid=[appid]"
cpa = "yes"
signalling = "yes"
source_uri = [email protected]
call_type="inbound" />
<call_action>
<play transaction_id=[transition_id]...</play>
</call_action>
</call_response>
</web_service>
<call> Properties
Parameter Description HTTP Method
signaling
Specifies if signaling is done by this media server or a third party application server. Valid values are Yes for PowerMedia XMS
and No for a third party application server. The default value is Yes.
POST
sdp
Session Description Protocol data. This parameter is set by the system and only used for 3rd party call control.
POST/PUT
Call Resource
15
Parameter Description HTTP Method
media
Sets the media type supported by the call. Valid values are Audio or Audiovideo. The default is Audio.
NOTE: For update call scenario, this
parameter will only take effect when answering an inbound call.
POST/PUT
dtmf_mode
Specifies the signaling mode for DTMF digits. Valid values are Inband, Outofband, or Rfc2833. The default is Rfc2833.
NOTE: For update call scenario, this
parameter will only take effect when answering an inbound call.
POST/PUT
async_dtmf
Specifies if DTMF digits are reported as events outside of a playcollect action. Valid values are Yes or No.
POST/PUT
rx_delta Volume adjustments are allowed between +31dB and -32dB.
POST/PUT
tx_delta Volume adjustments are allowed between +31dB and -32dB.
POST/PUT
async_tone Specifies if tones are reported as events
outside of a playcollect action. Valid values are Yes or No.
POST/PUT
cleardigits
Specifies whether previous, buffered, input should be discarded. This parameter is is considered when async_dtmf is set to Yes. Valid values are Yes or No.
POST/PUT
destination_uri
Specifies the SIP destination address only for creating an outbound SIP call.
POST
source_uri Specifies the Caller address.
POST
cpa Specifies if call progress detection is used
for an outbound call. Valid values are Yes or No. The default is No.
POST
call_action Refer to <call_action> properties. PUT
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
16
<call_response> Properties
Parameter Description
identifier A unique ID of a call resource.
href The http: address of a call resource.
appid A unique application ID included in the original HTTP POST
creation process that is utilized by the web service such that
clients only have access to resources that they created.
call_type Indicates the type of call. Valid values are Inbound, Outbound, or 3PCC (3rd party call control).
signaling Specifies if signaling is done by this media server or a third party application server. Valid values are Yes for PowerMedia XMS and No for a third party application server.
sdp Session Description Protocol data. This parameter is only used for 3rd party call control.
media Specifies the media type supported by the call. Valid values are
Audio or Audiovideo.
destination_uri Specifies the SIP destination address only for an outbound SIP call.
source_uri Specifies the Caller address.
cpa Specifies if call progress detection is used for an outbound call. Valid values are Yes or No.
async_dtmf Specifies if DTMF digits are reported as events outside of a
playcollect action. Valid values are Yes or No.
dtmf_mode Specifies the signaling mode for DTMF digits. Valid values are
Inband, Outofband, or Rfc2833.
cleardigits Specifies whether previous, buffered, input should be discarded. This parameter is is considered when async_dtmf is set to Yes. Valid values are Yes or No.
async_tone Specifies if tones are reported as events outside of a playcollect action. Valid values are Yes or No.
call_action Refer to <call_action> properties.
Call Resource
17
<calls_response> Properties
Parameter Description
Size Specifies the number of conferences.
call_response Refer to <conference> properties.
appid A unique application ID included in the original HTTP POST
creation process that is utilized by the web service such that clients only have access to resources that they created.
call_type Indicates the type of call. Valid values are Inbound, Outbound, or 3PCC (3rd party call control).
signaling Specifies if signaling is done by this media server or a third party application server. Valid values are Yes for PowerMedia XMS and No for a third party application server.
sdp Session Description Protocol data. This parameter is only used
for 3rd party call control.
media Specifies the media type supported by the call. Valid values are
Audio or Audiovideo.
destination_uri Specifies the SIP destination address only for an outbound SIP call.
source_uri Specifies the Caller address.
cpa Specifies if call progress detection is used for an outbound call. Valid values are Yes or No.
async_dtmf Specifies if DTMF digits are reported as events outside of a playcollect action. Valid values are Yes or No.
dtmf_mode Specifies the signaling mode for DTMF digits. Valid values are
Inband, Outofband, or Rfc2833.
cleardigits Specifies whether previous, buffered, input should be discarded. This parameter is is considered when async_dtmf is set to Yes. Valid values are Yes or No.
async_tone Specifies if tones are reported as events outside of a
playcollect action. Valid values are Yes or No.
call_action Refer to call_action properties.
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
18
<call_action> Properties
Parameter Description Property
play_source Specifies the file location and file to
play. Refer to <play_source>
properties.
<play>
dvr_setting Specifies the DVR setting for the play. Refer to <dvr_setting> properties.
<play>
offset
Specifies the time offset from where the
play should start (.wav files only). The
offset is applied to the initial play only.
The default is zero (0) seconds.
<play>
repeat
Number of times to repeat the play. Use
"infinite" to repeat indefinitely. "file://"
URIs only. The default is zero (0) seconds.
<play>
delay Time delay between repeated plays. The
default is one (1) second.
<play>
terminate_digits The digit or digits [0-9,*,#] used to
terminate the play. Valid values are 0-9, * or #. The default value is #.
<play>
max_time Specifies the playback time limit. The default value is infinite.
<play>
skip_interval
Defines the amount of time to skip on
the 'forward' and 'backwards' actions. The default is one (1) second.
<play>
location The URL of the content to be played in
the prompt phase (e.g., "file://...", "rtsp://...", "image:")
<play_source>
forward_key
Defines the DTMF key used to skip
forwards. Valid values are 0-9, * or #. The default value is 1.
<dvr_setting>
backward_key Defines the DTMF key used to skip
backwards. Valid values are 0-9, * or #. The default value is 2.
<dvr_setting>
pause_key
Defines the DTMF key used to pause
playback. Valid values are 0-9, * or #. The default value is 3.
<dvr_setting>
Call Resource
19
Parameter Description Property
resume_key Defines the DTMF key used to resume
playback. Valid values are 0-9, * or #. The default value is 4.
<dvr_setting>
restart_key Defines the DTMF key used to restart
playback. Valid values are 0-9, * or #.
The default value is 5.
<dvr_setting>
dvr_action
A DVR action performed on the play. It
is specified with the transaction ID.
Valid values are:
"backward" - Skip backwards
"forward" - Skip forward
"pause" - Pause playback
"restart" - Jump back to the start
"resume" - resumed paused playback
<update_play>
transaction_id A unique ID that is assigned by the
PowerMedia XMS RESTful web service for the play action.
<update_play>
play_source Specifies the location and name of the
file to play. Refer to the <play_source>
properties.
<play_record>
and
<play_collect>
recording_uri Specifies the filename "file://..." <play_record>
offset
Specifies the time offset from where the play should start (.wav files only).
NOTE: Applies only to the initial play.
<play_record>
and <play_collect>
repeat Specifies the number of times to repeat
the play.
<play_record>
and <play_collect>
delay
Specifies the time delay between
repeated plays. The default value is one (1) second.
<play_record>
and <play_collect>
terminate_digits The digit or digits [0-9,*,#] used to
terminate the play_record.
<play_record>
and <play_collect>
beep
Specifies whether to play a tone when
starting to record. Valid values are Yes or No.
<play_record>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
20
Parameter Description Property
max_time The maximum length of time to record. <play_record>
barge
Specifies whether DTMF digit input will
barge the prompt and force transition to
the record phase. Valid values are Yes or No.
NOTE: If barge is set to No, the
cleardigits parameter implicitly has the value Yes.
<play_record>
and <play_collect>
cleardigits
Specifies whether previous input should
be considered or ignored for the
purpose of barge-in. Valid values are
Yes or No.
When set to Yes, any previously
buffered digits are discarded. When set
to No, previously buffered digits will be
considered.
When set to No, with the barge
parameter set to Yes, previously
buffered digits will result in the
recording phase starting immediately,
and the prompt will not be played.
<play_record>
and <play_collect>
transaction_id
A unique ID assigned by PowerMedia
XMS RESTful API for the specific
<playrecord>, <play_collect>, or <overlay> action.
<play_record>
and
<play_collect> and <overlay>
max_digits Specifies the maximum number of digits
to collect.
<play_collect>
timeout
Specifies the maximum length of time to
wait for digits or tones. This time begins
when the prompt phase ends. The default
value is inifinite.
<play_collect>
tone_detection Enable tone detection. Valid values are
Yes or No. The default value is No. <play_collect>
uri
The template parameters passed to the
image builder. image:id=template&a=b..."
<overlay>
duration The length of time that the overlay is
shown. Use "infinite" without the quotes to display until the overlay stops.
<overlay >
Call Resource
21
Parameter Description Property
transaction_id
An identifier returned by <play>
<playrecord> <play_collect> or <overlay> action.
<stop>
conf_id Specifies the conference identifies. <add party> and <update_party>
caption Specifies text for caption, e.g., caller name.
<add party>
region
Specifies the video pane used to display
this participant's video stream. The
value 0 (zero) means no preference.
The current occupant of the region (if
any) will be reset to no preference and replaced by this party.
<add party> and <update_party>
audio
Sets the conference audio participation.
Valid values are:
"inactive" - No audio
"sendonly" - Only transmit audio
"recvonly" - Only receive audio
"sendrecv" - Full duplex audio
The value "recvonly" is the default.
<add party> and
<update_party>
video
Sets the conference video participation.
Valid values are:
"inactive" - No video
"sendonly" - Only transmit video
"recvonly" - Only receive video
"sendrecv" - Full duplex video
The value "recvonly" is the default.
<add party> and
<update_party>
conf_id Specifies the conference identifier of the party to remove.
<remove_party>
call_id Specifies the call identifier on which to perform the action.
<join> and <unjoin>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
22
XML Schema Definitions for Call
HTTP Post/Put Request payload:
<xs:element name="call">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_action" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="answer" type="boolean_type"/>
<xs:attribute name="signaling" type="boolean_type" default="yes" />
<xs:attribute name="source_uri" type="xs:string" />
<xs:attribute name="destination_uri" type="xs:string" />
<xs:attribute name="sdp" type="xs:string"/>
<xs:attribute name="media" type="media_type" default=”audio”/>
<xs:attribute name="cpa" type="boolean_type" default="no"/>
<xs:attribute name="dtmf_mode" type="dtmf_mode_option"
default="rfc2833"/>
<xs:attribute name="async_dtmf" type="boolean_type" />
<xs:attribute name="async_tone" type="boolean_type" />
<xs:attribute name="rx_delta" type="xs:string" />
<xs:attribute name="tx_delta" type="xs:string" />
<xs:attribute name="cleardigits" type="boolean_type" />
</xs:complexType>
</xs:element>
Single call instance response payload:
<xs:element name="call_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_action" minOccurs="0" />
</xs:sequence>
<xs:attribute name="signaling" type="boolean_type" />
<xs:attribute name="destination_uri" type="xs:string" />
<xs:attribute name="source_uri" type="xs:string" />
<xs:attribute name="call_type" type="call_type_option" />
<xs:attribute name="sdp" type="xs:string"/>
<xs:attribute name="cpa" type="boolean_type" />
<xs:attribute name=”media” type=”media_type” />
<xs:attribute name="dtmf_mode" type="dtmf_mode_option" />
<xs:attribute name="async_dtmf" type="boolean_type" />
<xs:attribute name="async_tone" type="boolean_type" />
<xs:attribute name="cleardigits" type="boolean_type" />
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
Get all instances response payload:
<xs:element name="calls_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_response" minOccurs="0" />
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
Call_action:
<xs:element name="call_action">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element ref="play" />
<xs:element ref="update_play" />
<xs:element ref="playcollect" />
<xs:element ref="playrecord" />
<xs:element ref="overlay" />
Call Resource
23
<xs:element ref="stop" />
<xs:element ref="join" />
<xs:element ref="unjoin" />
<xs:element ref="add_party" />
<xs:element ref="update_party" />
<xs:element ref="remove_party" />
</xs:choice>
</xs:complexType>
</xs:element>
Play:
<xs:element name="play">
<xs:complexType>
<xs:sequence>
<xs:element ref="play_source" minOccurs="1" maxOccurs="1" />
<xs:element ref="dvr_setting" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="offset" type="xs:string" default="0" />
<xs:attribute name="repeat" type="xs:string" default="0" />
<xs:attribute name="delay" type="time_value" default="1s" />
<xs:attribute name="skip_interval" type="time_value" default="1s" />
<xs:attribute name="max_time" type="time_value" />
<xs:attribute name="terminate_digits" type="digit_value" default="#"/>
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
Update_play:
<xs:element name="update_play">
<xs:complexType>
<xs:attribute name="dvr_action" type="dvr_action_option" />
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
Playrecord:
<xs:element name="playrecord">
<xs:complexType>
<xs:sequence>
<xs:element ref="source" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="barge" type="boolean_type" default="yes" />
<xs:attribute name="cleardigits" type="boolean_type" default="no" />
<xs:attribute name="offset" type="xs:string" default="0" />
<xs:attribute name="repeat" type="xs:string" default="0" />
<xs:attribute name="delay" type="xs:string" default="1s" />
<xs:attribute name="recording_uri" type="xs:string" use="required" />
<xs:attribute name="beep" type="boolean_type" default="yes" />
<xs:attribute name="terminate_digits" type="digit_value" default="#"/>
<xs:attribute name="max_time" type="time_value" />
<xs:attribute name=" transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
Playcollect:
<xs:element name="playcollect">
<xs:complexType>
<xs:sequence>
<xs:element ref="source" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="barge" type="boolean_type" default="yes" />
<xs:attribute name="cleardigits" type="boolean_type" default="no" />
<xs:attribute name="offset" type="xs:string" default="0" />
<xs:attribute name="repeat" type="xs:string" default="0" />
<xs:attribute name="delay" type="xs:string" default="1s" />
<xs:attribute name="max_digits" type="xs:string" />
<xs:attribute name="terminate_digits" type="digit_value" default="#"/>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
24
<xs:attribute name="timeout" type="time_value" />
<xs:attribute name="tone_detection" type="boolean_type" default="yes" />
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
Overlay:
<xs:element name="overlay">
<xs:complexType>
<xs:attribute name="uri" type="xs:string" use="required"/>
<xs:attribute name=" transaction _id" type="xs:string" />
</xs:complexType>
</xs:element>
Stop:
<xs:element name="stop">
<xs:complexType>
<xs:attribute name=" transaction_id" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
Add_party:
<xs:element name="add_party">
<xs:complexType>
<xs:attribute name="conf_id" type="xs:string" use="required" />
<xs:attribute name="audio" type="media_direction" default="recvonly" />
<xs:attribute name="video" type="media_direction" default="recvonly" />
<xs:attribute name="caption" type="xs:string" />
<xs:attribute name="region" type="xs:string" default="0"/>
</xs:complexType>
</xs:element>
Update_party:
<xs:element name="update_party">
<xs:complexType>
<xs:attribute name="conf_id" type="xs:string" />
<xs:attribute name="audio" type="media_direction" />
<xs:attribute name="video" type="media_direction" />
<xs:attribute name="caption" type="xs:string" />
<xs:attribute name="region" type="xs:string" />
</xs:complexType>
</xs:element>
Remove_party:
<xs:element name="remove_party">
<xs:complexType>
<xs:attribute name="conf_id" type="xs:string" />
</xs:complexType>
</xs:element>
Join:
<xs:element name="join">
<xs:complexType>
<xs:attribute name="call_id" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
Call Resource
25
Unjoin:
<xs:element name="unjoin">
<xs:complexType>
<xs:attribute name="call_id" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
Call Action Scenarios
This section provides several diagrams detailing specific call actions.
XMS App REST Web Service
Incoming call
HTTP PUT (To accept the inbound call)
size = 68
<web_service version="1.0">
<even type="incoming" resource_type="call" resource_id="b5387014-c20f-4316-a8f0-988bb29a47b3" >
<event_data caller_uri="sip:[email protected]" uri="sip:[email protected]"/>
</event>
</web_service>
HTTP POST
HTTP POST to create new EventHandler
http://<server>/default/eventHandlers?appid=master
<web_service version="1.0">
<eventhandler>
<eventsubscribe action="add" type="any" resource_id="any" resource_type="any"/>
</eventhandler>
</web_service>
201 CREATED Response
<web_service version="1.0">
<eventhandler_response identifier="a801ffa1-1e4b-4e11-85e6-c5d04c185401" appid="master"
href="http://server/defaultl/eventhandlers/a801ffa1-1e4b-4e11-85e6-c5d04c185401">
<eventsubscribe type="any" resource_id="any" resource_type="any"/>
</eventhandler_response>
</web_service>
201 CREATED
HTTP GET
HTTP GET to retireve events
http://<server>/defalut/eventhandlers/a801ffa1-1e4b-4e11-85e6-c5d04c185401?appid=master
200 OK
200 OK Response
No Body (TCP Connection remains open)
call
Create an inbound call resource
Incoming Event
HTTP PUT to accept the call
http://<server>/default/calls/b5387014-c20f-4316-a8f0-988bb29a47b3?appid=master
<web_service version="1.0">
<call answer="yes"/>
</web_service>
answer
HTTP 200 OK
HTTP 200 ok response
<web_service version="1.0">
<call_response identifier="b5387014-c20f-4316-a8f0-988bb29a47b3" href="http://<server>/default/calls/b5387014-c20f-4316-a8f0-988bb29a47b3"
appid=master call_type="inbound" media="audio" source_uri="sip:[email protected]" />
</web_service>
Figure 3. Answer/Accept an Inbound Call
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
26
XMS App REST Web ServiceHTTP POST
HTTP POST to create new call resource for outbound call
http://<server>/default/calls?appid=master
<web_service version="1.0">
<call destiination_uri="sip:[email protected]" cpa="yes" async_dtmf="yes"
async_tone="yes" media="video" signalling="yes" />
</web_service>
201 CREATED Response
<web_service version="1.0">
<call_response identifier="b5387014-c20f-4316-a8f0-988bb29a47b3"
href="http://<server>/default/calls/b5387014-c20f-4316-a8f0-988bb29a47b3"
appid=master call_type="outbound" media="video"
destination_uri="sip:[email protected]" cpa="yes" signalling="yes"
async_dtmf="yes" async_tone="yes" />
</web_service>
201 CREATED
HTTP DELETE
HTTP DELETE to hangup the call
http://<server>/default/calls/b5387014-c20f-4316-a8f0-988bb29a47b3"?appid=master
204 DELETED
call
createcall/dial
Create an outbound call resource
hangup/deletecall
Figure 4. Create an Outbound Call
Call Resource
27
The following diagram illustrates the play action process on a call resource. This scenario
assumes a call resource has already been created and the application has an eventhandler
resource to monitor the play events.
NOTE: The process of playcollect, playrecord, and overlay actions are similar to the play action.
Application call
HTTP PUT
HTTP PUT to play a file on the call resource
http://<server>/default/calls/92233fab-cc4a-455f-ae40-918c4e247e6e?appid=master
<web_service version="1.0">
<call>
<action>
<play>
<play_source location="file://myholiday" />
<dvr_setting forward_key="4" backward_key="5" pause_key="6" resume_key="7" restart_key="#" />
</play>
</action>
</call>
</web_service>
200 OK
200 OK Response
<web_service version="1.0">
<call_response appid="master" href="http://<server>/default/calls/92233fab-cc4a-455f-ae40-918c4e247e6e"
identifier="92233fab-cc4a-455f-ae40-918c4e247e6e" ...>
<action>
<play transaction_id ="92233fab-cc4a-455f-ae40-918c4e247e78">
<play_source location="file://myholiday" />
<dvr_setting forward_key="4" backward_key="5" pause_key="6" resume_key="7" restart_key="#" />
</play>
</action>
</call_response>
</web_service>
END_PLAY Event
size = 68
<web_service version="1.0">
<even type="end_play" resource_type="call" resource_id="b5387014-c20f-4316-a8f0-988bb29a47b3" >
<event_data
transaction_id="92233fab-cc4a-455f-ae40-918c4e247e78"
reason="EOF" duration="30s" />
</event>
</web_service>
Figure 5. Play Scenario
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
28
The following diagram illustrates the stop action. A stop action only applies to actions that return
a transaction ID in HTTP response payload. These actions include play, playrecord, playcollect,
and overlay.
application call
HTTP PUT
HTTP PUT to stop an action when it is performing.
http://<server>/default/calls/00c8e0e9-6216-4225-8cf1-0ba00a149d30?appid=master
<web_service version="1.0">
<call>
<action>
<stop transaction_id="00c8e0e9-6216-4225-8cf1-0ba00a149dab"/>
</action>
</call>
</web_service>
200 OK
<web_service version="1.0">
<call_response appid="master" href="http://<server>/default/calls/00c8e0e9-6216-4225-8cf1-0ba00a149d30"
identifier="92233fab-cc4a-455f-ae40-918c4e247e6e" ...>
<action>
<stop transaction_id ="00c8e0e9-6216-4225-8cf1-0ba00a149dab" />
</action>
</call_response>
</web_service>
Figure 6. Stop Scenario
Call Resource
29
application call
HTTP PUT
HTTP PUT to connect call media streams
http://<server>/default/calls/00c8e0e9-6216-4225-8cf1-0ba00a149d30?appid=master
<web_service version="1.0">
<call>
<action>
<join call_id="78c8e0e9-6216-4225-8cf1-0ba00a149d30" />
</action>
</call>
</web_service>
200 OK
join/unjoin action
<web_service version="1.0">
<call_response appid="master" href="http://<server>/default/calls/00c8e0e9-6216-4225-8cf1-0ba00a149d30"
identifier="92233fab-cc4a-455f-ae40-918c4e247e6e" ...>
<action>
<join call_id ="78c8e0e9-6216-4225-8cf1-0ba00a149d30" />
</action>
</call_response>
</web_service>
HTTP PUT
HTTP PUT to disconnect call media streams
http://<server>/default/calls/00c8e0e9-6216-4225-8cf1-0ba00a149d30?appid=master
<web_service version="1.0">
<call>
<action>
<unjoin call_id="78c8e0e9-6216-4225-8cf1-0ba00a149d30" />
</action>
</call>
</web_service>
200 OK
<web_service version="1.0">
<call_response appid="master" href="http://<server>/default/calls/00c8e0e9-6216-4225-8cf1-0ba00a149d30"
identifier="92233fab-cc4a-455f-ae40-918c4e247e6e" ...>
<action>
<unjoin call_id ="78c8e0e9-6216-4225-8cf1-0ba00a149d30" />
</action>
</call_response>
</web_service>
Figure 7. Join/Unjoin Scenario
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
30
4. Conference Resource
The Conference Resource encapsulates a single instance of a conference resource on
PowerMedia XMS. This resource contains the call resources that are currently included in the
active conference.
URL: /conferences?appid=[appid]
HTTP Method GET
Description Get all conferences
Request XML Payload N/A
HTTP Return Code 200 OK if success
404 NOT FOUND
Response XML Payload <web_service version="1.0">
<conferences_response size="2">
<conference_response appid="[appid]"
identifier="[conference_id]"
type="video"
max_parties="9"
layout="0"
caption="yes"
caption_duration="20"
beep = "yes"
clamp_dtmf="yes"
auto_gain_control="yes"
echo_cancellation="yes"
href="[base_url]/conferences/[conference_id]?appid=[appid]">
<conf_participant call_id=""[call_id] .../>
</conference_response >
<conference_response appid="[appid]"
conference_id="[conference_id]"
type="audio"
max_parties="5"
layout="0"
caption="yes"
caption_duration="20"
beep = "yes"
clamp_dtmf="no"
auto_gain_control="yes"
echo_cancellation="yes"
href="[base_url]/conferences/[conference_id]?appid=[appid]">
<conf_participant call_id=""[call_id] .../>
</conference_response >
</conferences_response >
</web_service>
Conference Resource
31
URL: /conferences/[conference_id]?appid=[appid]
HTTP Method GET
Description Get a conference
Request XML Payload N/A
HTTP Return Code 200 OK if success
404 NOT FOUND
Response XML Payload <web_service version="1.0">
<conference_response appid="[appid]"
identifier="[conference_id]"
type="video"
max_parties="9"
layout="2"
caption="yes"
caption_duration="20"
beep = "yes"
clamp_dtmf="yes"
auto_gain_control="yes"
echo_cancellation="yes"
href="[base_url]/conferences/[conference_id]?appid=[appid]">
<conf_participant call_id=""[call_id] ..."/>
<conf_participant call_id=""[call_id] ..."/>
</conference_response>
</web_service>
URL: /conferences?appid=[appid]
HTTP Method DELETE
Description Not Supported
Request XML Payload N/A
HTTP Return Code N/A
Response XML Payload N/A
URL: /conferences/[call_id]?appid=[appid]
HTTP Method DELETE
Description Delete a call
Request XML Payload N/A
HTTP Return Code 204 Deleted if success
404 NOT FOUND
Response XML Payload N/A
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
32
URL: /conferences?appid=[appid]
HTTP Method POST
Description Create a conference
Request XML Payload <web_service version="1.0">
<conferenceroom
max_parties="9"
type="video"
layout="0"
caption="yes"
caption_duration="20"
beep = "yes"
clamp_dtmf="yes"
auto_gain_control="yes"
echo_cancellation="yes" >
</conferenceroom>
</web_service>
HTTP Return Code 201 Created if success
404 NOT FOUND or 500 base Server side error
Response XML Payload <web_service version="1.0">
<conference_response appid="[appid]"
identifier="[conference_id]"
type="video"
max_parties="9"
layout="0"
caption="yes"
caption_duration="20"
beep = "yes"
clamp_dtmf="yes"
auto_gain_control="yes"
echo_cancellation="yes"
href="[base_url]/conferences/[conference_id]?appid=[appid]">
</conference_response >
</web_service>
Conference Resource
33
URL: /conferences/[conference_id]?appid=[appid]
HTTP Method PUT
Description Update a conference
* Update conference attrs
* perform one of the following action per request
** play
** update_play
** stop
Request XML Payload <web_service version="1.0">
<conference layout="2" >
<conf_action>
<play>...</play>
</conf_action>
</conference >
</web_service>
HTTP Return Code 200 OK if success
404 NOT FOUND or 500 base Server side error
Response XML Payload <web_service version="1.0">
<conference_response appid="[appid]"
identifier="[conference_id]"
type="video"
max_parties="9"
layout="2"
caption="yes"
caption_duration="20"
beep = "yes"
clamp_dtmf="yes"
auto_gain_control="yes"
echo_cancellation="yes"
href="[base_url]/conferences/[conference_id]?appid=[appid]">
<conf_action>
<play transaction_id=[transition_id].../>
</conf_action>
</conference_response >
</web_service>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
34
<conference> Properties
Parameter Description HTTP Method
type Sets the media supported by conference. Valid values are audio or audiovideo. The default value is audio.
POST
max_parties Maximum number of parties in a conference. The default is nine (9).
POST
reserve
Number of party resources to reserve for this conference. Any requests beyond this value are honored on a best-effort basis. The default is zero (0).
POST
layout
The number of tiles displayed in the conference output. Valid values are 0, 1, 2,4, 6 or 9. Setting to zero (0) means that the number of tiles displayed is determined by the number of active parties.
POST/PUT
caption Determines if the caller's ID is overlaid on
their image. Valid values are yes or no. The default value is yes.
POST
caption_duration
The length of time that the caption is
shown. Use "infinite" without the quotes to display the caption for the entire call. The default is “20” seconds.
POST
beep Determines if a tone is played when a party joins/leaves a conference. Valid values are yes or no. The default value is yes.
POST
clamp_dtmf Determines if dtmf digits are suppressed. Valid values are yes or no. The default value is yes.
POST
auto_gain_control Determines if automatic gain control should be used. Valid values are yes or no. The default value is yes.
POST
echo_cancellation Determines if echo cancellation should be used. Valid values are yes or no. The default
value is yes.
POST
conf_action Refer to conf_action properties PUT
Conference Resource
35
<conference_response> Properties
Parameter Description
identifier A unique ID of a conference resource.
href The http: address of a conference resource.
appid A unique application ID included in the original HTTP POST
creation process that is utilized by the web service such that
clients only have access to resources that they created.
type Sets the media type supported by the conference. Valid values are audio or audiovideo
max_parties Maximum number of parties in a conference.
reserve Number of party resources to reserve for this conference. Any requests beyond this value are honored on a best-effort basis.
layout
The number of tiles displayed in the conference output. Valid
values are 0, 1, 2, 4, 6 and 9. Setting to zero (0) means that
the number of tiles displayed is determined by the number of
active presenters.
caption Determines if the caller's ID is overlaid on their image. Valid values are Yes or No.
caption_duration The length of time that the caption is shown. Use "infinite" without the quotes to display the caption for the entire call
beep Determines if a tone is played when a party joins/leaves a conference. Valid values are Yes or No.
clamp_dtmf Determines if DTMF digits are suppressed. Valid values are
Yes or No.
auto_gain_control Determines if automatic gain control should be used. Valid values are Yes or No.
echo_cancellation Determines if echo cancellation should be used. Valid values are Yes or No.
conf_action Refer to conf_action properties.
size Number of conferences.
conference_ response
Refer to conference_response properties.
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
36
<conf_action> Properties
Parameter Description Property
play_source
Specifies the file location and file to
play. Refer to <play_source> properties.
<play>
dvr_setting Specifies the DVR setting for the play. Refer to <dvr_setting> properties.
<play>
offset
Specifies the time offset from where the
play should start (.wav files only). The
offset is applied to the initial play only. The default is zero (0) seconds.
<play>
repeat
Number of times to repeat the play. Use
"infinite" to repeat indefinitely. "file://"
uriS only. The default is zero (0)
seconds.
<play>
delay Time delay between repeated plays. The default is one (1) second.
<play>
terminate_digits The digit or digits [0-9,*,#] used to
terminate the play. Valid values are 0-9, * or #. The default value is #.
<play>
max_time Specifies the playback time limit. The
default value is infinite.
<play>
skip_interval Defines the amount of time to skip on
the 'forward' and 'backwards' actions. The default is one (1) second.
<play>
location The URL of the content to be played in
the prompt phase (e.g., "file://...",
"rtsp://...", "image:")
<play_source>
forward_key Defines the DTMF key used to skip
forwards. Valid values are 0-9, * or #. The default value is 1.
<dvr_setting>
backward_key Defines the DTMF key used to skip
backwards. Valid values are 0-9, * or #.
The default value is 2.
<dvr_setting>
pause_key Defines the DTMF key used to pause
playback. Valid values are 0-9, * or #.
<dvr_setting>
Conference Resource
37
The default value is 3.
Parameter Description Property
resume_key Defines the DTMF key used to resume
playback. Valid values are 0-9, * or #. The default value is 4.
<dvr_setting>
restart_key Defines the DTMF key used to restart
playback. Valid values are 0-9, * or #.
The default value is 5.
<dvr_setting>
dvr_action
A DVR action performed on the play. It
is specified with the transaction ID.
Valid values are:
"backward" - Skip backwards
"forward" - Skip forward
"pause" - Pause playback
"restart" - Jump back to the start
"resume" - resumed paused playback
<update_play>
transaction_id
A unique ID that is assigned by the
PowerMedia XMS RESTful web service for the play action.
<update_play>
transaction_id Identifier returned by play <stop>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
38
XML Schema Definition for Conference
Request payload:
<xs:element name="conference">
<xs:complexType>
<xs:sequence>
<xs:element ref="conf_action" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="type" type="media_type" default="audio" />
<xs:attribute name="max_parties" type="xs:string" default="9" />
<xs:attribute name="reserve" type="xs:string" default=”0” />
<xs:attribute name="layout" type="xs:string" >
<xs:attribute name="caption" type="boolean_type" default="yes" />
<xs:attribute name="caption_duration" type="xs:string" default="20s" />
<xs:attribute name="beep" type="boolean_type" default="yes" />
<xs:attribute name="clamp_dtmf" type="boolean_type" default="yes" />
<xs:attribute name="auto_gain_control" type="boolean_type" default="yes"
>
<xs:attribute name="echo_cancellation" type="boolean_type" default="yes"
>
</xs:complexType>
</xs:element>
Single instance response payload:
<xs:element name="conference_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="conf_action" minOccurs="0" maxOccurs="1" />
<xs:element ref="conf_participant" minOccurs="0" />
</xs:sequence>
<xs:attribute name="type" type="media_type" />
<xs:attribute name="max_parties" type="xs:string" />
<xs:attribute name="reserve" type="xs:string" />
<xs:attribute name="layout" type="xs:string" />
<xs:attribute name="caption_duration" type="xs:string" />
<xs:attribute name="beep" type="xs:string" default="yes" />
<xs:attribute name="clamp_dtmf" type="xs:string"/>
<xs:attribute name="auto_gain_control" type="xs:string"/>
<xs:attribute name="echo_cancellation" type="xs:string"/>
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
Get all instances response payload:
<xs:element name="conferences_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="conference_response" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
Conf_participant:
<xs:element name="conf_participant">
<xs:complexType>
<xs:attribute name="call_id" type="xs:string" />
<xs:attribute name="audio" type="media_direction" />
<xs:attribute name="video" type="media_direction" />
<xs:attribute name="caption" type="xs:string" />
Conference Resource
39
<xs:attribute name="region" type="xs:string" />
</xs:complexType>
</xs:element>
Conf_action:
<xs:element name="call_action">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element ref="play" />
<xs:element ref="update_play" />
<xs:element ref="stop" />
</xs:choice>
</xs:complexType>
</xs:element>
Conference Example
The figure below shows the creation/updating/deletion process of a conference. The actions
performed on a conference resource are similar to the play and playrecord action on a call resource.
application REST Web Service
HTTP POST
HTTP POST to create a conference
http://<server>/default/conferences?appid=master
<web_service version="1.0">
<conference type="video" max_parties="9" layout="0" caption="yes" caption_duration="20"
beep = "yes" clamp_dtmf="yes" auto_gain_control="yes" echo_cancellation="yes"/>
</web_service>
201 CREATED
201 CREATED Response
<web_service version="1.0">
<conference_response appid="master" href="http://146.152.37.9:81/DialogicWebService/mediacontrol/conferences/
3513d1ca-96d7-477d-8a56-afc320044f40"
identifier="3513d1ca-96d7-477d-8a56-afc320044f40"
type="video" max_parties="9" layout="0" caption="yes" caption_duration="20"
beep = "yes" clamp_dtmf="yes" auto_gain_control="yes" echo_cancellation="yes"/>
</web_service>
create/update/delete conference
HTTP PUT
HTTP PUT to udpate a conference
http://<server>/default/conferences/3513d1ca-96d7-477d-8a56-afc320044f40?appid=master
<web_service version="1.0">
<conference layout="4" />
</web_service>
200 OK
HTTP DELETE
200 OK Response
<web_service version="1.0">
<conference_response appid="master" href="http://146.152.37.9:81/DialogicWebService/mediacontrol/conferences/
3513d1ca-96d7-477d-8a56-afc320044f40"
identifier="3513d1ca-96d7-477d-8a56-afc320044f40"
type="video" max_parties="9" layout="4" caption="yes" caption_duration="20"
beep = "yes" clamp_dtmf="yes" auto_gain_control="yes" echo_cancellation="yes"/>
</web_service>
HTTP DELETE to remove a conference
http://<server>/default/conferences/3513d1ca-96d7-477d-8a56-afc320044f40?appid=master
204 NO CONTENT
Figure 8. Conferencing Sample Flow
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
40
5. Event Handler
HTTP event streaming is implemented in the PowerMedia XMS RESTful web service as an eventhandler resource.
When the client wishes to receive asynchronous events, it uses the web service to create an
eventhandler and subscribes to specific event types. When the client performs an HTTP GET
on the newly created eventhandler, the web service responds with a 200 OK; however, the
TCP connection remains open until the client destroys the eventhandler. Event data related
to resources and event types subscribed to will be pushed to the client until the eventhandler is deleted by the client.
URL: /eventhandlers?appid=[appid]
HTTP Method GET
Description Get all eventhandlers
Request XML Payload N/A
HTTP Return Code 200 OK if success
404 NOT FOUND
Response XML Payload <web_service version="1.0">
<eventhandlers_response size="2">
<eventhandler_response appid="[appid]"
identifier="[eventhandler_id]"
href="[base_url]/eventhandlers/[eventhandler_id]?appid=[appid]">
<eventsubscribe resource_id="any" resource_type="any"
type="any"/>
</eventhandler_response>
<eventhandler_response appid="[appid]"
identifier="[eventhandler_id]"
href="[base_url]/eventhandlers/[eventhandler_id]?appid=[appid]">
<eventsubscribe resource_id="any" resource_type="any"
type="any"/>
</eventhandler_response>
</eventhandlers_response>
</web_service>
URL: /eventhandlers/[eventhandler_id]?appid=[appid]
HTTP Method GET
Description Get an eventhandler
Request XML Payload N/A
HTTP Return Code 200 OK if success
404 NOT FOUND
Response XML Payload <web_service version="1.0">
<event type="end_play"
resourcet_ype="call"
resource_id="[callid]" >
<event_data transaction_id=[transition_id] />
<event_data reason="complete"/>
<event_data duration="10030ms"/>
</event>
</web_service>
Event Handler
41
URL: /eventhandlers?appid=[appid]
HTTP Method DELETE
Description Not Supported
Request XML Payload N/A
HTTP Return Code N/A
Response XML Payload N/A
URL: /eventhandlers/[eventhandler_id]?appid=[appid]
HTTP Method DELETE
Description Delete an eventhandler
Request XML Payload N/A
HTTP Return Code 204 Deleted if success
404 NOT FOUND
Response XML Payload N/A
URL: /eventhandlers?appid=[appid]
HTTP Method POST
Description Create an eventhandler
Request XML Payload <web_service version="1.0">
<eventhandler>
<eventsubscribe action="add"
type="any" resource_id="any"
resource_type="any"/>
</eventhandler>
</web_service>
HTTP Return Code 201 Created if success
404 NOT FOUND or 500 base Server side error
Response XML Payload <web_service version="1.0">
<eventhandler_response appid="[appid]"
identifier="[eventhandler_id]"
href="[base_url]/eventhandlers/[eventhandler_id]?appid=[appid]">
<eventsubscribe resource_id="any"
resource_type="any" type="any"/>
</eventhandler_response>
</web_service>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
42
URL: /eventhandlers/[eventhandler_id]?appid=[appid]
HTTP Method PUT
Description Update an eventhandler
* Add/Remove subscription
Request XML Payload <web_service version="1.0">
<eventhandler>
<eventsubscribe action="add"
type="end_play" />
<eventsubscribe action="remove"
type="end_playcollect" />
</eventhandler>
</web_service>
HTTP Return Code 200 OK if success
404 NOT FOUND or 500 base Server side error
Response XML Payload <web_service version="1.0">
<eventhandler_response appid="[appid]"
identifier="[eventhandler_id]"
href="[base_url]/eventhandlers/[eventhandler_id]?appid=[appid]">
<eventsubscribe type="end_play"/>
</eventhandler_response>
</web_service>
<eventhandler> Properties
Parameter Description HTTP Method
eventsubscribe Refer to the <eventsubscribe>
properties.
POST/PUT
<eventsubscribe> Properties
Parameter Description
type
Type of events to monitor. Valid values are:
end_play
end_playcollect
end_playrecord
end_overlay
incoming
ringing
connected
hangup
dtmf
cpa
tone
keepalive any (default)
resource_type Monitor events for a specific resource type. Valid values are call, conference, or any. The default value is any.
Event Handler
43
resource_id Monitor events for a specific resource.
action Add/remove the subscription. Valid values are Add or Remove. The default value is Add.
<eventhandler_response> Properties
Parameter Description
identifier A unique ID of an eventhandler resource.
href http: address of an eventhandler resource.
appid Unique application ID included in the original HTTP POST
creation process that is utilized by the web service such that
clients only have access to resources that they created.
eventsubscribe Refer to the <eventsubscribe> properties.
<eventhandlers_response> Properties
Parameter Description
size Number of eventhandlers.
eventhandler_response Refer to the <eventhandler_response> properties.
XML Schema Definition for Eventhandler
Eventsubscribe:
<xs:element name="eventsubscribe">
<xs:complexType>
<xs:attribute name="type" type="event_type" default="any" />
<xs:attribute name="action" type="action_option" default="add" />
<xs:attribute name="resource_id" type="xs:string" default="any" />
<xs:attribute name="resource_type" type="event_resource_type" default="any" />
</xs:complexType>
</xs:element>
Request payload:
<<xs:element name="eventhandler">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventsubscribe" minOccurs="1" maxOccurs="unbounded"
/>
</xs:sequence>
</xs:complexType>
</xs:element>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
44
Single instance response payload:
<xs:element name="eventhandler_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventsubscribe" minOccurs="1" maxOccurs="unbounded"
/>
</xs:sequence>
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:elemen>
Get all instances response payload:
<xs:element name="eventhandlers_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventhandler_response" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
Event Handler
45
Event Handler Example
This diagram of an eventhandler scenario illustrates how to create and monitor events.
application REST Web ServiceHTTP POST
HTTP POST to create new EventHandler
http://<server>/default/eventHandlers?appid=master
<web_service version="1.0">
<eventhandler>
<eventsubscribe action="add" type="any" resource_id="any" resource_type="any"/>
</eventhandler>
</web_service>
201 CREATED
201 CREATED Response
<web_service version="1.0">
<eventhandler_response identifier="a801ffa1-1e4b-4e11-85e6-c5d04c185401" appid="master"
href="http://server/defaultl/eventhandlers/a801ffa1-1e4b-4e11-85e6-c5d04c185401">
<eventsubscribe type="any" resource_id="any" resource_type="any"/>
</eventhandler_response>
</web_service>
HTTP GET
HTTP GET to retireve events
http://<server>/defalut/eventhandlers/a801ffa1-1e4b-4e11-85e6-c5d04c185401?appid=master
200 OK
200 OK Response
No Body (TCP Connection remains open)
Event Data
Event Data
<web_service version="1.0">
<event type="dtmf" resourceid="7bfc5cc2-45c3-4ab9-bb41-67af4e43972c" resourcetype="call">
<data name="digits" value="1" />
</event>
</web_service>
<web_service version="1.0">
<event type="end_play" resourceid="5974c8b5-8a3c-4a8e-ae82-8f7c8bd0efd5" resourcetype="player">
<data name="reason" value="EOF" />
<data name="duration" vaule="30s" />
<data name="transaction_id" value="0974c8b5-8a3c-4a8e-ae82-8f7c8bd0efdd" />
</event>
</web_service>
Figure 9. eventhandler Scenario
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
46
6. Events
This chapter describes the event data that is associated with the event types.
<event_data> Properties
Parameter Description
name
The name of an event data. Valid values are:
reason
tone
digits
duration
caller_uri
uri
content_type
content transaction_id
value The value of an event data.
<event> Properties
Parameter Description
type
The event type. Valid values are:
end_play
end_playcollect
end_playrecord
end_overlay
dtmf
tone
info
incoming
ringing
connected
hangup keepalive
resource_type A resource type. Valid values are call or conference.
resource_id A unique ID.
Events
47
Event Types
Event Description Event Payload
end_play transaction_id Reason:
Play complete
Play stopped
Duration in milliseconds
<web_service version="1.0">
<event type="end_play"
resourceid="5974c8b5-8a3c-4a8e-ae82-
8f7c8bd0efd5" resource_type="call">
<event_data name="reason" value="complete" />
<event_data name="duration" vaule="30000ms" />
<event_data name="transaction_id"
value="0974c8b5-8a3c-4a8e-ae82-
8f7c8bd0efdd" />
</event>
</web_service>
end_playcollect transaction_id
Reason:
maxdigits
termdigit -timeout -tone -stopped
digits
tone
Duration in milliseconds
<web_service version="1.0">
<event type="end_playcollect"
resourceid="5974c8b5-8a3c-4a8e-ae82-
8f7c8bd0efd5" resource_type="call">
<event_data name="reason" value=" termdigit " />
<event_data name="digits" vaule="1234" />
<event_data name="transaction_id" value="0974c8b5-
8a3c-4a8e-ae82-8f7c8bd0efdd" />
</event>
</web_service>
end_playrecord transaction_id
Reason:
stopped
Duration in milliseconds
<web_service version="1.0">
<event type="end_playrecord"
resource_id="5974c8b5-8a3c-4a8e-ae82-
8f7c8bd0efd5" resource_type="call">
<event_data name="reason" value=" timeout " />
<event_data name="transaction_id" value="0974c8b5-
8a3c-4a8e-ae82-8f7c8bd0efdd" />
</event>
</web_service>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
48
end_overlay
transaction_id
Reason:
termdigit
timeout
stopped
Duration in milliseconds
<web_service version="1.0">
<event type="end_overlay" resource_id="5974c8b5-
8a3c-4a8e-ae82-8f7c8bd0efd5"
resource_type="call">
<event_data name="reason" value=" stop " />
<event_data name="transaction_id" value="0974c8b5-
8a3c-4a8e-ae82-8f7c8bd0efdd" />
</event>
</web_service>
incoming call_id, uri, caller_uri
<web_service version="1.0">
<event type="incoming" resource_id="5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" resource_type="call">
<event_data name="call_id" value=" 5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" />
<event_data name="uri" value="sip:
<event_data name="caller_uri"
value="sip:[email protected]" />
</event>
</web_service>
ringing The remote party of
an outbound call is ringing.
call_id
<web_service version="1.0">
<event type="ringing" resource_id="5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" resource_type="call">
<event_data name="call_id" value=" 5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" />
</event>
</web_service>
connected The remote party of an outbound call has answered.
call_id
Reason:
unknown
answer-machine
voice
fax
custom tone name
Media
audio
audiovideo
<web_service version="1.0">
<event type="connected" resource_id="5974c8b5-
8a3c-4a8e-ae82-8f7c8bd0efd5"
resource_type="call">
<event_data name="reason" value="voice" />
<event_data name="media" value="audio" />
</event>
</web_service>
Events
49
hangup The remote party has ended the call.
call_id
Reason:
busy-tone
operator-intercept voice
no-answer
<web_service version="1.0">
<event type="hangup" resource_id="5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" resource_type="call">
<event_data name="reason" value=”no-answer" />
</event>
</web_service>
info Unsolicited user information (e.g., SIP INFO).
call_id
content-type
content
<web_service version="1.0">
<event type="info" resource_id="5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" resource_type="call">
<event_data name="call_id" value=" 5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" />
<event_data name=”content-type” value=”sdp” />
<event_data name=”content” value=”[sdp]” />
</event>
</web_service>
dtmf Unsolicited DTMF digits.
call_id
digitscall_id
<web_service version="1.0">
<event type="info" resource_id="5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" resource_type="call">
<event_data name="call_id" value=" 5974c8b5-
8a3c-4a8e-ae82-8f7c8bd0efd5" />
<event_data name=”digits” value=”4” />
</event>
</web_service>
tone Unsolicited tone detection events.
call_id
tone
<web_service version="1.0">
<event type="tone" resource_id="5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" resource_type="call">
<event_data name="call_id" value=" 5974c8b5-8a3c-
4a8e-ae82-8f7c8bd0efd5" />
<event_data name=”tone” value=”[name]” />
</event>
</web_service>
keepalive Once the application
starts to monitor the events, the PowerMedia XMS RESTful web service will send a “keepalive” event periodically.
<web_service version="1.0">
<event type="keepalive" />
</web_service>
XML Schema Definition for Events <xs:simpleType name="event_type">
<xs:restriction base="xs:string">
<xs:enumeration value="end_play" />
<xs:enumeration value="end_playcollect" />
<xs:enumeration value="end_playrecord" />
<xs:enumeration value="end_overlay" />
<xs:enumeration value="keepalive" />
<xs:enumeration value="incoming" />
<xs:enumeration value="ringing" />
<xs:enumeration value="connected" />
<xs:enumeration value="hangup" />
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
50
<xs:enumeration value="info" />
<xs:enumeration value="dtmf" />
<xs:enumeration value="tone" />
<xs:enumeration value="any" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="event_data_name">
<xs:restriction base="xs:string">
<xs:enumeration value="result" />
<xs:enumeration value="reason" />
<xs:enumeration value="digits" />
<xs:enumeration value="tone" />
<xs:enumeration value="duration" />
<xs:enumeration value="uri" />
<xs:enumeration value="caller_uri" />
<xs:enumeration value="content_type" />
<xs:enumeration value="content" />
<xs:enumeration value="transaction_id" />
</xs:restriction>
</xs:simpleType>
<xs:element name="event_data">
<xs:complexType>
<xs:attribute name="name" type="event_data_name" use="required" />
<xs:attribute name="value" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:simpleType name="event_resource_type">
<xs:restriction base="xs:string">
<xs:enumeration value="call" />
<xs:enumeration value="conference" />
<xs:enumeration value="any" />
</xs:restriction>
</xs:simpleType>
<xs:element name="event">
<xs:complexType>
<xs:sequence>
<xs:element ref="event_data" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="type" type="event_type" use="required" />
<xs:attribute name="resource_type" type="event_resource_type" />
<xs:attribute name="resource_id" type="xs:string" />
</xs:complexType>
</xs:element>
Appendix A
51
7. Appendix A
This Appendix contains the complete XML Schema Definition of elements used for PowerMedia XMS RESTful web server.
NOTE: This Schema Definition may occasionally be updated. Always use the definition
available on the PowerMedia XMS ISO version used.
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:simpleType name="boolean_type">
<xs:restriction base="xs:string">
<xs:enumeration value="yes" />
<xs:enumeration value="no" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="action_option">
<xs:restriction base="xs:string">
<xs:enumeration value="add" />
<xs:enumeration value="remove" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="call_type_option">
<xs:restriction base="xs:string">
<xs:enumeration value="inbound" />
<xs:enumeration value="outbound" />
<xs:enumeration value="3pcc" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="media_type">
<xs:restriction base="xs:string">
<xs:enumeration value="audio" />
<xs:enumeration value="audiovideo" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="media_direction">
<xs:restriction base="xs:string">
<xs:enumeration value="inactive" />
<xs:enumeration value="sendonly" />
<xs:enumeration value="recvonly" />
<xs:enumeration value="sendrecv" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="time_value">
<xs:restriction base="xs:string">
<xs:pattern value="(\+)?([0-9]*\.)?[0-9]+(ms|s)|infinite"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="digit_value">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9#*]+|”>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="volume_range">
<xs:restriction base="xs:string">
<xs:pattern value="((\+|)([0-9]|1[0-9]|2[0-9]|3[0-1])|(\-)([0-9]|1[0-
9]|2[0-9]|3[0-2]))(dB|db|DB|Db)"/>
</xs:restriction>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
52
</xs:simpleType>
<xs:simpleType name="integer_value">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]+|infinite"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="dtmf_mode_option">
<xs:restriction base="xs:string">
<xs:enumeration value="inband" />
<xs:enumeration value="outofband" />
<xs:enumeration value="rfc2833" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="event_type">
<xs:restriction base="xs:string">
<xs:enumeration value="end_play" />
<xs:enumeration value="end_playcollect" />
<xs:enumeration value="end_playrecord" />
<xs:enumeration value="end_overlay" />
<xs:enumeration value="keepalive" />
<xs:enumeration value="incoming" />
<xs:enumeration value="ringing" />
<xs:enumeration value="connected" />
<xs:enumeration value="hangup" />
<xs:enumeration value="info" />
<xs:enumeration value="dtmf" />
<xs:enumeration value="tone" />
<xs:enumeration value="any" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="event_data_name">
<xs:restriction base="xs:string">
<xs:enumeration value="tone" />
<xs:enumeration value="digits" />
<xs:enumeration value="info" />
<xs:enumeration value="reason" />
<xs:enumeration value="duration" />
<xs:enumeration value="uri" />
<xs:enumeration value="caller_uri" />
<xs:enumeration value="content_type" />
<xs:enumeration value="content" />
<xs:enumeration value="transaction_id" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="event_resource_type">
<xs:restriction base="xs:string">
<xs:enumeration value="call" />
<xs:enumeration value="conference" />
<xs:enumeration value="any" />
</xs:restriction>
</xs:simpleType>
<xs:element name="dvr_setting">
<xs:complexType>
<xs:attribute name="forward_key" type="digit_value" default="1" />
<xs:attribute name="backward_key" type="digit_value" default="2" />
<xs:attribute name="pause_key" type="digit_value" default="3" />
<xs:attribute name="resume_key" type="digit_value" default="4" />
<xs:attribute name="restart_key" type="digit_value" default="5" />
</xs:complexType>
</xs:element>
<xs:simpleType name="dvr_action_option">
<xs:restriction base="xs:string">
<xs:enumeration value="forward" />
<xs:enumeration value="backward" />
Appendix A
53
<xs:enumeration value="pause" />
<xs:enumeration value="resume" />
<xs:enumeration value="restart" />
</xs:restriction>
</xs:simpleType>
<xs:element name="conf_participant">
<xs:complexType>
<xs:attribute name="call_id" type="xs:string" />
<xs:attribute name="audio" type="media_direction" />
<xs:attribute name="video" type="media_direction" />
<xs:attribute name="caption" type="xs:string" />
<xs:attribute name="region" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="add_party">
<xs:complexType>
<xs:attribute name="conf_id" type="xs:string" use="required" />
<xs:attribute name="audio" type="media_direction"
default="recvonly" />
<xs:attribute name="video" type="media_direction"
default="recvonly" />
<xs:attribute name="caption" type="xs:string" />
<xs:attribute name="region" type="xs:string" default="0"/>
</xs:complexType>
</xs:element>
<xs:element name="update_party">
<xs:complexType>
<xs:attribute name="conf_id" type="xs:string" />
<xs:attribute name="audio" type="media_direction" />
<xs:attribute name="video" type="media_direction" />
<xs:attribute name="caption" type="xs:string" />
<xs:attribute name="region" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="remove_party">
<xs:complexType>
<xs:attribute name="conf_id" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="join">
<xs:complexType>
<xs:attribute name="call_id" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="unjoin">
<xs:complexType>
<xs:attribute name="call_id" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="call_action">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element ref="play" />
<xs:element ref="update_play" />
<xs:element ref="playcollect" />
<xs:element ref="playrecord" />
<xs:element ref="overlay" />
<xs:element ref="stop" />
<xs:element ref="join" />
<xs:element ref="unjoin" />
<xs:element ref="add_party" />
<xs:element ref="update_party" />
<xs:element ref="remove_party" />
</xs:choice>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
54
</xs:complexType>
</xs:element>
<xs:element name="conf_action">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element ref="play" />
<xs:element ref="update_play" />
<xs:element ref="stop" />
</xs:choice>
</xs:complexType>
</xs:element>
<xs:attributeGroup name="response_attrgroup">
<xs:attribute name="href" type="xs:string" use="required" />
<xs:attribute name="identifier" type="xs:string" use="required" />
<xs:attribute name="appid" type="xs:string" use="required" />
</xs:attributeGroup>
<xs:element name="overlay">
<xs:complexType>
<xs:attribute name="uri" type="xs:string" use="required"/>
<xs:attribute name="duration" type="time_value" default="infinite" />
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="event_data">
<xs:complexType>
<xs:attribute name="name" type="event_data_name" use="required" />
<xs:attribute name="value" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="event">
<xs:complexType>
<xs:sequence>
<xs:element ref="event_data" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="type" type="event_type" use="required" />
<xs:attribute name="resource_type" type="xs:string" />
<xs:attribute name="resource_id" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="stop">
<xs:complexType>
<xs:attribute name="transaction_id" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="play_source">
<xs:complexType>
<xs:attribute name="location" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="play">
<xs:complexType>
<xs:sequence>
<xs:element ref="play_source" minOccurs="1" maxOccurs="1" />
<xs:element ref="dvr_setting" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="offset" type="time_value" default="0s" />
<xs:attribute name="repeat" type="integer_value" default="0" />
<xs:attribute name="delay" type="time_value" default="1s" />
<xs:attribute name="skip_interval" type="time_value" default="1s" />
<xs:attribute name="max_time" type="time_value" default="infinite" />
<xs:attribute name="terminate_digits" type="digit_value" default="#"/>
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
Appendix A
55
</xs:element>
<xs:element name="update_play">
<xs:complexType>
<xs:attribute name="dvr_action" type="dvr_action_option" use="required"/>
<xs:attribute name="transaction_id" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="playrecord">
<xs:complexType>
<xs:sequence>
<xs:element ref="play_source" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="barge" type="boolean_type" default="yes" />
<xs:attribute name="cleardigits" type="boolean_type" default="no" />
<xs:attribute name="offset" type="time_value" default="0s" />
<xs:attribute name="repeat" type="integer_value" default="0" />
<xs:attribute name="delay" type="time_value" default="1s" />
<xs:attribute name="recording_uri" type="xs:string" use="required" />
<xs:attribute name="beep" type="boolean_type" default="yes" />
<xs:attribute name="terminate_digits" type="digit_value" default="#"/>
<xs:attribute name="max_time" type="time_value" default="infinite" />
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="playcollect">
<xs:complexType>
<xs:sequence>
<xs:element ref="play_source" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="barge" type="boolean_type" default="yes" />
<xs:attribute name="cleardigits" type="boolean_type" default="no" />
<xs:attribute name="offset" type="time_value" default="0s" />
<xs:attribute name="repeat" type="integer_value" default="0" />
<xs:attribute name="delay" type="time_value" default="1s" />
<xs:attribute name="max_digits" type="xs:string" />
<xs:attribute name="terminate_digits" type="digit_value" default="#"/>
<xs:attribute name="timeout" type="time_value" />
<xs:attribute name="tone_detection" type="boolean_type" default="no" />
<xs:attribute name="transaction_id" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:element name="error">
<xs:complexType>
<xs:attribute name="code" type="xs:string" use="required" />
<xs:attribute name="description" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="call">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_action" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="answer" type="boolean_type"/>
<xs:attribute name="signaling" type="boolean_type" default="yes" />
<xs:attribute name="media" type="media_type" default= "audio"/>
<xs:attribute name="source_uri" type="xs:string" />
<xs:attribute name="destination_uri" type="xs:string" />
<xs:attribute name="sdp" type="xs:string"/>
<xs:attribute name="cpa" type="boolean_type" default="no"/>
<xs:attribute name="dtmf_mode" type="dtmf_mode_option" default="rfc2833"/>
<xs:attribute name="async_dtmf" type="boolean_type" />
<xs:attribute name="async_tone" type="boolean_type" />
<xs:attribute name="rx_delta" type="volume_range" />
<xs:attribute name="tx_delta" type="volume_range" />
<xs:attribute name="cleardigits" type="boolean_type" />
</xs:complexType>
Dialogic® PowerMedia™ XMS RESTful API Developer’s Guide
56
</xs:element>
<xs:element name="call_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_action" minOccurs="0" />
</xs:sequence>
<xs:attribute name="signaling" type="boolean_type" />
<xs:attribute name="media" type="media_type" />
<xs:attribute name="destination_uri" type="xs:string" />
<xs:attribute name="source_uri" type="xs:string" />
<xs:attribute name="call_type" type="call_type_option" />
<xs:attribute name="connected" type="boolean_type" />
<xs:attribute name="sdp" type="xs:string"/>
<xs:attribute name="cpa" type="boolean_type" />
<xs:attribute name="dtmf_mode" type="dtmf_mode_option" />
<xs:attribute name="async_dtmf" type="boolean_type"/>
<xs:attribute name="async_tone" type="boolean_type" />
<xs:attribute name="rx_delta" type="volume_range" />
<xs:attribute name="tx_delta" type="volume_range" />
<xs:attribute name="cleardigits" type="boolean_type" />
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
<xs:element name="calls_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_response" minOccurs="0" />
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="eventhandler">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventsubscribe" minOccurs="1"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="eventhandler_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventsubscribe" minOccurs="1"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
<xs:element name="eventhandlers_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventhandler_response" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="eventsubscribe">
<xs:complexType>
<xs:attribute name="type" type="event_type" default="any" />
<xs:attribute name="action" type="action_option" default="add" />
<xs:attribute name="resource_id" type="xs:string" default="any" />
<xs:attribute name="resource_type" type="event_resource_type"
default="any" />
</xs:complexType>
Appendix A
57
</xs:element>
<xs:element name="conference">
<xs:complexType>
<xs:sequence>
xs:element ref="conf_action" minOccurs="0" maxOccurs="1" />
</xs:sequence>
<xs:attribute name="type" type="media_type" default="audio" />
<xs:attribute name="max_parties" type="xs:string" default="9" />
<xs:attribute name="reserve" type="xs:string" default="0" />
<xs:attribute name="layout" type="xs:string" />
<xs:attribute name="caption" type="boolean_type" default="yes" />
<xs:attribute name="caption_duration" type="time_value" default="20s" />
<xs:attribute name="beep" type="boolean_type" default="yes" />
<xs:attribute name="clamp_dtmf" type="boolean_type" default="yes" />
<xs:attribute name="auto_gain_control" type="boolean_type" default="yes" />
<xs:attribute name="echo_cancellation" type="boolean_type" default="yes" />
</xs:complexType>
</xs:element>
<xs:element name="conference_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="conf_action" minOccurs="0" maxOccurs="1" />
<xs:element ref="conf_participant" minOccurs="0" />
</xs:sequence>
<xs:attribute name="type" type="media_type" />
<xs:attribute name="max_parties" type="xs:string" />
<xs:attribute name="reserve" type="xs:string" />
<xs:attribute name="layout" type="xs:string" />
<xs:attribute name="caption_duration" type="time_value" />
<xs:attribute name="beep" type="xs:string" default="yes" />
<xs:attribute name="clamp_dtmf" type="boolean_type"/>
<xs:attribute name="auto_gain_control" type="boolean_type"/>
<xs:attribute name="echo_cancellation" type="boolean_type"/>
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
<xs:element name="conferences_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="conference_response" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="web_service">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element ref="call" />
<xs:element ref="call_response" />
<xs:element ref="calls_response" />
<xs:element ref="conference" />
<xs:element ref="conference_response" />
<xs:element ref="conferences_response" />
<xs:element ref="eventhandler" />
<xs:element ref="eventhandler_response" />
<xs:element ref="eventhandlers_response" />
<xs:element ref="event" />
<xs:element ref="error" />
</xs:choice>
xs:attribute name="version" type="xs:NMTOKEN" fixed="1.0" use="required" />
</xs:complexType>
</xs:element>
</xs:schema>