Polycom Web Application Developer’s User Manual

Web Application Developer’s Guide Polycom Phones Running Polycom UC Software

UC Software 3.1.1 | October 2010 | 1725-17693-331 Rev. A

Trademark Information

POLYCOM®, the Polycom “Triangles” logo and the names and marks associated with Polycom’s products are trademarks and/or service marks of Polycom, Inc. and are registered and/or common law marks in the United States and various other countries. All other trademarks are property of their respective owners. No portion hereof may be reproduced or transmitted in any form or by any means, for any purpose other than the recipient’s personal use, without the express written permission of Polycom.

Patent Information

The accompanying product is protected by one or more U.S. and foreign patents and/or pending patent applications held by Polycom, Inc.

Disclaimer

Some countries, states, or provinces do not allow the exclusion or limitation of implied warranties or the limitation of incidental or consequential damages for certain products supplied to consumers, or the limitation of liability for personal injury, so the above limitations and exclusions may be limited in their application to you. When the implied warranties are not allowed to be excluded in their entirety, they will be limited to the duration of the applicable written warranty. This warranty gives you specific legal rights which may vary depending on local law.

4750 Willow Road Pleasanton, CA 94588-2708 USA

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Polycom, Inc. Under the law, reproducing includes translating into another language or format.

As between the parties, Polycom, Inc., retains title to and ownership of all proprietary rights with respect to the software contained within its products. The software is protected by United States copyright laws and international treaty provision. Therefore, you must treat the software like any other copyrighted material (e.g., a book or sound recording).

Every effort has been made to ensure that the information in this manual is accurate. Polycom, Inc., is not responsible for printing or clerical errors. Information in this document is subject to change without notice.

About This Guide

The Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX is for developers of applications which use the Web Server and the Microbrowser on SoundPoint IP and SoundStation IP phones and the Browser on the Polycom VVX phones.

The following related documents for SoundPoint IP/SoundStation IP/VVX phones are available:

• Quick Start Guides, which describe how to assemble the phones

• Quick User Guides, which describe the most basic features available on

the phones

• User Guides, which describe the basic and advanced features available on the phones

• Administrator’s Guide, which describes how to configure, customize, manage, and troubleshoot SoundPoint IP/SoundStation IP/VVX phone systems

• Technical Bulletins, which describe workarounds to existing issues and provide expanded descriptions and examples

• Release Notes, which describe the new and changed features and fixed problems in the latest version of the software

For support or service, please go to Polycom Technical Support at

http://www.polycom.com/support/voip/.

Polycom recommends that you record the phone model numbers, software (both the bootROM and SIP), and partner platform for future reference.

SoundPoint IP/SoundStation IP/VVX models: ___________________________

BootROM version: ________________________________________________

SIP Application version: ___________________________________________

Partner Platform: _________________________________________________

iii

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1

2 SoundPoint IP/SoundStation IP/VVX XML API Application

Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1

What is the Microbrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2

What is the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3

What is XHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–4

How to Create Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–5

New Features in SIP 3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–6

Programmable Soft Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1

Telephone Integration URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–4

Push Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–8

Telephony Notification Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–11

Phone State Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–16

API Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–22

3 Application Development for the Microbrowser . . . . . . . . . 3–1

Supported XHTML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1

Basic Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–2

Link Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3

Input Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3

Image Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–6

Table Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–7

Meta Information Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–13

HTTP Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–14

Microbrowser User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–15

Launching the Microbrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–16

Navigation and Form Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–16

Idle Display Microbrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–17

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

Developing an XHTML Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–17

Changing Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 3–18

Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–20

4 Application Development for the Browser . . . . . . . . . . . . . . 4–1

Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–1

HTTP Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–2

Browser User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–3

Launching the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–4

Navigation and Form Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–4

Idle Display Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–5

Setting Up the Polycom SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–5

Developing an XHTML Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–6

Changing Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–6

Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–8

5 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–1

XML Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–1

A Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A–1

Unsupported XHTML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–1

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Index–1

Overview

