Dialogic PowerMedia XMS RESTful API Developer's Guide

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

January 2013

05-2703-003 www.dialogic.com

Copyright and Legal Notice Copyright © 2012-2013 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 6700 de la Cote-de-Liesse Road, Suite 100, Borough of Saint-Laurent, Montreal, Quebec, Canada H4T 2B5. 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, BorderNet, PowerMedia, ControlSwitch, I-Gate, Mobile Experience Matters, Network Fuel, Video is the New Voice, Making Innovation Thrive, Diastar, Cantata, TruFax, SwitchKit, Eiconcard, NMS Communications, SIPcontrol, Exnet, EXS, Vision, inCloud9, NaturalAccess 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 6700 de la Cote-de-Liesse Road, Suite 100, Borough of Saint-Laurent, Montreal, Quebec, Canada H4T 2B5. 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 respon sible 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.

Table of Contents 1.

Welcome ....................................................................................................... 6

2. Overview....................................................................................................... 7 RESTful API Description............................................................................................ 8 Client Side Technologies ........................................................................................ 8 RESTful API with HTTP Methods................................................................................. 9 RESTful API Request/Response Model ..................................................................... 9 XML Schema Definition ........................................................................................ 10 Event Streaming................................................................................................. 11 3.

Resource-Based Element Introduction ........................................................ 13 Applications and Application IDs (appid) ................................................................ 13

4. Call Resource .............................................................................................. 14 XML Schema Definitions for Call .............................................................................. 17 Element Attributes ...................................................................................... 22 Element Attribute Notes ............................................................................ 23 Parameters................................................................................ 24 Parameters .................................................................................... 26 Call Action Scenarios ............................................................................................. 32 5. Conference Resource .................................................................................. 38 XML Schema Definition for Conference ..................................................................... 41 Element Attributes ............................................................................ 42 Parameters ..................................................................... 44 Parameters .................................................................................. 45 Conference Actions Scenarios ................................................................................. 48 6. Event Handler ............................................................................................. 50 XML Schema Definition for Event Handler ................................................................. 52 Element Attribute .......................................................................... 53 Parameters.............................................................................. 53 Parameters .................................................................. 54 Event Handler Scenario .......................................................................................... 55 7. Events ......................................................................................................... 56 XML Schema Definition for Events ........................................................................... 56 Parameters ........................................................................................... 57 Parameters ................................................................................... 57 Event Types ....................................................................................................... 58 8.

XML Schema Definition of Elements ............................................................ 62

9. Dynamic Text and Image Generation .......................................................... 71 Document Templates ............................................................................................. 71 Style Definition ..................................................................................................... 72 Creating the Image using the RESTful API ................................................................ 74 Combining the Three Data Sources .......................................................................... 74 10.

XMSTool RESTful Utility............................................................................... 76

3

Revision History Revision

Release Date

Notes

05-2703003

January 2013

Updates to support PowerMedia XMS Release 2.0. Call Resource: 

Updated http post/put request payload, single call instance response payload, call_action, add_party, and update_party in XML Schema Definitions for Call.



Added new clamp_dtmf, auto_gain_control, echo_cancellation, digits, interval, level, content_type, and content to the Parameters table.



Added new send_dtmf, send_info, send_info_ack, transfer, redirect, and hangup to the Parameters table.



Added new display_name, accept, early_media, and info_ack_mode to the Element Attributes table.



Added new section for Element Attribute Notes.

Conference Resource: 

Added new playrecord conference action in XML Schema Definition for Conference.



Added new barge, cleardigits, beep, and recording_uri to the Parameters table.

XML Schema Definition of Elements: 

Added updated schema definition.

4

Revision History

Revision

Release Date

Notes

05-2703002

July 2012

Updated to support PowerMedia XMS Release 1.1. This includes adding additional information to all sections and reorganizing the layout of the Resource sections. Global change: 

Renamed PowerMedia XMS RESTful web service to PowerMedia XMS RESTful server.

Call Resource: 

Added new interdigit_timeout parameter to the Parameters table.

Conference Resource: 

