of 57 /57
Dialogic ® PowerMedia™ Extended Media Server (XMS) RESTful API Developer’s Guide February 2012 05-2703-001 www.dialogic.com

Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

  • Upload
    others

  • View
    22

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

Dialogic® PowerMedia™ Extended Media Server (XMS) RESTful API

Developer’s Guide

February 2012 05-2703-001

www.dialogic.com

Page 2: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 3: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 4: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 5: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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:

Page 6: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 7: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 8: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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:

Page 9: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 10: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 11: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 12: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 13: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 14: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 15: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 16: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 17: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 18: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 19: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 20: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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 >

Page 21: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 22: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 23: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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="#"/>

Page 24: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 25: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 26: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 27: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 28: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 29: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 30: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 31: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 32: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 33: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 34: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 35: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 36: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 37: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 38: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 39: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 40: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 41: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 42: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 43: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 44: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 45: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 46: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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.

Page 47: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 48: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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:

[email protected]" />

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

Page 49: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 50: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 51: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 52: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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

Page 53: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 54: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 55: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 56: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>

Page 57: Dialogic® PowerMedia™ XMS RESTful API/media/manuals/xms/XMS_RESTfulAPIDe… · RESTful API Description PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful)

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>