Polycom has two different application development environments, the one you choose depends on the phone model and software version running on the phone. This guide is intended to provide an overview of each development environment and example applications that will run in each environment.

This chapter provides an overview of the Web Server and the Microbrowser available on certain SoundPoint IP and SoundStation IP phones, and the Polycom VVX 1500 phone running SIP 3.1.3 or earlier. It also provides an overview of the Web Server and the Browser available on the Polycom VVX 1500 phone running SIP 3.2 or later.

Note

When SoundPoint IP 32x/33x is used in this guide, it includes the SoundPoint IP 320, 321, 330, 331, and 335 phones.

A comparison between the Microbrowser and the Browser is shown in the following table.

Microbrowser Browser

Supported On IP 32x/33x, IP 430,

IP 450, IP 550, IP 560, IP 650, IP 670, IP 6000, IP 7000, VVX 1500 (running SIP 3.1.3 or earlier)

XML API programmable soft keys,

telephone integration URIs, push requests, telephone notification events, phone state polling

Capabilities HTML 4.01

XHTML 1.0

VVX 1500 (running SIP

3.2.2 or later)

telephone integration URIs, push requests, telephone notification events, phone state polling

partial HTML 5.0 XHTML 1.1

1 - 1

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

This chapter contains information on:

• What is the Microbrowser

• What is the Browser

• What is XHTML

• How to Create Applications

• New Features in SIP 3.2

To develop an application that can run on the Web Server and the Microbrowser, refer to Application Development for the Microbrowser on page 3-1. To develop an application that can run on the Web Server and the Browser, refer to Application Development for the Browser on page 4-1.

To troubleshoot any problems with your applications, refer to

Troubleshooting on page 5-1.

What is the Microbrowser

The Microbrowser is like any Web browser—Microsoft Internet Explorer and Firefox, for example—but supports only a subset of XHTML features. It can connect to Web servers hosted in the Internet or intranet and download XHTML pages. The Microbrowser supports a limited number of XHTML 1.0 features—it does not have full Web browser functionality.

The Microbrowser downloads XHTML content from a Web server into the phone’s memory, then parses the content to identify XHTML tags and renders these tags onto the phone’s graphic display. The appearance of the rendered page depends on the graphical capabilities and display size of the device on which the browser is running. Complicated pages should be avoided on devices with very small displays.

The Microbrowser does not support scripting (such as JavaScript). All actions on data entered into forms is processed by the server using POST or GET methods.

The XHTML pages displayed on the Microbrowser can contain static or dynamic information.

Static XHTML. These pages are created using XHTML editors and hosted by the Web server. These pages are accessed from the Microbrowser (using HTTP protocol) by entering the URL to access the page. These XHTML pages are called static, because the information that is displayed is already coded into the XHTML pages. These pages do not include information that keeps changing or contact other services for update.

1 - 2

Overview

Dynamic XHTML. These pages involves dynamic information updates of XHTML pages by an application hosted on the Web server. The application residing on the Web server will get information from an intranet or through the Internet—data service providers like Yahoo, Exchange Server, Call Control Servers and other enterprise servers.

Users can launch the Microbrowser on a SoundPoint IP or SoundStation IP phone by pressing the Applications key or, if there isn’t one on the phone, it can be accessed through the Menu key by selecting Applications.

Note

As of SIP 2.2, the Services key and menu entry were renamed Applications, however the functionality remains the same.

The Microbrowser is supported on part of the phone’s total display area:

Microbrowser Screen

Phone T otal Screen Size

SoundPoint IP 32x/33x 102x33 pixels 88x12 pixels SoundPoint IP 430 184x64 pixels 134x31 pixels SoundPoint IP 450 256x116 pixels 171x72 pixels SoundPoint IP

550/560/650/670 SoundStation IP 6000 240x68 pixels 248x32 pixels SoundStation IP 7000 255x128 pixels 255x79 pixels Polycom VVX 1500 800x480 pixels 562x322 pixels