Added new region parameter to the Parameters table.

XML Schema Definition of Elements: 

Added updated schema definition.

Dynamic Text and Image Generation: 

Added new section.

XMSTool RESTful Utility:  05-2703001

February 2012

Added new section.

Initial release of this document.

Last modified: January 2013 Refer to www.dialogic.com for product updates and for information about support policies, warranty information, and service offerings.

5

1.

Welcome

This Developer's Guide provides information about the Dialogic® PowerMedia™ Extended Media Server (also referred to herein as "PowerMedia XMS" or "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 PowerMedia XMS.

6

2.

Overview

This section provides information about the 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 PowerMedia XMS. The architectural diagram below shows how the RESTful interface fits into PowerMedia XMS.

Two web servers are used in PowerMedia XMS: 

Apache server Controls a web-based interface for operations, administration and maintenance.



lighttpd 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 PowerMedia XMS processes.

The PowerMedia XMS translates RESTful commands into the PowerMedia HMP media engine's low-level API. The media engine itself handles SIP calls, plays/records multimedia, and mixes multimedia conferences.

7

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide PowerMedia XMS provides two call control models: 

First party call control (1PCC) The application sends 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.



Third party call control (3PCC) The application handles SIP calls and SDP negotiation, and the PowerMedia XMS only performs media processing operations.

RESTful API Description The PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful) web service. This web service is a software system designed to support interoperable machineto-machine interactions over a network, using the HTTP protocol. The RESTful API consists of a series of requests and responses built around the transfer of representations of "resources". These resources are accessed through Universal Resource Indicators (URIs). RESTful client-server architecture is where clients initiate requests to servers and servers process the requests and return appropriate responses.

