Pushing the Limits: Avaya IP Telephones Equip Developers with Web and Push APIs

Any developer with knowledge of Web servers and standard Web protocols, such as Hypertext Transfer Protocol (HTTP) and Wireless Markup Language (WML), can program Avaya's 4600 series Internet Protocol (IP) phones to create an application-enabled appliance. Developers have two API options, the Web API and Push API.

Avaya's 4600 series of IP phones come equipped with an embedded micro Web browser that renders WML pages and allows end-users to use the phone to access Web-based enterprise applications. The Web API enables developers to create WML pages that can then be loaded by the phone. For example, a phone in a hotel lobby or guest room could be configured to access WML pages that allow the guest to see a list of local restaurants. By embedding a special WTAI link in the page (more on that later), the user can easily place an outgoing call to the restaurant.

The Push API allows developers to create an external application that sends, or "pushes," information to the display of an IP phone or multiple IP phones, such as a conference call reminder or an emergency alert. The Push API allows a simple text message, an entire WML application, or an audio stream to be sent to the phone.

Avaya 4600 Series IP Phones can also be configured to perform a Subscription service at boot-up, registering pertinent information about themselves with external applications using a simple HTTP GET command. This allows applications to dynamically build an intelligent database of users and eases the administration of adding new phones. Through a special Subscription Push (part of the Push API), phones can also be told to re-register themselves at any time.

No proprietary technologies or special servers are required to use the Avaya IP Telephone's Web and Push APIs. If you're a developer with knowledge of how to create a WML page, are familiar with HTTP and standard Web servers, then you're ready to begin. For the record, WML is a markup language based on XML. Essentially, WML is a stripped-down version of syntactically valid HTML with 35 strictly applied semantic tags. So, if you are familiar with HTML, then the transition to WML will be an easy one indeed.

We'll talk more later about how to access the Web API and Push API and upload WML pages to 4600 series IP phones. First, let's talk about how the IP phones work with the Web browser.

Avaya IP Phones
In the 4600 series of Avaya IP phones, the 4610SW, 4620/4620SW, 4621SW, 4622SW, and 4625SW support the Web and Push APIs. The IP telephones that support the Web browser have twelve feature buttons that are available for Web applications, with the exception of the Avaya 4610SW, with six feature buttons. When the phone is in Web Browser mode, the buttons and the display take on special functions. The top display line on the phones is reserved for messages, text entry prompts, and page titles. The display line at the bottom of the IP phones presents the programmable soft key selections, four of which can be displayed at one time. The rest of the screen is used for the rendering of WML pages. The Figure 1 shows a 4620SW phone with a WML page displayed and the special functions of the buttons and the display indicated.

Figure 1. 4620SW Phone

The APIs
No proprietary technologies are required to access the Avaya Web and Push APIs other than the IP phones themselves. The API is embedded as part of the IP phone itself, so no downloading of an API library is necessary. You just need to reset some server settings and write a few lines of XML and some WML pages. Here's how the APIs work.

Web API
It's a simple matter to enable the Web browser functionality on the Avaya 4600 Series IP Telephones. All you have to do is configure a standard Web server to support two additional MIME types, .wml and .wbmp extensions. This Web server can now host your WML pages. This can even be an existing Web server that is already hosting a company's intranet Web pages. To initialize the IP phone to access a WML "home page," just set one variable in the phone's configuration file with the URL of the WML page. Now, when using the phone's Web button, the end-user accesses the Web content you programmed the phone to display.

In addition, you can use the IP phones to access WML pages on the Internet. Just embed links to theses pages in your WML. The IP phones can be configured to use the same proxy servers and proxy exception lists as the browsers in your desktop PCs, thus adhering to the same security and controls as desktop users.

Figure 2. Cards

The Web browser supports WML 1.3. Avaya provides extensive documentation to aid in creating WML pages, including sample code, and tutorials. See the section on Support below for more details.

Now, let's look at some sample WML code and how it gets displayed on the IP phone. A full discussion on WML is beyond the scope of this article, but here's a brief overview. In WML nomenclature, a WML file is commonly referred to as a Deck, which consists of Cards. An entire Deck (WML file) is downloaded to the IP phone while only a single Card is displayed at any given time. WML lets you control navigation between cards in the deck with links or soft-key buttons, as well as allowing links that cause a new WML page to be loaded. Figure 2 illustrates these points. Note the standard XML prolog block that must appear at the beginning of each WML file, as well as the use of the <do> tag to create a soft-key with the label "Next."

Figure 3. Form Elements

Of course, the Avaya 4600 Series IP Telephone Web Browser is not restricted to just displaying static content. WML pages can also be full-fledged Web applications that support user input through standard Web Forms, which can then be submitted to a Web server for processing. Standard form elements such as text input, checkboxes, and radio buttons are supported. The Figure 3 shows how Form elements are encoded in WML and rendered by the Web browser.