320x160 pixels 213x110 pixels

Size

For more information, refer to Application Development for the Microbrowser on page 3-1.

What is the Browser

The Browser is also like any other major web browser. It is based on the powerful and popular open source WebKit platform. The version can be found in the user agent string. (The user agent string can be seen in network captures in the User-Agent HTTP header.)

The Browser supports true Web 2.0 applications with the following features:

• XHTML 1.1

• HTML 4.01 with partial support for HTML 5

• CCS 2.1 with partial support for CCS 3.0

1 - 3

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

• SVG 1.1 (partial support)

• JavaScript

• XMLHttpRequest

• DOM

• HTTP 1.1

As noted previously, the Browser is only available today on the Polycom VVX 1500 phone. The interactive browser window takes up the phone’s full screen (800x480 pixels). The web content area is 800x395 pixels. The idle browser window is 610x360 pixels.

For more information, refer to Application Development for the Browser on page 4-1.

What is XHTML

XHTML is the abbreviation of eXtensible HyperText Markup Language.

XHTML 1.0 is a transformation of HTML into valid XML. The use of the stricter XML syntax makes parsing of XHTML much easier for small clients, but XHTML 1.0 was also the first step towards making HTML easily extensible. Moving to XML allowed the methods used to create XML extensions to apply to HTML as well. Step two occurred with XHTML 1.1, where XHTML was divided up into ‘modules’, where any features above and beyond a skeleton set were grouped into individual modules. User agent (UA) developers could then decide which extensions to support. A simple user agent can be considered a fully compliant user agent by supporting only the Basic module, whereas a more powerful browser can support all the official modules, as well as those developed by third parties.

Modularization is also intended to help content creators. As more and more devices become web-enabled, the number of platforms a content creator will be asked to support will become unreasonable. By dividing HTML up into different ‘building blocks’ content creators can supply a minimal version of their site for user agents that only support the Basic module, a moderate version of their site for user agents who support the additional modules, and a full version of their site for user agents that support the full range of the XHTML specification.

Finally the X in XHTML was intended to help people who wish to extend HTML. The use of XML brought a standard grammar with which they could define their extension, and the modularization meant that their extension would be just another module that a user agent developer or content creator could choose to support. Additionally, since XHTML pages should state what modules are required to accurately render them, the user agent software could dynamically load a ‘plug-in’ that it could use to render a module that was defined after the user agent had been originally released.

1 - 4

For more information, go to:

• HTML 4.0—http://www.w3.org/TR/html401

• HTML 5 —http://www.w3.org/TR/html5

• XHTML™ 1.0—http://www.w3.org/TR/xhtml1

• XHTML™ Basic—http://www.w3.org/TR/xhtml-basic

• XHTML™ 1.1—http://www.w3.org/TR/xhtml11

• XHTML Tables Module -

XHTML™2.0—http://www.w3.org/TR/2004/WD-xhtml2-20040722/m od-tables.html

For the purposes of this guide, it is assumed that you have experience in HTML and XHTML programming or access to someone who has such experience.

How to Create Applications

Overview

The Polycom Software Development Kit (SDK) application environment allows developers to create full-featured, context-aware applications using familiar web technologies such as AJAX, HTML, JavaScript, and CSS.

The Polycom SDK development environment is based on the popular open source WebKit developer toolset. Combined with an Integrated Development Environment (IDE) and Polycom’s rich set of XML APIs, the development of applications is easy and familiar. To develop widgets or rich, interactive applications, use the open source Web 2.0 technologies known as AJAX. These are the same technologies that allow the migration of web content out of the browser and into other environments. Using open source technologies decreases the development learning curve and increases compatibility between platforms and devices. Common IDE environments include Eclipse, NetBeans, and Microsoft Visual Studio; and form the basis for developing rich and interactive applications.

Microbrowser/Browser applications may be static in nature, but often involve two-way communication that incorporates user input, acknowledgement and interaction. The Polycom XML APIs and support interactive applications development, with access to the resources on the targeted phones.

