NAME

Polycom::App::Push - Module for sending push requests to Polycom's SoundPoint IP and VVX series VoIP phones

SYNOPSIS

  use Polycom::App::Push;

  my $phone = Polycom::App::Push->new(address => '172.23.8.100', username => 'Bob', password => '1234');

  # Send a simple XHTML message to a Polycom phone that will pop-up on the screen
  $phone->push_message({priority => 'normal', data => '<h1>Fire drill at 2:00pm!</h1>'});

  # Request that the phone show the specified web page, relative to the URL specified in the "apps.push.serverRootURL" configuration parameter
  $phone->push_message({priority => 'critical', url => '/announcement.xhtml'});

  # Request that the phone execute the specified internal URI, or prompt the user to dial the specified "tel:" or "sip:" URI
  $phone->push_message({priority => 'critical', uri_data => 'sip:172.23.8.100'});

DESCRIPTION

The Polycom::App::Push class is for writing web applications for Polycom's SoundPoint IP and VVX series VoIP phones. It provides a mechanism to push messages to a phone for display to the user.

Note that to use the push_message method, the phone must be configured with the following parameters, where the values of each parameters should be customized based on your requirements:

   <apps
     apps.push.messageType="5"
     apps.push.serverRootURL="http://192.168.1.11"
     apps.push.username="Polycom"
     apps.push.password="456" />

The value of the 'apps.push.messageType' parameter is very important, because it determines how the phone will filter incoming push messages based on their 'priority' attributes. The allowable values for the 'apps.push.messageType' parameter are:

   0 - Don't show any push messages
   1 - Show messages with 'priority="normal"'
   2 - Show messages with 'priority="important"'
   3 - Show messages with 'priority="high"'
   4 - Show messages with 'priority="critical"'
   5 - Show all messages, regardless of their 'priority' value

The 'apps.push.serverRootURL' parameter is used as the base URL for the relative URL passed to 'push_message' method in its 'url' parameter.

The 'apps.push.username' and 'apps.push.password' parameters must match the 'username' and 'password' parameters passed to the 'push_message' method.

CONSTRUCTOR

new ( %fields )

  use Polycom::App::Push;
  my $phone = Polycom::App::Push->new(address => '172.23.8.100', username => 'Polycom', password => '456');

Returns a newly created Polycom::App object. The following parameters are required:

  address   - the IP address of the phone.
  username  - the user name configured on the phone with the "apps.push.username" parameter.
  password  - the password configured on the phone with the "apps.push.password" parameter.

ACCESSORS

address

  my $ip_address = $phone->address
  $phone->address('172.23.8.100');  # Set the address to "172.23.8.100"

username

  my $username = $phone->username;
  $phone->username('Bob');  # Set the username to 'Bob'

password

  my $password = $phone->password;
  $phone->password('1234');  # Set the password to '1234'

METHODS

push_message

  if (!$phone->push_message({priority => "critical", url => "/announcements/happy_birthday.xhtml"});)
  {
      print "Failed to send push message\n";
  }

This method can be used to send a push request to a Polycom IP phone that will trigger it to display the supplied message or URL in its web browser. The following parameters are supported:

  priority  - the priority of the message (either "critical" or "normal"). If not specified, "normal" is assumed.
  url       - the URL to display on the phone, relative to the "apps.push.serverRootURL" configuration parameter.
  data      - a URI-escaped HTML document to display on the phone.
  uri_data  - an internal URI to execute, or a "sip:" or "tel:" URI to prompt the user to dial 

Note that either url or data must be specified, but not both. Returns 1 if the message was sent successfully, or 0 otherwise.

SEE ALSO

Developer's Guide SoundPoint IP / SoundStation IP - http://support.polycom.com/global/documents/support/setup_maintenance/products/voice/Web_Application_Developers_Guide_SIP_3_1.pdf

Polycom(R) UC Software Administrator's Guide - http://support.polycom.com/global/documents/support/setup_maintenance/products/voice/spip_ssip_vvx_Admin_Guide_UCS_v4_0_0.pdf

Polycom::App::URI - A module that can be used to generate XHTML documents for displaying custom softkeys and hyperlinks using internal URIs for Polycom phones.

AUTHOR

Zachary Blair, <zblair@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Zachary Blair

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Polycom::App::Push

perl -MCPAN -e shell
install Polycom::App::Push