Pushing xml to the cisco ip phone

Did you know that it is possible to send a text message or an image to a cisco ip phone? It is also possible to play a ringtone on a distant phone.
I will illustrate how it works. This will serve as a an introduction to implement new services in the cisco (in a future post).

CiscoIPPhone object

Actually, it’s quite simple. The cisco website explains that the instructions have to be sent in CiscoIPPhone objects: it’s nothing more than xml in a POST request. For example, I want to send a text message to a colleague:

<CiscoIPPhoneText>
   <Prompt>hey there!</Prompt>
   <Text>This is a cool message.</Text>
</CiscoIPPhoneText>

which will give as result:

Very simple, right? Let’s see the code to display an image. Images should not exceed 295 x 140 pixels (I first resize and convert the images with the PHP script in the previous post).

<CiscoIPPhoneImageFile>
   <Prompt>hey there!<Prompt>
   <URL>http://172.18.1.1/cisco/image.png</URL>
</CiscoIPPhoneImageFile>

and the result:

To display a menu, the following code must be used:

<CiscoIPPhoneMenu>
   <Title>My applications</Title>
   <Prompt>Choose an item</Prompt>
   <MenuItem>
      <Name>a random picture</Name>
      <URL>http://172.18.1.1/cisco/randomPicture.php</URL>
   </MenuItem>
   <MenuItem>
      <Name>a random citation</Name>
      <URL>http://172.18.1.1/cisco/randomCitation.php</URL>
   </MenuItem>
</CiscoIPPhoneMenu>

When selecting an item, the cisco connects to the URL of the MenuItem. The URL points to another CiscoIPPhone object. Here is the illustration of the menu:

In order to play a ringtone:

<CiscoIPPhoneExecute>
   <ExecuteItem URL="Play:music1.wav"></ExecuteItem>
</CiscoIPPhoneExecute>

The ExecuteItem tag does not display anything. In the URL attribute, we tell the phone that it has to do something. Instead of playing a sound, you can tell to dial a number with Dial:123.

Forging a POST request

Now let’s see the content of the POST request. The cisco expects to receive an authenticated (basic) HTTP POST request at the URL http://IP_ADDRESS_CISCO/CGI/Execute (note that there is no trailing slash !).

POST /CGI/Execute HTTP/1.1
Host: 172.18.22.32
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.2.10) Gecko/20100914 Firefox/3.6.10 (.NET CLR 3.5.30729)
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 115
Connection: close
Authorization: Basic MTIzOjEyMw==
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 105
Pragma: no-cache
Cache-Control: no-cache

XML=%3CCiscoIPPhoneExecute%3E%3CExecuteItem%20URL%3D%22Dial%3A789%22%20%2F%3E%3C%2FCiscoIPPhoneExecute%3E

Some notes about the HTTP request above:

• authenticated: the cisco needs the login and password of your cisco phone. For me, my login is the extension number. The basic authentication is used (see line 10).
• POST request: the body of the POST request must be XML= followed by the CiscoIPPhone object (which must be url-encoded, see line 16)
• IP_ADDRESS_CISCO: to replace by the ip of your cisco. You can get it in Settings > Network Configuration > IPv4 Configuration

Fortunately, some libraries are at our disposal. The Cisco::IPPhone Perl module allows sending custom messages to the cisco. It is well explained in their website so I won’t detail the use of this library.

With the Zend Framework (PHP), pushing a xml content would be done like this:

$login='123';
$password='456';
$xml='<CiscoIPPhoneExecute><ExecuteItem URL="Dial:789"></ExecuteItem></CiscoIPPhoneExecute>';

$client = new Zend_Http_Client('http://172.18.22.32/CGI/Execute');
$client->setMethod(Zend_Http_Client::POST);
$client->setAuth($login, $password);
$client->setParameterPost('XML', $xml);
$client->request();

Here is a possible application: a Firefox extension detects phone numbers on a special page (telephone directory for example). When clicking on phone numbers, it automatically sends an Ajax request with the instruction to dial the number. Note that cross-domain Ajax requests are authorized within Firefox extensions, it will not work from a web page.

Now that we know the main CiscoIPPhone objects, we can build our own services for the cisco.

Sources

• Cisco Unified IP Phone Service Application Development Notes
• Cisco::IPPhone