You can design the following examples of applications:

• Text messaging application

• Company directory

• Stock ticker

Depending on the type and complexity of the application, you might use one of the following tools to assist with application development:

1 - 5

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

• Text editor

• XML editor

• Integrated Development Environment (IDE)

When designing applications, you might want to consider the following guidelines:

Note

These guidelines are for your information only. You are solely responsible for determining the suitability and applicability of this information to your needs.

1. Spend sufficient time designing the application by:

— Developing a conceptual design

— Describe all user-application interactions

— Plan for all user types

2. Create standardized applications to assist in:

— Lowering design time

— Speed up debugging

— Increasing usability

3. Promote consistent output and predictable user input.

4. Create a prototype application to test on sample users.

5. Thoroughly test your application before releasing to:

— Identify all user interface issues

— Verify that all error conditions are caught cleanly

For step-by-step instructions on how to develop an XHTML application that can be run on the Microbrowser of all SoundPoint IP and SoundStation IP phones, refer to Application Development for the Microbrowser on page 3-1. For step-by-step instructions on how to develop an XTML application that can be run on the Browser of the Polycom VVX 1500, refer to Application

Development for the Browser on page 4-1.

Note

Polycom is not responsible for troubleshooting any programming that you create for the Microbrowser and/or Browser.

New Features in SIP 3.2

The following new features were introduced in SIP 3.2.2:

• The Browser on the Polycom VVX 1500

— What is the Browser

1 - 6

Overview

The following existing sections were changed in SIP 3.2.0:

• Programmable Soft Keys on page 2-1

• Telephone Integration URIs on page 2-4

• Call Line Information on page 2-17

• HTTP Support on page 3-14

The Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family has been reorganized:

• SoundPoint IP/SoundStation IP/VVX XML API Application Interface is

now in a separate chapter, Chapter 2

• Application Development for the Microbrowser is now in a separate

chapter, Chapter 3

• Application Development for the Browser is in a new chapter, Chapter 4

1 - 7

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

1 - 8

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

There is XML API support for applications on the SoundPoint IP 32x/33x, 430, 450, 550, 560, 650, and 670 desktop phones, the SoundStation IP 6000 and 7000 conference phones, and the Polycom VVX 1500 phones.

The SoundPoint IP/SoundStation IP/VVX XML API is intended to provide developers with flexibility in developing applications on SoundPoint IP, SoundStation IP, and Polycom VVX 1500 phones, while tightly integrating into the phone’s telephony capabilities and functions. The XML API features are supported by the Microbrowser and Browser, except where noted.

This support includes:

• Programmable Soft Keys

• Telephone Integration URIs

• Push Requests

• Telephony Notification Events

• Phone State Polling

For a discussion of the security aspects of this API, refer to API Security on page 2-22.

Programmable Soft Keys

Note

The programmable soft key tag is not supported in the Browser on the Polycom VVX 1500. However, the same functionality can be created through HTML button tag:

The following programmable soft key tag is supported:

• <softkey>—Defines a soft key

2 - 1

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

The softkey element creates a soft key with a customizable label, position, and action. Users execute actions by pressing the soft key on their phone.

The soft keys are modified within the interactive Microbrowser only.

The following format is supported:

The following attributes are supported:

Attribute Value/s Description

index numeric, 1 to 8 Position of the soft key. name string Text displayed on soft key when

label string Text displayed on soft key. The

Softkey:Submit action is used. It is ignored for all other actions. Use in cases where more than one Softkey:Submit action appears on a page.

maximum length is 9 characters.

Note: If empty or absent, default action name is displayed.

action URI Supported actions (must be one of

those listed in the next table).

The supported actions are described in the following table:

Action Default Action Name Description

SoftKey:Home Home Moves to configured home page Softkey:Back Back Move to previous page SoftKey:Exit Exit Exits Microbrowser SoftKey:Cancel Cancel Cancel action SoftKey:Refresh Refresh Refreshes current page SoftKey:Fetch;