The Web browser supports Wireless Telephony Application Interface (WTAI). This allows the WML page to contain special links that perform Click-to-Dial or Add-to-Speed-Dial functions. Click-to-Dial refers to the phone placing an outgoing call, while Add-to-Speed-Dial causes a phone number to be stored in the phone's speed dial directory. Figure 4 shows a WML file with WTAI links. Note that the links are rendered with a special graphic symbol that indicates their function. They are accessed the same way navigational links are, by pressing the associated button on the left side of the IP phone's display.

Figure 4. WML File with WTAI Links

Even graphics can be displayed. The 4610SW, 4620/4620SW, 4621SW and 4622SW support the display of WBMP images. The color display on the 4625SW also supports JPEG images

Figures 4 and 5 show a small subset of all the tags and attributes available to a developer writing Web-based applications for the Avaya 4600 Series IP Telephones. For a full description, download "4600 Series IP Telephones Application Programmer Interface (API) Guide" at http://www.avaya.com/support.

You can use the Web interface for Avaya 4600 IP phones to build applications that serve many vertical markets, including:

Figure 5. Display of WBMP Images

• Hospitality applications for lobby or guest room phones that provide guests with access to local information, valet service or special concierge services
• Financial services applications, such as integration with digital merchandizing displays for branch banking customers
• Applications for K-12 schools, such as broadcasting alerts to classrooms, administrative offices and even parents' cell phones

Push API
The Push API allows an external application to spontaneously send data to an Avaya IP telephone. Unlike the Browser interface, which requires a user to initiate the interaction with the application, the Push API enables developers to use the IP phone in a proactive way.

The Push API can be used in a variety of applications where an application needs to proactively reach out and contact users. For example:

• Broadcast company news
• Send meeting reminders with click-to-dial conference bridge numbers,
• Stream music, such as wake-up music in hotel guest rooms
• Stream audio announcements
• Broadcast weather alerts
• Send company-wide announcements and reminders
• Display advertisements

As with the Web functionality, no additional servers are required for Push functionality. The same intranet server used for the Web interface can be a trusted push server.

To access the Push API, you will need to write a few lines of XML and use the HTTP POST command using any language like ASP.NET, JavaScript, or PHP that allows the HTTP POST request to be sent. Before we show the syntax of a Push Message and discuss the different types of messages, let's first define some terminology and look at the steps involved in a Push Request.

• Push Initiator: An application capable of transmitting the Push Message to the Push Agent.
• Push Agent: The telephone software resident on the Avaya IP Telephone that is capable of receiving the Push Message from the Push Initiator. The Push Agent processes the Push Message and requests the Push Content.
• Trusted Push Server (TPS): A Web server serving the Push Content that conforms to the security settings as established by the TPSLIST parameter in the IP phone configuration file. This can be an existing Web server within the network, or the same server as the Push Initiator.
• Push Content (PC): A file containing the data that the IP phone will ultimately display.

A Push Message sent using the Push API is really a multiple step operation, as illustrated in Figure 6.

Figure 6. Diagram of a Push Message Sent Using the Push API

Once a Push Message is received from the Push Initiator (step 1A), the Push Agent first parses the Push Message XML for validation and mismatched tag errors. Next, the push agent verifies that the URL in the Push Message is a Trusted Push Server. It then returns the result of the validation to the Push Initiator (step 1B). The Push Agent then requests the Push Content from the Trusted Push Server via an HTTP GET request to the URL (step 2A) and displays (or plays in the case of an Audio Push) the results (step 2B).

All Push Messages consist of a few lines of simple XML that is packaged in an HTTP POST command and sent to the phone. The HTTP POST address (URL) for the IP telephone where a Push request is sent to is:

http://<IP_Address_of_the_telephone>/forms/push

Where, <IP_Address_of_the_telephone> is the IP Address of the telephone where the push is to be sent in the dotted-decimal format.

The Push Agent will process all POST methods received by the phone's HTTP server that contain the above URL. All HTTP POST requests must be sent to this URL only. All XML messages are sent in the HTTP POST pre-defined variable called "XMLData".

All Push Messages have a couple things in common. Each message (except the Subscription Push) has an alert attribute and a mode attribute. Setting the alert attribute causes the phone to beep that number of times when the Push Message is received. The mode attribute is used to control the priority of the message. Messages sent with mode=normal will not override certain states that the phone may be in and be rejected whereas messages sent with mode=barge will override certain phone activities. The "4600 Series IP Telephones Application Programmer Interface (API) Guide" describes in detail which phone states are considered pushable depending on the mode value. All Push Messages support the <postfield> tag as part of the <go> tag. This allows applications to set name/value pairs that can be sent to the Push Content server along with the request.

Now let's see just how easy it is to format and send a message using the Push API.

Display Push
The Display Push type is used to send an entire WML Deck to the phone's display. Use it when you want to send information to the entire display, which can be as simple as a conference call reminder with a WTAI Click-to-Dial link or a full-blown WML application.

The syntax of the Display Push is:

<?xml version="1.0"?>
<Push
alert="0|1|2|3"
type="display"
mode="normal|barge"
>
  <go href="http://trusted_push_server/filename.wml" method="get|post">
<postfield name="name1" value="value1"/>
<postfield name="name2" value="value2"/>
  </go>
</Push>

The Display Push type's Push Content (the URL referenced in the <go> tag) must be a WML file. This file can contain any of the Web browser elements and features.

Topline Push
Use the Topline Push when you only need to send a single-line text message that will be displayed on the top line of the display.

The syntax of the Topline Push is:

<?xml version="1.0"?>
<Push
alert="0|1|2|3"
type="topline"
mode="normal|barge"
>
  <go href="http://trusted_push_server/filename.xml" method="get|post">
   <postfield name="name1" value="value1"/>
   <postfield name="name2" value="value2"/>
  </go>
</Push>

The Topline Push type's Push Content (the URL referenced in the <go> tag) must be an XML file with the following format:

<?xml version="1.0"?>
<Response>
<Topline>
Text to display
</Topline>
</Response>

Audio Push
You can use the Audio Push to stream an audio message to an IP phone. The Audio push allows you to transmit Real-time Transfer Protocol (RTP) streams to IP phones. To stream audio to the IP phone, you will need an RTP port. The Push Agent sends the port information to the Trusted Push Server in the GET string. The GET string contains the variable "rtpLPort", the telephone's local port to be used for audio streaming.

The syntax of the Audio Push is:

<?xml version="1.0"?>
<Push
alert="0|1|2|3"
type="audio"
mode="normal|barge"
>
  <go href="http://trusted_push_server/filename.xml" method="get|post">
  	<postfield name="name1" value="value1"/>
                <postfield name="name2" value="value2"/>
  </go>
</Push>

The Audio Push type's Push Content must be an XML file with the following format:

<?xml version="1.0"?>
<Response>
<Audio
packetsize="10|20|30|40|50|60"
codec = "PCMU | PCMA"
>
  <AudioTimer value="30"/>
  <Url href="RTPRx://rtpserver_ip_address:rtpLPort">
</Audio>
</Response>

Subscribe Push
Use the Subscribe Push as a subscription service for your organization's IP phones. It allows an application to maintain a database of telephone's information, which can then be used by Push Initiators to target phones or groups of phones using the Push API. The Subscribe Push sends re-subscription requests. Recall that the phones also subscribe at boot-up. Further, the Subscription Push is processed in the background-- no user interface is required and therefore there's no concept of alerts or priorities.

A subscription consists of an HTTP request to the subscription server passing the following values:

• User's Telephone Extension
• IP Address of the telephone
• MAC Address of the telephone
• Set ID, an eight character model number which is fixed and does not change

For example: GET:http//<subscription_server>/<script_name>?MAC=xxx+Extn=xxx+ip=xxx+SetID=xxx

The syntax of the Subscribe Push is:

<?xml version="1.0"?>
<Push type="subscribe">
<go  href="http://subscription_server/filename.xml" method="get|post">
 <postfield name="name1" value="value1"/>
 <postfield name="name2" value="value2"/>
  </go>
</Push>

The Subscription Push type's Push Content must be an XML file with the following format:

<?xml version="1.0"?>
<Response>
<Subscribe type="all|me">
<Url href= "Subscription_Server_Url" />
</Subscribe>
</Response >

Avaya Support
Avaya is dedicated to providing support to developers building applications using the Web and Push APIs. There is a wealth of information available for free download from http://www.avaya.com/support, including the following materials:

• Avaya 4600 Series IP Telephones Application Programmer Interface (API) Guide: contains detailed documentation for developers covering the Web browser and the Push API
• Avaya 4600 Series IP Telephone R2.3 LAN Administrator Guide: contains detailed information for administering DHCP and TFTP servers to support Avaya 4600 Series IP Telephones
• The latest Avaya 4600 Series IP Telephone firmware files: the most current releases of the firmware for Avaya 4600 Series IP Telephones
• The Avaya TFTP Server Application
• The 46xxxsettings.txt file which is the configuration file for Avaya IP Telephones
• Sample code

In addition, Avaya's DeveloperConnection Program provides access to a comprehensive set of innovative support and marketing programs that help you create a new generation of innovative communication solutions. Benefits of Registered Membership include:

• Access to Avaya APIs and SDKs
• Discounted pricing on Avaya products and platforms used for development
• Enhanced developer education and support
• Online courses and tutorials
• Additional sample code
• FAQs
• Forums
• Use of the Avaya DeveloperConnection logo

Learn more about the DevConnect program at http://www.devconnectprogram.com.

The End Point
Using the Push and Web APIs and open standards protocols, enterprise developers can go beyond IP telephony application development to create an application-enabled appliance on the desktop. Desktops are not the limit, though. Avaya 4600 IP phones in an office, school, lobby, or anywhere else give users valuable Web access via an Avaya IP phone.