[FAQ] Can I remotely control the Phone or send content to the Phone / CTI?

[SteffenBaierUK]

uaCSTA:

Partial Support for this was added in UC Software 5.8.0 or later. For more details on what exactly is supported is documented in the 5.8.0 Admin Guide and for additional information contact a Polycom Sales Engineer or Polycom support quoting EN-64922

NOTE:

• UC Software 5.3.0 changed the Web Interface to HTTPS only as explained => here <=

The following is to be enabled if CURL via HTTP is being used:

apps.push.secureTunnelRequired="0"

Example file to => import <= is attached.

REST API

A more modern approach to the below PUSh functionality using the built in REST API => here <=

3rd Party Tools

Using an external Tool like Device Operator Console >here< (by a Poly employee)

NOTE: For CCX Phones full functionality is only given when using this in openSIP or Skype base Profile. For Microsoft Teams or Zoom Room only the screen can be seen but not controlled!

PUSH server control

The <apps/> parameter section can be used to utilize the push server control of the Phone.

Various scenarios like dialling a number or activating/disabling features or even simply displaying a message on the Phone's micro browser can be used with below.

Note: Please be aware that utilizing this functionality can allow the control of the Phone and the standard Web Interface username and password should be changed to prevent third parties access to the phone!

Note: The below examples are based on UCS 4.0.0 or later and earlier SIP or UCS Version may not be fully compatible or limited with the below example.

Prerequisite:

• Please check the relevant support Page => here <= matching your Phone model in order to download the latest Web Application Developer’s Guide
  
  
• Please check download the relevant SIP / UCS Admin Guide => here <= matching your Phone model

The Push functionality can be enabled via the Web Interface Settings => Applications => Push

A basic configuration should be set to allow “All" Push Messages and add a “User Name” and “Password” 

The Feature can also be enabled using => provisioning <= via:

<WEB apps.push.messageType="5" apps.push.password="Push" apps.push.username="Push" />

Above set’s the following:

• apps.push.messageType will allow All messages to be passed
• apps.push.username will use the User Name Push
• apps.push.password will use the Password Push

In this demonstration, the curl command is used from a Linux console. Other scripting languages like Java or Python can be utilized in addition.

NOTE: Please bear the formatting when copying & pasting in mind. CR and LF may not be copied correctly!

Please be aware that you may need some additional characters to ensure the formatting is correct. These can be "$" and the " ' " and " ' " apostrophe or simply " \ "

Using Windows and CURL try this => here <=
EDIT: Windows 10 support CURL from an MS-Dos command line

Example:

 
Please note the ASCII code Single quote or Apostrophe before and at the end to escape the string correctly.