<URI> SoftKey:Reset Reset Clears all input fields in the form SoftKey:Submit Submit Submits the form Key:VolDown VolDown Decreases volume by 1 unit Key:VolUp VolUp Increases volume by 1 unit

Fetch Fetches the page from the given

URI

2 - 2

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

Action Default Action Name Description

Key:DoNotDisturb Do not disturb Enables Do Not Disturb feature Key:Headset Headset Enables use of microphone Key:Handsfree Hands-free Enables use of speaker Key:Messages Messages Open the Messages menu Key:Applications Applications Open the Applications menu Key:MicMute Mute Mutes the phone when the call

state Key:Directories Directories Open the Directories menu Key:Menu Menu Opens the main menu Key:Setup Setup Opens the main menu Settings

Depending on the browser state, a number of predefined soft keys exist:

Note

Action Predefined Soft Key

Browser Active—fetching pages or rendering data

Browser Stop—no longer active Home, Refresh, Back, Exit or

Edit Active—when entering text Home, A->a1, Back, Exit

The soft keys from the “Browser Active” and “Edit Active” soft key groups override any custom soft keys defined in the current XHTML.

The soft keys from the “Browser Stop” soft key group appear if no custom soft keys are defined.

The exact soft keys that appear vary between the SoundPoint IP and SoundStation IP phones.

Home, Refresh, Back, Stop

programmable soft key

The following should be noted with respect to softkey tags:

• All actions are case insensitive.

• If the soft key action name is empty, the soft key tag is ignored.

• The Reset and Submit soft key tags must exist inside the

<form>

tag that

they are to act upon.

• On the Polycom VVX 1500, the Reset and Submit soft key tags can exists inside a single form element. If there are multiple forms inside an XHTML document, the XHTML Submit and Reset input elements must be used.

2 - 3

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

• Indexes need not be sequential. A missing index will result in an empty space, no soft key displayed.

• An index greater than eight is ignored.

• By default, a Back soft key is placed on the graphic display (even if one is

not defined).

Note

The Back soft key will not appear when otherwise it will appear.

• When using more than one Submit soft key on page, use the name to distinguish between them.

For example, to create a simple page:

<html>

<p> Hello World! </p><br/>

</html>

Telephone Integration URIs

Internal URIs provide the interface to execute predefined actions on the phone. These actions are similar to the manual execution of key presses by the user.

There are three ways to execute an internal URI action:

• If the file sent to the phone contains only internal URI actions, the file content type must be “ internal URIs are executed in ascending order.

mb.main.autoBackKey

is set to 0;

application/x-com-polycom-spipx

”. The

2 - 4

• If an XHTML file will include internal URI, they must be defined in (and executed from) anchor tags, in the

hef=”Key:Setup”>Menu</a>

). When the user selects the anchor, the