Client Side Technologies The "client side" refers to the client that communicates with the PowerMedia XMS and directs the session with the caller. Essentially, any language or operating system may be used to build a client. The main requirement is that the client supports HTTP and XML. Listed below are client-side development platforms. Comments are included on multithreading, which is important for the event handler. Java – This object-oriented, operating system-independent programming environment is fully multithreaded. Several XSD/XML parsers are available, as well as HTTP client class libraries. Note: The Dialogic Verification Demo used with the PowerMedia XMS is a Java application. Refer to the Dialogic® PowerMedia™ XMS Quick Start Guide for information about the Demo. Python – This operating system-independent interpreted scripting language has POSIX threading available. HTTP protocol client library and Python XML/Schema processing tool are also available. .NET – This Integral Microsoft Windows component supports the building and running of applications and XML web services. HTTP module and XSD schema definition tools are available. Ruby – This open source scripting language contains a multiprocessing model that may be needed for the event handler. An HTTP client API and XSD validation tools are available. C/C++ – These general purpose programming languages are fully multithreaded. cURL library (http://curl.haxx.se) is used for HTTP processing and Xerces C++ XML parser (http://xerces.apache.org/xerces-c) is used for XML.

8

Overview

RESTful API with HTTP Methods In the RESTful API, the four HTTP methods are translated to the actions shown in the following table. HTTP Method

Request

Response

POST

Create a new resource

Contents of a newly created resource

PUT

Modify an existing resource

Contents of an updated resource

GET

Retrieve information for all instances of a specific resource type, or information regarding a specific resource

Contents of resource information

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 PowerMedia XMS. 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. If a client wished to retrieve a list of all call resources currently active on the PowerMedia XMS, it would issue an HTTP GET request. The HTTP GET request would be sent on the web service with the IP address of . For example: http:///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:

The above sample shows a client requesting information for all calls with a response of two active identifiers along with the attributes of each call resource.

9

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide 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. http:///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:

Additional request/response examples are contained within Resource-Based Components.

XML Schema Definition PowerMedia XMS uses an XML schema definition (also referred to herein as "XSD"). The XSD formally describes the structure, content, and semantics of the XML payload for the PowerMedia XMS RESTful API call and media commands. An XSD may be used to generate client-side code, allowing contents of XML documents to be treated as objects. The generated code usually enforces type-checking, thus supporting client-side validation of the XML payload before it is sent to the PowerMedia XMS. Definitions of individual elements are referenced throughout this guide. The full XSD is provided in XML Schema Definition of Elements. PowerMedia XMS RESTful API is designed using the following XML Schema declarations: Element An element describes the data it contains. It consists of a name and data type. When an element definition contains additional elements or attributes, it is a complex type.

Attribute An attribute is a simple type definition that cannot contain other elements. Attribute names are always within quotation marks.

Sequence Specifies the order in which attributes or elements within a complex type must be listed.

10

Overview Complex Type Defines an element containing other elements and attributes or mixed content (elements and text).

Simple Type Creates a constrained data type for an element or attribute value.

Refer to the specific resource-based element sections for more information.

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. 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. For PowerMedia XMS, HTTP event streaming is implemented in the 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 API 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:

11

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

12

3.

Resource-Based Element Introduction

There are three resource-based elements used by the PowerMedia XMS RESTful web service. 

Call



Conference



Event Handler

These elements are used in conjunction with one another to direct the PowerMedia XMS to make and receive calls, handle media during a call, manipulate audio and video conferences, and to catch events relating to calls, conferences and their media. Each element makes use of the various HTTP methods – POST, PUT, DELETE and GET. The resource-based element chapters in this document contain HTTP method tables that 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. The tables also contain a sample payload for that specific resource-based element type. This XML content is used in both HTTP requests and responses. Refer to the specific resource-based element sections for information about each of the three elements.

Applications and Application IDs (appid) The appid shown in the URL request examples is for identifying the resources used, owned and created by a specific application. For example:

Discrete appids are defined so that multiple applications may be simultaneously run on a single PowerMedia XMS. The appid 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 an application with a matching appid. The appid is used throughout the PowerMedia XMS RESTful API to identify the intended application. Note: The appid is pre-defined on the Routing page of the PowerMedia XMS Admin Console (also referred to herein as "Console"), which is used for post-operating system installation and configuration tasks. New appids may be added, or unwanted appids removed on the Routing page. Refer to the Dialogic® PowerMedia™ XMS Installation and Configuration Guide for detailed information about the Console.

13

4.

Call Resource

The Call Resource creates and manages the media/signal connection between the remote media endpoint (typically a SIP phone) and the PowerMedia XMS. The Call Resource has the following types: 

Inbound This call resource is created by the PowerMedia XMS RESTful server when an incoming call is received. The application is then informed of the inbound call via the eventhandler resource.



Outbound This call resource is created by an application that wishes to make a media stream connection from the PowerMedia XMS RESTful server to a SIP endpoint.



3PCC This call resource is requested by the application without requesting the PowerMedia XMS RESTful server to provide signaling control. The call resource will be created based on the Session Description Protocol (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, and stop. Conference-related actions include add_party, update_party and remove_party. The following tables show the HTTP methods that can be used with one or more calls. Note: The payloads shown are examples only as there are many possible variations.

POST URL: /calls?appid=[appid] Action

Create an outbound call. Note: When creating a 3PCC call without SIP call control, the SDP must be specified.

Request XML Payload Example



HTTP Return Code

Success: 201 CREATED Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR or 400 BAD REQUEST

14

Call Resource

Response XML Payload Example



PUT URL: /calls_id?appid=[appid] Action

Update a call. 

Call-related – answer an inbound SIP call, or join or unjoin two calls



Conference-related – add_party, update_party or remove_party



Media-related – play, update_play, playrecord, playcollect, overlay or stop

Request XML Payload Example



HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR

Response XML Payload Example



15

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

DELETE The DELETE method has two options – one deletes all calls and the other deletes one call specified by the [call_id]. URL: /calls?appid=[appid] Action

Delete all calls.

Request XML Payload Example

N/A

HTTP Return Code

N/A

Response XML Payload Example

N/A

URL: /calls/[call_id]?appid=[appid] Action

Delete a call by call ID.

Request XML Payload Example

N/A

HTTP Return Code

Success: 204 NO CONTENT Error: 404 NOT FOUND

Response XML Payload Example

N/A

GET The GET method has two options – one to get all calls and the other to get one call specified by the [call_id]. URL: /calls?appid=[appid] Action

Get all calls.

Request XML Payload Example

N/A

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND

16

Call Resource

Response XML Payload Example



URL: /calls/[call_id]?appid=[appid] Action

Get a single call by call ID.

Request XML Payload Example

N/A

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND

Response XML Payload Example



XML Schema Definitions for Call The following XML schema definitions provide a formal definition of all possible XML payloads that are valid with the Call element.

17

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide http post/put request payload

single call instance response payload

get all instances response payload

18

Call Resource call_action

play

update_play

playrecord

19

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide playcollect

overlay

stop

add_party

update_party

remove_party

20

Call Resource join

unjoin

send_dtmf

send_info

send_info_ack

transfer

redirect

hangup

21

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Element Attributes The following table lists all valid parameters, their definitions and their valid and default values that can be used in an XML payload as part of a call. The HTTP method(s) in which they can be used is also provided. Parameter

Description

Values

HTTP Method

signaling

Specifies if signaling is done by PowerMedia XMS or a third party application server.

yes - for PowerMedia XMS (default)

POST

no - for a third party application server sdp

Specifies the Session Description Protocol data. This attribute is set by the client when it builds the XML payload and used only for 3PCC.

Valid SDP

POST/PUT

media

Sets the media type supported by the call.

audio (default)

POST/PUT

audiovideo

Note: For an update call scenario, this attribute will only take effect when answering an inbound call. dtmf_mode

Specifies the signaling mode for DTMF digits.

inband

Note: For an update call scenario, this attribute will only take effect when answering an inbound call.

rfc2833 (default)

Specifies if DTMF digits are reported as events outside of a action.

yes

rx_delta

Used for volume adjustments.

Between +31dB and -32dB

POST/PUT

tx_delta

Used for volume adjustments.

Between +31dB and -32dB

POST/PUT

async_tone

Specifies if tones are reported as events outside of a action.

yes

POST/PUT

async_dtmf

POST/PUT

outofband

POST/PUT

no

no

22

Call Resource

Parameter

Description

Values

HTTP Method

cleardigits

Specifies whether previous buffered digit input should be discarded.

yes

POST/PUT

no

Note: This attribute is considered only when async_dtmf is set to Yes. destination_uri

Specifies the SIP destination (Called) address when creating an outbound SIP call.

N/A

POST

source_uri

Specifies the SIP source (Caller) address when creating an outbound SIP call.

N/A

POST

cpa

Specifies if call progress detection is used for an outbound call.

yes

POST

call_action

Refer to the attributes.

N/A

PUT

display_name

Specifies the display name when creating an outbound call.

N/A

POST

accept

Accepts an incoming call.

N/A

PUT

early_media

Enables early media when accepting an incoming call.

yes

PUT

Specifies how INFO events are acknowledged.

automatic (default)

info_ack_mode

no (default)

no (default) POST/PUT

manual

Element Attribute Notes The following notes contain details that will help in understanding how the various attributes are used.

Asynchronous Tones Audio tones can be used to both terminate operations and can also be delivered to the application as asynchronous events. To terminate a playrecord or play operation, set terminate_digits to the desired DTMF digit value (0-9, * and #). If the operation is terminated this way, the end_playrecord or endplay event will reference the digit collected to end the operation. To have an async DTMF event delivered to your application outside of its use as a play/record termination, async_dtmf=yes should be set for a call resource.

23

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide User-defined tone detection is set up using tone templates, which are created in the PowerMedia XMS GUI in the Tones screen (see the Dialogic® PowerMedia™ XMS Installation and Configuration Guide for more information). Set async_tones=yes for a call resource and detection of the defined tones is activated. DTMF events are delivered as event type "dtmf", with a name of "digits" and a value corresponding to the digit collected. Async tone events are delivered as event type "tone", with a name of "tone" and a value corresponding to the name assigned when the user-defined tone was created.

Playcollect and User-Defined Tones A playcollect operation usually is used to collect DTMF tones but may collect user-defined tone as well. To do this, the attribute tone_detection=yes must be set when the playcollect is initiated. The end_playcollect event will reference the user-defined name of the tone collected and the reason parameter will be set to tone. Duration (in milliseconds) refers to the length of the play operation, not the duration of the tone.

Parameters The following table lists all valid parameters and their definitions that may be returned in an XML payload as part of a call_response. Parameter

Description

Values

identifier

A unique ID of a call resource.

N/A

href

The http: address of a call resource.

N/A

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.

N/A

call_type

Indicates the type of call.

inbound outbound 3pcc

signaling

Specifies if signaling is done by PowerMedia XMS or a third-party application server.

yes - for PowerMedia XMS (default) no - for a third party application server

24

Call Resource

Parameter

Description

Values

sdp

Returns the Session Description Protocol data. In this case, a valid SDP must be supplied by the application.

SDP created by PowerMedia XMS for 1PCC SDP that the client sent as part of 3PCC

media

Specifies the media type supported by the call.

audio audiovideo

destination_uri

Specifies the SIP destination address for only an outbound SIP call.

N/A

source_uri

Specifies the Caller address.

N/A

cpa

Specifies if call progress detection is used for an outbound call.

yes

display_name

Specifies the display name when creating an outbound call.

N/A

async_dtmf

Specifies if DTMF digits are reported as events outside of a action.

yes

Specifies the signaling mode for DTMF digits.

inband

dtmf_mode

no

no

outofband rfc2833 cleardigits

Specifies whether previously buffered input should be discarded.

yes no

Note: This attribute is considered when async_dtmf is set to Yes. async_tone

Specifies if tones are reported as events outside of a action.

yes

call_action

Refer to attributes.

N/A

early_media

Enables early media when accepting an incoming call.

yes

no

no (default)

25

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameter

Description

Values

info_ack_mode

Specifies how INFO events are acknowledged.

automatic (default) manual

Parameters The following table lists all valid parameters, their definitions and their valid and default values that can be used in an XML payload as part of a call_action. Parameter

Description

Values

Associated Element

play_source

Specifies the file location and file to play.

Refer to properties.



dvr_setting

Specifies the DVR setting for the play.

Refer to attribute.



offset

Specifies the time offset from where the play should start (.wav files only).

The default is zero (0) seconds.



Note: The offset is applied to the initial play only. repeat

Number of times to repeat the play. Use "infinite" to repeat indefinitely. "file://" URIs only.

The default is zero (0) seconds.



delay

Time delay between repeated plays.

The default is one (1) second.



terminate_digits

The digit or digits used to terminate the play.

0-9



* # (default)

max_time

Specifies the playback time limit. The maximum length of time to record.

The default value is infinite.

,

26

Call Resource

Parameter

Description

Values

Associated Element

skip_interval

Defines the amount of time to skip on the forward and backwards actions.

The default is one (1) second.



location

The URL of the content to play in the prompt phase (such as, "file://...", "rtsp://...", "image://").

N/A



forward_key

Defines the DTMF key used to skip forwards.

0-9



* # The default value is 1.

backward_key

Defines the DTMF key used to skip backwards.

0-9



* # The default value is 2.

pause_key

Defines the DTMF key used to pause playback.

0-9



* # The default value is 3.

resume_key

Defines the DTMF key used to resume playback.

0-9



* # The default value is 4.

restart_key

Defines the DTMF key used to restart playback.

0-9



* # The default value is 5.

27

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameter

Description

Values

Associated Element

dvr_action

A DVR action performed on the play.

backward - skip backwards



forward - skip forward pause - pause playback restart - jump back to the start resume - resumed paused playback transaction_id

A unique ID assigned by the PowerMedia XMS RESTful server for the play action.

N/A



play_source

Specifies the location and name of the file to play.

N/A

, , and

recording_uri

Specifies the filename "file://..."

N/A



offset

Specifies the time offset from where the play should start (.wav files only).

N/A

, , and

Note: Applies only to the initial play. repeat

Specifies the number of times to repeat the play.

N/A

, , and

delay

Specifies the time delay between repeated plays.

The default value is one (1) second.

, , and

terminate_digits

The digit or digits used to terminate the playrecord.

0-9

, , and

* #

28

Call Resource

Parameter

Description

Values

Associated Element

beep

Specifies whether to play a tone when starting to record.

yes



Specifies whether DTMF digit input will barge the prompt and force transition to the record phase.

yes

barge

no

no

and

Note: If barge is set to No, the cleardigits attribute implicitly has the value Yes. cleardigits

Specifies whether previous input should be considered or ignored for the purpose of barge-in. Note: When set to No with the barge attribute set to Yes, previously buffered digits will result in the recording phase starting immediately, and the prompt will not be played.

yes - previously buffered digits are discarded

and

no - previously buffered digits are considered

transaction_id

A unique ID assigned by PowerMedia XMS RESTful API.

N/A

, , , , and

max_digits

Specifies the maximum number of digits to collect.

N/A



timeout

Specifies the maximum length of time to wait for the first digit or tone. The time begins when the prompt phase ends.

The default value is infinite.



29

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameter

Description

Values

Associated Element

interdigit_timeou t

The maximum length of time to wait for subsequent digits. This timeout is reset after each digit is received.

The value specified by the timeout parameter.



tone_detection

Enable tone detection.

yes



no (default) uri

The template attributes passed to the image builder. image:id=template&a=b. ..

N/A

, , and

Specifies the uri of the transfer target. duration

The length of time that the overlay or each digit is shown.

Use "infinite" to display until the overlay stops.

and

conf_id

Specifies the conference identifier.

N/A

, , and

caption

Specifies text for caption, as in caller name.

N/A



region

Specifies the video pane used to display this participant's video stream. The current occupant of the region (if any) will be reset to no preference and replaced by this party.

The value 0 (zero) means no preference.

and

audio

Sets the conference audio participation.

inactive - no audio

and

sendonly - only transmit audio recvonly - only receive audio (default) sendrecv - full duplex audio

30

Call Resource

Parameter

Description

Values

Associated Element

video

Sets the conference video participation.

inactive - no video

and

sendonly - only transmit video recvonly - only receive video (default) sendrecv - full duplex video

call_id

Specifies the call identifier on which to perform the action.

N/A

, , and

clamp_dtmf

Determines if DTMF digits are suppressed.

The value specified in xms_create_conferenc e.

and

yes no auto_gain_contr ol

Determines if automatic gain control should be used.

The value specified in xms_create_conferenc e.

and

yes no echo_cancellatio n

Determines if echo cancellation should be used.

The value specified in xms_create_conferenc e.

and

yes no digits

Specifies the digits to send.

0-9



* # ABCD

interval

Specifies the length of time of each digit.

100ms (default)



level

Specifies the amplitude of the DTMF digit tones.

Between 0 and -40dB



-10dB (default)

31

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameter

Description

Values

Associated Element

content_type

Specifies the mime type describing content.

N/A

, , and

content

Specifies the content data.

N/A

, , and

Call Action Scenarios This section provides several diagrams detailing specific call actions.

32

Call Resource Answer/Accept an Inbound Call

33

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide Create an Outbound Call

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 , , and actions are similar to the action.

34

Call Resource Play Scenario

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 , , , and .

35

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide Stop Scenario

36

Call Resource Join/Unjoin Scenario

37

5.

Conference Resource

The Conference Resource encapsulates a single instance of a conference resource on PowerMedia XMS. It contains all call resources currently included in the active conference. Conference-related properties and actions associated with the conference are defined in this section. These include add_party, update_party, remove_party, and playrecord. The following tables show the HTTP methods that can be used with a conference. Note: The payloads shown are examples only as there are many possible variations.

POST URL: /conferences?appid=[appid] Action

Create a conference.

Request XML Payload



HTTP Return Code

Success: 201 CREATED Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR or 400 BAD REQUEST

Response XML Payload

201 Created

PUT URL: /conferences/[conference_id]?appid=[appid] Action

Update a conference. 

Update conference attributes.



Perform one of the following actions per request: play update_play stop

38

Conference Resource

Request XML Payload



HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR

Response XML Payload

200 OK

DELETE URL: /conferences/[call_id]?appid=[appid] Action

Delete a call from a conference.

Request XML Payload

N/A

HTTP Return Code

Success: 204 NO CONTENT Error: 404 NOT FOUND

Response XML Payload

N/A

39

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

GET The GET method has two options – one gets all conferences and the other gets one conference specified by the [conference_id]. URL: /conferences?appid=[appid] Action

Get all conferences.

Request XML Payload

N/A

Response XML Payload

200 OK

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND

URL: /conferences/[conference_id]?appid=[appid] Action

Get a conference.

Request XML Payload

N/A

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND

40

Conference Resource

Response XML Payload

200 OK

XML Schema Definition for Conference The following XML schema definitions provide a formal definition of all possible XML payloads that are valid with the Conference element. request payload

single instance response payload

41

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide get all instances response payload

conf_participant

conf_action

playrecord

Element Attributes The following table lists all valid parameters, their definitions and their valid and default values that can be used in an XML payload as part of a conference. The HTTP method(s) in which they can be used is also provided. Parameter

Description

Values

HTTP Method

type

Sets the media supported by conference.

audio (default)

POST

audiovideo

42

Conference Resource

Parameter

Description

Values

HTTP Method

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.

0, 1, 2, 4, 6, or 9.

POST/PUT

Determines if the caller's ID is overlaid on their image.

yes (default)

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 twenty (20) seconds.

POST

beep

Determines if a tone is played when a party joins/leaves a conference.

yes (default)

POST

Determines if DTMF digits are suppressed.

yes (default)

Determines if automatic gain control should be used.

yes (default)

Determines if echo cancellation should be used.

yes (default)

caption

clamp_dtmf

auto_gain_control

echo_cancellation

Setting to zero (0) means that the number of tiles displayed is determined by the number of active parties. POST

no

no

POST

no POST

no POST

no

43

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameter

Description

Values

HTTP Method

conf_action

Refer to conf_action attributes.

N/A

PUT

Parameters The following table lists all valid parameters, their definitions and valid values that can be returned by PowerMedia XMS in an XML payload as part of the response to a conference POST or PUT. Parameter

Description

Values

identifier

A unique ID of a conference resource.

N/A

href

The http: address of a conference resource.

N/A

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.

N/A

type

Sets the media type supported by the conference.

audio

max_parties

Maximum number of parties in a conference.

N/A

reserve

Number of party resources to reserve for this conference. Any requests beyond this value are honored on a best-effort basis.

N/A

layout

The number of tiles displayed in the conference output.

0, 1, 2, 4, 6, and 9.

Determines if the caller's ID is overlaid on their image.

yes

caption

audiovideo

Zero (0) means that the number of tiles displayed is determined by the number of active presenters.

no

44

Conference Resource

Parameter

Description

Values

caption_duration

The length of time the caption is shown. Use "infinite" (without the quotes) to display the caption for the entire call.

N/A

beep

Determines if a tone is played when a party joins/leaves a conference.

yes

Determines if DTMF digits are suppressed.

yes

Determines if automatic gain control should be used.

yes

Determines if echo cancellation should be used.

yes

conf_action

Refer to conf_action parameters.

N/A

size

Number of conferences.

N/A

conference_ response

Refer to conference_response parameters.

N/A

clamp_dtmf

auto_gain_control

echo_cancellation

no

no

no

no

Parameters The following table lists all valid parameters, their definitions and their valid and default values that can be used in an XML payload as part of a conference. Parameters

Description

Values

Associated Element

play_source

Specifies the file location and file to play. Refer to attributes.

N/A

and

dvr_setting

Specifies the DVR setting for the play. Refer to attributes.

N/A



beep

Specifies whether to play a tone when starting to record.

yes



no

45

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameters

Description

Values

Associated Element

barge

Specifies whether DTMF digit input will barge the prompt and force transition to the record phase.

yes



no

Note: If barge is set to No, the cleardigits attribute implicitly has the value Yes. cleardigits

Specifies whether previous input should be considered or ignored for the purpose of barge-in. Note: When set to No with the barge attribute set to Yes, previously buffered digits will result in the recording phase starting immediately, and the prompt will not be played.

yes - previously buffered digits are discarded



no - previously buffered digits are considered

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.

and

repeat

Number of times to repeat the play. Use "infinite" to repeat indefinitely. "file://" URIs only.

The default is zero (0) seconds.

and

delay

Time delay between repeated plays.

The default is one (1) second.

and

recording_uri

Specifies the filename "file://..."

N/A



46

Conference Resource

Parameters

Description

Values

Associated Element

terminate_digits

The digit or digits used to terminate the play.

0-9

and

* # (default)

max_time

Specifies the playback time limit.

The default value is infinite.

and

skip_interval

Defines the amount of time to skip on the "forward" and "backwards" actions.

The default is one (1) second.



region

Sets the video pane that will display the video media. Conference only.

The value "0" causes the video to be shown fullscreen with the current layout being restored automatically when the play back completes.



location

The URL of the content to be played in the prompt phase (e.g., "file://...", "rtsp://...", "image:").

N/A



forward_key

Defines the DTMF key used to skip forwards.

0-9



* # The default value is 1.

backward_key

Defines the DTMF key used to skip backwards.

0-9



* # The default value is 2.

47

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Parameters

Description

Values

Associated Element

pause_key

Defines the DTMF key used to pause playback.

0-9



* # The default value is 3.

resume_key

Defines the DTMF key used to resume playback.

0-9



* # The default value is 4.

restart_key

Defines the DTMF key used to restart playback.

0-9



* # The default value is 5.

dvr_action

A DVR action performed on the play. It is specified with the transaction ID.

backward - skip backwards



forward - skip forward pause - pause playback restart - jump back to the start resume - resumed paused playback

transaction_id

A unique ID that is assigned by the PowerMedia XMS RESTful server.

N/A

, , and

Conference Actions Scenarios 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 actions on a call resource.

48

Conference Resource

49

6.

Event Handler

HTTP event streaming is implemented in the PowerMedia XMS RESTful server as an eventhandler resource. When the client wishes to receive asynchronous events, it uses the web service to create an eventhandler and to subscribe to specific event types. For example, when the client performs an HTTP GET on a newly created eventhandler, the PowerMedia XMS RESTful server responds with a 200 OK; however, the TCP connection remains open until the client destroys the eventhandler. Event data related to resources and subscribed event types are sent to the client until it deletes the eventhandler. The following tables show the HTTP methods that can be used with the eventhandler. Note: The payloads shown are examples only as there are many possible variations.

POST URL: /eventhandlers?appid=[appid] Action

Create an eventhandler.

Request XML Payload



HTTP Return Code

Success: 201 CREATED Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR

Response XML Payload



PUT URL: /eventhandlers/[eventhandler_id]?appid=[appid] Action

Update/change an eventhandler subscription.

Request XML Payload



50

Event Handler

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR

Response XML Payload



DELETE URL: /eventhandlers/[eventhandler_id]?appid=[appid] Action

Delete an eventhandler.

Request XML Payload

N/A

HTTP Return Code

Success: 204 NO CONTENT Error: 404 NOT FOUND

Response XML Payload

N/A

GET The GET method has two options – one gets all eventhandlers and the other gets one eventhandler specified by the [eventhandler_id]. URL: /eventhandlers?appid=[appid] Action

Get all eventhandlers.

Request XML Payload

N/A

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND

51

Dialogic® PowerMedia™ XMS RESTful API Developer's Guide

Response XML Payload



URL: /eventhandlers/[eventhandler_id]?appid=[appid] Action

Get an eventhandler.

Request XML Payload

N/A

HTTP Return Code

Success: 200 OK Error: 404 NOT FOUND

Response XML Payload



XML Schema Definition for Event Handler The following XML schema definitions provide a formal definition of all possible XML payloads that are valid with the eventhandler element. eventsubscribe

52

Event Handler request payload