Linux (notice the \ before the " 😞

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority=\"All\">Key:Status</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.233.240.107/push

Using HTTPS and Curl:

curl --digest -u Push:Push -d  "<PolycomIPPhone><Data priority='"Critical"'>tel:\\114</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" https://10.252.149.112/push -k

The -k Option is used as the certificate of the phone cannot be verified

*   Trying 10.252.149.109...
* Connected to 10.252.149.109 (10.252.149.109) port 443 (#0)
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: C:\Program Files\cURL\bin\curl-ca-bundle.crt
  CApath: none
* TLSv1.2 (OUT), TLS header, Certificate Status (22):
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.0 (IN), TLS handshake, Server hello (2):
* TLSv1.0 (IN), TLS handshake, Certificate (11):
* TLSv1.0 (OUT), TLS alert, Server hello (2):
* SSL certificate problem: unable to get local issuer certificate
* Closing connection 0
* TLSv1.0 (OUT), TLS alert, Client hello (1):
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle"
 of Certificate Authority (CA) public keys (CA certs). If the default
 bundle file isn't adequate, you can specify an alternate file
 using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
 the bundle, the certificate verification probably failed due to a
 problem with the certificate (it might be expired, or the name might
 not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.

Working Wireshark Trace example:

Error finding:

You can check your Logs for errors as a wrongly formatted URL may cause a 405 Error:

0727140404|push |2|00|wappPushHandlerC::Handle: <PolycomIPPhone><Data priority=All>Key:Status</Data></PolycomIPPhone>
0727140404|push |4|00|PushParserC::parseDoc: Bad document - priority attribute is not proper: <Data priority=All>Key:Status</Data></PolycomIPPhone>

Dialling Numbers

Example 1 simply dialling a number:

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="all">tel:\\3035</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

In above original example the SoundStation IP 560 (10.252.75.219) is send the PUSH message to dial the Phone Number 3035 with the User Name “Push” and the Password “Push” using the “critical” priority.

NOTE: The target IP or Hostname will always need the /push destination!

Example 2 dialing a number specifying Line 2:

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="all">tel:\\3035;line2</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

In the above example the SoundStation IP 560 (10.252.75.219) sends the PUSH message to dial the Phone Number 3035 using Line 2 with the User Name “Push” and the Password “Push” using the “all” priority.

Example 3 dialling a number pause and sending DTMF pause and send DFTM:

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="all">tel:\\8500;postd=p3095,3095</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

In above example the SoundStation IP 560 (10.252.75.219) sends the PUSH message to dial the Phone Number 3095 with the User Name “Push” and the Password “Push” using the “all” priority pause (p) before sending the DTMF digits “3095” once the call is connected and then pausing (,) again before sending the DTMF digits “3095”.

• A two-second pause is indicated by the, (comma). A one-second pause is indicated by a p

[SteffenBaierUK]

NOTE:

• UC Software 5.3.0 changed the Web Interface to HTTPS only as explained => here <=

Controlling the Phone

Example 1 setting the Phones DND status to on or off

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="all">Key:DoNotDisturb</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

In the above example the SoundStation IP 560 (10.252.75.219) sends the PUSH message to use the DoNotDirsturb Key with the User Name “Push” and the Password “Push” using the “all” priority.

NOTE: Even if a Phone does not have the physical Hardware Button the functionality of the action will work.

Example 2 answering an incoming call

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="Critical">Key:Softkey1</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

In the above example the SoundStation IP 560 (10.252.75.219) sends the PUSH message to use the Softkey1 with the User Name “Push” and the Password “Push” using the “critical” priority causing the command to be executed whilst the Phone is in signalling mode.

NOTE: Please be aware that there is currently no simple way to do this on a VVX500 or VVX600!

Example 3 answering an incoming call and transferring the call to another extension and hanging up

curl --digest -u Push:Push -d $'<PolycomIPPhone><Data priority="Critical">Key:Softkey1\nKey:Softkey3\nKey:Dialpad8\nKey:Dialpad5\nKey:Dialpad0\nKey:Dialpad0\nKey:Softkey1\nKey:Handsfree</Data></PolycomIPPhone>' --header "Content-Type: application/x-com-polycom-spipx" 10.252.75.219/push

NOTE: In this example, some additional characters are needed to ensure the \n (Carriage Return / Line Feed) is executed. These are "$" and the " ' " and " ' "

In the above example, the SoundStation IP 560 (10.252.75.219) sends the PUSH message to use the Softkey1 (Answer) to answer the call

It then receives the command to use the Softkey3 (Transfer) to place the call on hold and enable the call to be forwarded to another extension

It then receives multiple Dialpadx commands to dial Extension 8500

It then receives the command to use the Softkey1 (send) to transfer the call

The Final command instructs the Phone to disconnect from the Handsfree call

Example 4 directly accessing the status Menu

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="all">Key:Status</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

Example 5 directly accessing the settings Menu

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="all">Key:Setup</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push

Example 6 reloading a Configuration from the Provisioning Server.

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority="Critical">Action:UpdateConfig</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-polycom-spipx" http://10.252.75.219/push 

Usually the steps Menu > Settings > Basic > Update Configuration to trigger the phone to check for any configuration changes on the Provisioning server.

Above command would just action the Update Request and load any changes and if needed reboot the Phone. This is also described => here <= using other methods

Additional Information:

Another method to send multiple commands is to create a file hosted on a server,

In the above example, the Server hosting the file can be reached on the IP 10.252.75.203

The Sub Directory containing the file is /push

Create a file (called doubleMenu.txt) that contains this:

<PolycomIPPhone><Data priority="Critical">Key:Menu
Key:Menu</Data></PolycomIPPhone>

NOTE: Please ensure to exclude any invisible characters as introducing these will not work porperly with the Carriage Return (CR) and Line Feed (LF)

curl --digest -u Push:Push --data-binary @doubleMenu.txt --header "Content-Type: application/x-com-polycom-spipx" 10.252.75.219/push

Note: The usage of the " @ " enables the file to be located on the same server as the curl command is being executed.

Wireshark Trace of the double command

In above example the Phone will download the doubleMenu.txt  file from http://10.252.75.203/push Directory

Possible Keys for all examples are:

Line1	Line21	Line41	Softkey1	ArrowLeft
Line2	Line22	Line42	Softkey2	ArrowRight
Line3	Line23	Line43	Softkey3	Backspace
Line4	Line24	Line44	Softkey4	Select
Line5	Line25	Line45	Softkey5	Conference
Line6	Line26	Line46	VolDown	Transfer
Line7	Line27	Line47	VolUp	Redial
Line8	Line28	Line48	Headset	Hold
Line9	Line29	Dialpad0	Handsfree	DoNotDisturb
Line10	Line30	Dialpad1	MicMute	Video
Line11	Line31	Dialpad2	Messages	Green
Line12	Line32	Dialpad3	Applications	Red
Line13	Line33	Dialpad4	Directories	Home
Line14	Line34	Dialpad5	Setup	Talk
Line15	Line35	Dialpad6	BasicMenu	BarCode
Line16	Line36	Dialpad7	Status	Back
Line17	Line37	Dialpad8	Call List	Unknown
Line18	Line38	Dialpad9	Menu	efk:
Line19	Line39	DialPadStar	ArrowUp	tel:
Line20	Line40	DialPadPound	ArrowDown

Note: The above is depending on the phone model and software and not all may be supported!

[SteffenBaierUK]

NOTE:

• UC Software 5.3.0 changed the Web Interface to HTTPS only as explained => here <=

Sending HTML Content to a Phone

Example 1 sending a simple HTML page to the Phone to retrieve:

For this example the location of a Directory to submit these files from needs to be specified

This can be done via the Web Interface or a => provisioning <= such as:

<web apps.push.serverRootURL="http://10.252.75.203/push" />

Example HTTP File „fire.html“ located on the Server within the Push subdirectory

<html>
<body>
<h1>Fire Drill at 2pm</h1>
Please exit and congregate at your appropriate location outside
</body>
</html>

The command to be sent to the phone would be

curl --digest -u Push:Push -d "<PolycomIPPhone><URL priority="Critical">/fire.html</URL></PolycomIPPhone>" --header "Content-Type: application/xhtml+xml" http://10.252.75.219/push

Example 2 sending a simple HTML messaged directly to the Phone:

For this example we are sending an HTML message directly to the phone:

curl --digest -u Push:Push -d "<PolycomIPPhone><Data priority='"critical"'><h1> Fire Drill at 2pm </h1>Please exit and congregate at your appropriate location outside</Data></PolycomIPPhone>" --header "Content-Type: application/x-com-Polycom-spipx" https://10.252.149.54/push -k

The above uses HTTPS and therefore using the -k Option is used as the certificate of the phone cannot be verified

Phone Log:

0111103111|push |2|00|wappPushHandlerC::Handle: <PolycomIPPhone><Data priority='critical'><h1> Fire Drill at 2pm </h1>Please exit and congregate at your appropriate location outside</Data></PolycomIPPhone>
0111103111|push |2|00|PushManagerC::processPushObject: <html><h1> Fire Drill at 2pm </h1>Please exit and congregate at your appropriate location outside</html>
0111103112|push |3|00|Data push message is being displayed.

It may be desirable to have an audible notification when such message is arriving.

This can be done via the => provisioning <= such as:

<web apps.push.alertSound="1" />

Simulate a Blind Transfer for a VVX500,501,600 and 601

The above was added in VVX UC Software 5.5.4, 5.6.3, 5.7.2 and 5.8.0 or later

To Answer the Call

curl --digest -u Polycom:456 -d "Key:Softkey1" --header "Content-Type: application/x-com-polycom-spipx" http://<DUT IP Address>/push

To Press Transfer SK

curl --digest -u Polycom:456 -d "Key:Softkey3" --header "Content-Type: application/x-com-polycom-spipx" http://<DUT IP Address>/push

To Press Blind SK

curl --digest -u Polycom:456 -d "Key:Softkey3" --header "Content-Type: application/x-com-polycom-spipx" http://<DUT IP Address>/pus