attribute (for example,

href

action is processed and executed.

• Use one of the following soft key actions in anchor tags:

— SoftKey:Home

— SoftKey:Back

— SoftKey:Exit

— SoftKey:Cancel

— SoftKey:Refresh

Refer to Programmable Soft Keys on page 2-1.

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

Note

Internal URI actions contained in a file with content type

application/x-com-polycom-spipx

“

” can be executed only through a URL push.

The following format is supported:

ActionType:Action

where:

• ActionType is a type of key or action to execute (Key, Softkey, Tel, or Play)

• Action is the name of the action to be executed.

The supported internal URIs are described in the following table:

Action Type Action Description

Key Line1 to Line48 The Key URIs send the key press

DialPad0 to DialPad9 SoftKey1 to SoftKey5 DialPadStar DialPadPound VolDown

event to the phone. The phone processes this event as if the button had been physically pressed.

VolUp Headset Handsfree MicMute Menu Messages Applications Directories Setup ArrowUp ArrowDown ArrowLeft ArrowRight

2 - 5

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

Action Type Action Description

Key (Continued) Backspace

DoNotDisturb Select Conference Transfer Redial Hold

SoftKey Back The SoftKey URIs send the soft

Cancel Exit Home Refresh

key press event to the phone. The phone processes this event as if the associated soft key had been physically pressed. These URIs function when the interactive Microbrowser is on the screen.

Note: The programmable soft key related URIs are not supported on the Browser on the Polycom VVX

1500.

Tel Number;LineIndex The Tel URI initiates a new call to

the specified number on the specified line. The line number is optional (the first available line is used). The digit map rules are followed (refer to “Digit Map” in the

Administrator’s Guide for the SoundPoint IP / SoundStation IP / VVX Family).

Note: The LineIndex value is case insensitive. The range of LineIndex is “Line1” to “Line48”.

Note: If the line corresponding to the LineIndex in the Tel action is busy, the existing call on that line is held and a call is placed to the number specified in the Tel URI on that given line.

2 - 6

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

Action Type Action Description

Play Play:<audiofile_path> Download and play the audio file.

The supported audio formats are G.711μ-law, G.711a-law, and Liner16.

The <audiofile_path> is the relative path on the application server, relative to

apps.push.serverRootURL

The supported maximum file size is determined by

res.finder.sizeLimit.

For G.711μ-law and G.711a-law files:

• Sample rate must be 8ksps with a sample size of 8. This is supported on all phones.

For Liner16 files:

• Sample size must 16 for all sample rates.

• Sample rate of 16ksps is supported on SoundPoint IP 32x/33x, 430, 450, 550, 560, 650, and 670, SoundStation IP 6000 and 7000, and Polycom VVX 1500 phones.

• Sample rate of 32ksps and 48 ksps is supported on SoundStation IP 6000 and 7000 and Polycom VVX 1500 phones.

• Sample rate of 8ksps and 44.1 ksps is supported on Polycom VVX 1500 phones.

Note: An error is logged if the file is too large to play.

The following should be noted with respect to internal URIs:

• The action name and key type are case insensitive.

• For non-XHTML content containing only internal URIs, the internal URIs

are executed in ascending order without any delay.

• If any URI is invalid and it is in a file of only internal URIs, the entire file is rejected.

2 - 7

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

• If any invalid URI is present in a XHTML file, the execution of that URI is ignored.

For example, to create a link that behaves as if you pressed the Do Not Disturb key:

<html>

<body> <br/> Click on the link to engage the DND feature

<a href="Key:DoNotDisturb">DNDSettings</a>

</body> <softkey index="1" label="Back" action="SoftKey:Back" /> <softkey index="2" label="Exit" action="SoftKey:Exit" />

</html>

For example, to place a call to “*50”:

<html>

</body>

</html>

Push Requests

A push request is defined as a request that you send to a remote site asking for data to be sent to you.

HTTP <URL> Push

The HTTP URL push allows you to send asynchronous relative URIs to a specific phone.

The following format is supported:

2 - 8

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

The following attributes are supported:

Attribute Value/s Description

Note

priority “critical” = Accept critical priority

push requests only “Normal” = accept normal priority push requests only

URI path string Any relative URI (or relative URI

This tag must be defined under a

Priority

Note: If attribute is absent, “normal” is used.

path) on the configured application server.

Note: Currently multiple URIs in a single push request are not supported.

root tag.

The following table describes when to use a specific priority:

Phone State Priority Description

Idle State Critical The phone will display push

request immediately.

Normal The phone will display push

request immediately.

Non-Idle State Critical The phone will display push

request immediately.

Normal The phone will keep push request

in push queue. Once the phone is idle, the push request will be displayed.

The following should be noted with respect to HTTP URI push:

• By default, a Back soft key is placed on the graphic display.

The Back soft key will not appear when

mb.main.autoBackKey

is set to 0;

otherwise it will appear.

• Push requests are displayed as “first-in-first-out”.

• Changes must be made in the sip.cfg configuration file to enable this

feature. For example, the

httpd.enabled

parameter must be set to 1 (default setting). Refer to Push Request Configuration Parameters on page

2-11.

2 - 9

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

• All HTTP requests are challenged through HTTP Digest Authentication.

• If the phone cannot fetch the content from the pushed URI, the request is

ignored.

For example, to push the display of soft keys that fetch pages:

<URL priority=”normal”>/examples/media.xhtml</URL>

</PolycomIPPhone>

where

<html>  Press any soft key to fetch the corresponding page <softkey index="1" label="Top News" action="SoftKey:Fetch;http://www.cbc.ca/news/world/top/> <softkey index="2" label="Weather "action="SoftKey:Fetch;http://www.theweathernetwork.com/canada/bc/burn aby/current/"/> <softkey index="4" label="Sports" action="SoftKey:Fetch;http://www.tsn.ca/topstory/"/> <softkey index="3" label="Back" action="SoftKey:Back"/> </html>

media.xhtml

is defined as follows:

HTML <Data> Push

The data push allows you to send messages in XHTML format to a specific phone.

The following format is supported:

The following attributes are supported:

2 - 10

Note

Attribute Value/s Description

priority “critical” = Accept critical priority

push requests only “Normal” = accept normal priority push requests only

text text in HTML format Text

This tag must be defined under a

Priority

Note: If attribute is absent, “normal” is used.

Note: The maximum file size is 1KB.

root tag.

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

For example, to push the display of an important message:

<Data priority=”critical”> <h1> Fire Drill at 2pm </h1> Please exit and congregate at your appropriate location outside </Data> </PolycomIPPhone>

The following should be noted with respect to HTTP data push:

• Changes must be made in the sip.cfg configuration file to enable this

feature. For example, the

httpd.enabled

parameter must be set to 1 (default setting). Refer to Push Request Configuration Parameters on page

2-11.

Push Request Configuration Parameters

The push request configuration parameters in sip.cfg must be set as follows to enable push requests:

• Set

apps.push.messageType

For example,

• Set

apps.push.serverRootURL

URL.

For example,

• Set

apps.push.username

For example,

The username and password are required to authenticate incoming push requests to the phone.

• Set

apps.push.password

For example,

Telephony Notification Events

The phone can be configured to send information to a specific URI if one of the following telephony notification events occurs:

• Incoming Call Event

• Outgoing Call Event

to the appropriate display priority.

apps.push.messageType

to the application server root relative

apps.push.serverRootURL

to the appropriate username.

apps.push.username

=bob

to the appropriate password.

apps.push.password

=1234

=/sampleapps

• Offhook Event

• Onhook Event

These events are XML data posted to web server by the phone’s Microbrowser or Browser.

2 - 11

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

Changes must be made in the sip.cfg configuration file to enable this feature. Refer to Telephony Event Notification Configuration Parameters on page 2-16.

Incoming Call Event

The following format is supported:

</IncomingCallEvent>

The following attributes are supported:

Attribute Value/s Description

Phone IP IP address IP address of the phone.

For example, “172.24.128.160”

MACAddress MAC address MAC address of the phone.

For example, “0004f214b8e7”

CallingPartyName name The name displayed in phone's

"From" label in screen.

• If the line is registered and the call is initiated from that line, then the registered line display name of the calling party is shown. For example, “SoundPoint IP”

• If the line is not registered and the call is initiated from that line, then IP address of the calling party is shown. For example, “sip:172.24.128.160”

2 - 12

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

Attribute Value/s Description

CallingPartyNumber number The number displayed on the

phone.

• If the line is registered and the call is initiated from that line, the registered line number of the calling party is shown.

• If the line is not registered and the call is initiated using IP address from that line, the IP address of the calling party is shown.

CalledPartyName name • If the call is received by

registered line, the registered line display name of the called party is shown.

• If the call is received on a nonregistered line, the IP address of the called party is shown.

CalledPartyNumber number • If the call is received by

registered line, the registered line number of the called party is shown.

• If the call is received on a nonregistered line, the IP address of the called party is shown.

TimeStamp time The date and time that the event

occurred on the phone. For example,

“2008-07-11T13:19:53-08:00”

When the telephone notification URI is set and the incoming call event is enabled to gather information, the following example shows the transmitted data for a call between two registered lines:

</IncomingCallEvent>

</PolycomIPPhone>

2 - 13

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

Outgoing Call Event

The following format is supported:

</OutgoingCallEvent>

The following attributes are supported:

Attribute Value/s Description

Phone IP IP address IP address of the phone.

MACAddress MAC address MAC address of the phone.

For example, “172.24.128.160”

For example, “0004f214b8e7”

CallingPartyName name • If the line is registered and the

call is initiated from that line, then the registered line display name of the calling party is shown.

• If the line is not registered and the call is initiated from that line, then IP address of the calling party is shown.

CallingPartyNumber number • If the line is registered and the

call is initiated from that line, the registered line number of the calling party is shown.

• If the line is not registered and the call is initiated using IP address from that line, the IP address of the calling party is shown.

CalledPartyName name The name displayed at phone’s

"To" name.

• If the call is received by registered line, the registered line display name of the called party is shown.

• If the call is received on a nonregistered line, the IP address of the called party is shown.

2 - 14

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

Attribute Value/s Description

CalledPartyNumber number The number displayed on the

phone.

• If the call is received by registered line, the registered line number of the called party is shown.

• If the call is received on a nonregistered line, the IP address of the called party is shown.

TimeStamp time The date and time that the event

occurred on the phone. For example,

“2008-07-11T13:19:53-08:00”

Offhook Event

The following format is supported:

</OffHookEvent>

The following attributes are supported:

Attribute Value/s Description

Phone IP IP address IP address of the phone.

For example, “172.24.128.160”

MACAddress MAC address MAC address of the phone.

For example, “0004f214b8e7”

TimeStamp time The date and time that the event

occurred on the phone. For example,

“2008-07-11T13:19:53-08:00”

Onhook Event

The following format is supported:

</OnHookEvent>

2 - 15

Web Application Developer’s Guide for the SoundPoint IP/SoundStation IP/VVX Family

The following attributes are supported:

Attribute Value/s Description

Phone IP IP address IP address of the phone.

MACAddress MAC address MAC address of the phone.

TimeStamp time The date and time that the event

Telephony Event Notification Configuration Parameters

The telephone event notification configuration parameters in sip.cfg must be set as followed:

For example, “172.24.128.160”

For example, “0004f214b8e7”

occurred on the phone. For example,

“2008-07-11T13:19:53-08:00”

• Set

apps.telNotification.URL

to the location where notifications

should be sent.

For example,

apps.telNotification.URL

=http://172.24.128.85:8080

If this URL is set to Null, the notifications events will not be sent.

• Set

apps.telNotification.incomingEvent

to 1 or 0 (for Enable or

Disable respectively).

For example,

• Set

apps.telNotification.outgoingEvent

apps.telNotification.incomingEvent

to 1 or 0 (for Enable or

Disable respectively).

For example,

• Set

apps.telNotification.offhookEvent

apps.telNotification.outgoingEvent

to 1 or 0 (for Enable or

Disable respectively).

For example,

• Set

apps.telNotification.onhookEvent

apps.telNotification.offhookEvent

to 1 or 0 (for Enable or Disable

respectively).

For example,

apps.telNotification.onhookEvent

2 - 16

+ 75 hidden pages

Polycom Web Application Developer’s User Manual

Contents

Overview

What is the Microbrowser

What is the Browser

What is XHTML

How to Create Applications

New Features in SIP 3.2

SoundPoint IP/SoundStation IP/VVX XML API Application Interface

Programmable Soft Keys

Telephone Integration URIs

Push Requests

Telephony Notification Events