Content
Via HTTP
Snom Phones of the serie D3XX and D7XX can be controlled via HTTP requests. This feature is not supported for D8XXÂ
Syntax
The URL to press one or more keys is the address of your phone with the page ’command.htm’ and the post value "key=KEYEVENT":Â
http://phoneIP/command.htm?key=KEYEVENT[;KEYEVENT]
KEYEVENTs are separated by a semicolon from each other. KEYEVENT contains the following values:
KEYEVENT = Key[,Time[,Pause]]
Whereas Key  is the key to be pressed. Time  is the amount in milliseconds that a key is to be pressed (this way real key presses can be simulated, or a long press of a key can be achieved). Pause  is the time in milliseconds that shall elapse between key presses (when the command contains more than one KEYEVENT). The values Time  and Pause  are optional.
If HTTP user name  and HTTP password  are enabled, the request must contain the credentials:
http://username:password@192.168.0.1/command.htm?key=KEYEVENT
Keyevents for Snom Deskphones
- CANCEL = "Cancel" key pressed, e.g. a call can be terminated
- ENTER = " Enter" key pressed
- OFFHOOK = simulates lifting up the handset
- ONHOOK = simulates hanging up the handset
- RIGHT = simulates pressing right navigation key
- LEFT = simulates pressing left navigation key
- UP = simulates pressing "up" navigation key
- DOWN = simulates pressing "down" navigation key
- VOLUME_UP = increases volume in active audio mode (handset / speaker / headset)
- VOLUME_DOWN = reduces volume in active audio mode (handset / speaker / headset)
- MENU = simulates pressing MENU key (not used in FW 7 anymore)
- MUTE = simulates pressing MUTE key
- REDIAL = simulates pressing REDIAL key
- DND = simulates pressing DND key
- REC = simulates pressing Record key
F1, F2, F3, F4 = simulates pressing context sensitive soft function keys (located directly below the display of the phone)
NOTE: snom 190/200 have no key F4 and snom870 no key F1-F4- SPEAKER = simulates pressing SPEAKER key
- HEADSET = simulates pressing HEADSET key
- TRANSFER = simulates pressing TRANSFER key F_HOLD = simulates pressing HOLD key (Before firmware version 8.7.3.7: F_R) 0-9, *, # = simulates pressing the alphanumeric keypadNOTE: with some browsers for # and * you might need to use the ASCII code. For example %23 instead of #, %2A instead of *
- P1-PX = simulates pressing free programmable function keys (X=15 for snom870, X=12 for snom320/360/370/820, X=4 for snom300).
- EK0- EKmax =Â simulates pressing free programmable function keys of expansion module. Note: expansion module Only for snom3xx.
Other keyevents
- Remote Dialing: http://phoneIP/command.htm?number=NUMBER&outgoing_uri=URI
- Remote DTMF tones: http://phoneIP/command.htm?key_dtmf=NUMBER
- Remote End all ongoing calls: http://phoneIP/command.htm?RELEASE_ALL_CALLS
- Remote Logoff all identities: http://phoneIP/command.htm?LOGOFFALL
- Remote Logoff a specific identity: http://phoneIP/command.htm?LOGOFFLINE=1(..12)
- Remote Reregister a specific identity: http://phoneIP/dummy.htm?REREGISTER=1(..12)
- Remote Ringtone Playing: http://phoneIP/line_login.htm?PLAY_RINGER:X=+Ringer(X=1..9)
- Remote Reboot: http://phoneIP/advanced_update.htm?reboot=Reboot
- Remote Reset: http://phoneIP/advanced_update.htm?reset=Reset
- Remote Reset of Dialed Numbers: http://phoneIP/index.htm?dialeddel=clear
- Remote Reset of Missed Calls: http://phoneIP/index.htm?misseddel=clear
- Remote Reset of Received Calls: http://phoneIP/index.htm?receiveddel=clear
- Remote Firmware Upgrade: https://phoneIP/dummy.htm?swload=load&firmware=firmwareURL
- Fix the line-info-layer for screen.bmp (820/21): http://phoneIP/command.htm?FIX_LIL=true
Snom 870 (Touch)
Since versions 8.4.34 and 8.7.2 you can also emulate pressing the touchscreen of the snom870.
XÂ must be between 0 and 479, where 0 is the left display edge and 479 the right one.YÂ must be between 0 and 271, where 0 is the upper display edge and 271 the lower one.
- just press, dont release: http://phoneIP/command.htm?touch=X Y
- press brief version: http://phoneIP/command.htm?touch=X Y p
- release when formerly pressed: http://phoneIP/command.htm?touch=X Y
- release brief version: http://phoneIP/command.htm?touch=X Y r
- press and release with one cmd: http://phoneIP/command.htm?touch=X Y pr
- brief version: http://phoneIP/command.htm?touch=X Y
- chained commands: http://phoneIP/command.htm?touch=X Y pr X2 Y2 pr X3 Y3 pr
Examples
- http://192.168.0.1/command.htm?key=OFFHOOK Â simulates the user of the phone with the IP address 192.168.0.1Â picking up the handset.
- http://192.168.0.1/command.htm?number=12345678&outgoing_uri=123@domain1 Â will dial 1234. In order to place a call from a specific outgoing line (SIP account, identity) attach "&outgoing_uri=user@domain1"
- http://192.168.0.1/line_login.htm?PLAY_RINGER:9=Play+Ringer  plays the ring tone 9 remotely
- http://192.168.0.1/command.htm?key_dtmf=1234 Â will send DTMF tones 1234Â (only available during an active call)
- http://192.168.0.1/dummy.htm?swload=load&firmware=http://my.provisioning.server.com/download/fw/snom821-8.4.35-SIP-r.bin  will upgrade the phone with the URL passed via firmware variable
Attended Transfer (Incoming call A, transferred by B to C):
- http://192.168.6.252/command.htm?key=F_HOLD --> Holds the call "A"
- http://192.168.6.252/command.htm?key=X (X=0-9) --> Repeat this for each digit of the number "C" to be transferred to
- http://192.168.6.252/command.htm?key=ENTER --> "B" makes a call to "C" and announces transfer
http://192.168.6.252/command.htm?key=TRANSFER --> call is transferred
NOTE: If the parameter "Call Join on Xfer (2 calls)" has been set to "ON" the "Calls on Hold" list is displayed instead (in this remote scenario not recommended, since it would require navigation through the list and a final command http://192.168.6.252/command.htm?key=TRANSFER/ENTER)
Via SIP
Alert Info Header
By sending an INVITE request to the phone which gets automatically answered. Most PBX can be configured to handle CTI Integration by just calling the phone. E.g. If I click in a software client "call 1004" the PBX will send anINVITE to the phone and the phone will automatically answer. After the answer the pbx will send the request to the callee. The phone basically does not need any special implementation
Configuration
On the receiving phone(s): Configure the setting "Answer After Policy" via Provisioning or Web User Interface
Usage
The incoming INVITE message will contain the "Alert-Info" Header
Alert-Info: <http://www.notused.com>;info=alert-autoanswer;delay=0"
If Answer After Policy is correctly defined the phone will go offhook and can receive any RE-INVITE to connect to the expected participant.
Event Header Talk, Hold (Broadsoft)
Our phones support a specific Event Header in a SIP Notify supported by Broadsoft. Instead of using alert-info header for going offhook a specific event: talk can be used to force offhook. The hold event then is triggering the same for "Hold" but the phone will send the Hold by itself. This is important for the feature "line toggling" as the phone will unhold the call by itself.
Usage:
In the Allow-Events of a SIP message the support is indicated
Allow-Events:hold,talk
and the a NOTIFY is sent to the phone with eitherÂ
Event: talk
or
Event: hold
The phone will then trigger an according action.
CSTA
There are several ways to remote control the phone via the CSTA Protocol
- Versions starting from 7.3.4 till < 8.7 support CSTA via HTTP only
- Versions since 8.7.1 support uaCSTA (via SIP) but have broken HTTP-CSTA until 8.7.3
- Versions since 8.7.3 support CSTA via HTTP and uaCSTA (via SIP)
Snom phones always use CompoundCallState when reporting a callState.
Snom phones always use and expect sip-uris as deviceIDs. Alternatively (since 8.7.4) you may also use the index (1..12) when referring to an identity registered on the phone in most services.
CSTA via HTTP
Here is a link of all CSTA requests that can be sent to the Snom phone via HTTP: CSTA over HTTP - Requests .
CSTA Events and Action URL
Our CSTA via HTTP implementation does not support Events at the moment. Event Notification must be done with Action URLs. Therefore, we have added a new runtime variable $csta_id as an action url parameter e.g.:
Additionally, you can still send the $call-id too if you need it for something else. In the XML messages you need to send the $csta_id. This value should be used whenever you see a ConnectionID type in CSTA commands described in the CSTA document.
E.g. AnswerCall specification looks like:
<xsd:element name="AnswerCall"> <xsd:complexType> <xsd:sequence> <xsd:element name="callToBeAnswered" type="csta:ConnectionID"/> <xsd:element ref="csta:correlatorData" minOccurs="0"/> <xsd:element ref="csta:userData" minOccurs="0"/> <xsd:element ref="csta:extensions" minOccurs="0"/> </xsd:sequence> </xsd:complexType> </xsd:element>
with
<xsd:complexType name="ConnectionID"> <xsd:choice> <xsd:element name="deviceID" type="csta:LocalDeviceID"/> <xsd:sequence> <xsd:element name="callID" type="csta:CallID"/> <xsd:element name="deviceID" type="csta:LocalDeviceID" minOccurs="0"/> </xsd:sequence> </xsd:choice> </xsd:complexType>
callToBeAnswered should use the value returned by $csta_id through action url, lets assume thats -18, the request would thus look like this:
<csta:AnswerCall> <csta:callToBeAnswered> <csta:callID>-18</csta:callID> </csta:callToBeAnswered> </csta:AnswerCall>
The above semantic is to be used when dealing with firmwares of Version 8.7.3 or higher. 8.7-Versions before 8.7.3 do not support CSTA via HTTP. With Versions before 8.7 or when csta_legacy_control is set to 0 the following semantic would be correct:
<csta:AnswerCall> <csta:callToBeAnswered>-18</csta:callToBeAnswered> </csta:AnswerCall>
The same holds for most other commands mentioned in the templates section below.
Responses from the phone
In case the request was processed successfully the phone will answer with a "HTTP/1.1 200 Ok". The body will differ slightly in the different versions.
<?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <csta:AnswerCallResponse xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed5"/> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<?xml version="1.0" encoding="utf-8"?> <AnswerCallResponse xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed5"/>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:AnswerCallResponse></csta:AnswerCallResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
In case of an error we'll answer with an "HTTP/1.1 500 Internal Server Error" and a body like this (again slightly different with the different implentations):
<?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <SOAP-ENV:faultcode>Client</SOAP-ENV:faultcode> <SOAP-ENV:faultstring>CSTA Error</SOAP-ENV:faultstring> <SOAP-ENV:detail> <csta:CSTAErrorCode xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed5"> <csta:operation>invalidCallID</csta:operation> </csta:CSTAErrorCode> </SOAP-ENV:detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<?xml version="1.0" encoding="utf-8"?> <CSTAErrorCode xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed5"> <operation>invalidCallID</csta:operation> </CSTAErrorCode>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <SOAP-ENV:faultcode>Client</SOAP-ENV:faultcode> <SOAP-ENV:faultstring>CSTA Error</SOAP-ENV:faultstring> <SOAP-ENV:detail> <csta:CSTAErrorCode xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <csta:operation>Invalid CallID</csta:operation> </csta:CSTAErrorCode> </SOAP-ENV:detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
How to post it to the phone
HTTP-POST to: http://<ip-of-phone>/csta.
The content-type should be text/xml.
POST /csta HTTP/1.1 User-Agent: curl/7.18.0 (i486-pc-linux-gnu) libcurl/7.18.0 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.1 Host: 192.168.11.253 Accept: */* Content-Length: 343 Content-Type: text/xml ... <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:AnswerCall> <csta:callToBeAnswered>-2</csta:callToBeAnswered> </csta:AnswerCall> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Proprietary CSTA Messages and Action URLs
We have introduced proprietary CSTA messages to set and get the values of settings, to post an action url and to push and xml document to the phone. The message exchange follows the mechanism that is already in place. The phone replies with a 200 OK or error messages. In the following examples we show only the 200 OK reply of the phone.
Set and Get Setting Values
A CTI Application needs to change certain settings.
The following messages are used to get and set the values of all settings shown in this list:
Only the following settings can be read or changed using the above messages*
- mac (only readable) - phone_type (only readable) - firmware_version (only readable) - user_nameN - user_realnameN - user_hostN - action_incoming_url - action_outgoing_url - action_connected_url - action_disconnected_url - action_hold - action_unhold - action_transfer - action_blind_transfer - action_attended_transfer - action_offhook_url - action_onhook_url - action_missed_url - firmware_version (only readable)CTI Application => Phone<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:GetSettings> </csta:GetSettings> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Phone => CTI Application<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:GetSettingsResponse> <csta:Setting> <csta:name> Name of the Setting </csta:name> <csta:value> Value of the setting </csta:value> </csta:Setting> <csta:Setting> <csta:name> Name of the Setting </csta:name> <csta:value> Value of the setting </csta:value> </csta:Setting> ... All settings in the above list. </csta:GetSettingsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
The following messages are used to set the values of settings:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:SetSettings> <csta:Setting> <csta:name> Name of the Setting </csta:name> <csta:value> Value of the setting </csta:value> </csta:Setting> <csta:Setting> <csta:name> Name of the Setting </csta:name> <csta:value> Value of the setting </csta:value> </csta:Setting> ... Possibly all settings in the above list, but at least one setting. </csta:SetSettings> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:SetSettingsResponse> </csta:SetSettingsResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Pushing of XML Minibrowser Documents
During an incoming call a CTI Application is informed about the call via action urls. The CTI Application looks up contact details of the caller. We want to introduce a feature so that the CTI Application can show contact details or other information for the contact on the phone. We will do this with XML documents for the minibrowser. This mechanism is extremely flexible and CTI Applications can show any kind of information. Therefor we need a CSTA message to push an XML document to the phone. The phone will display the XML document with the minibrowser upon reception.
The following messages are used to send the XML document:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:XmlPush> <csta:document> "XML Document as a String in Quotes" </csta:document> </csta:XmlPush> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:XmlPushResponse> </csta:XmlPushResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Firewall Test
CTI Application needs a way to detect whether a firewall is running on a PC and prevents the reception of fired action urls. In order to detect this we add a new action url called *Firewall Test (action_fwtest_url)*. This action url is hidden and can not be set using the web interface. It will be set by a CTI Application via a SetSettings CSTA message.
CTI Application can trigger the firing of the action url *Firewall Test* by sending a CSTA message.
The following messages are used to trigger the phone to fire the action url:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:FireTest> </csta:FireTest> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed4"> <SOAP-ENV:Body> <csta:FireTestResponse> </csta:FireTestResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
uaCSTA via SIP
usCSTA uses SIP as Transport layer and is explained in detail in [1]
Snom phones support the following requests/events: uaCSTA over SIP - Requests and Events
SIP NOTIFY using Minibrowser SyntaxÂ
Snom phones support the Minibrowser Extension with SIP NOTIFY (available since version 10.1.82.0).
This feature has the same syntax, as any Minibrowser XML which is used all accross the phone. It's not mandatory but for a seamless remote control user experience we recommend to use the SnomIPPhoneSilent minibrowser tag.
Further Information
Related articles
-
CSTA over HTTP - Requests (Snom Service Hub)
-
Remote phone control (Snom Service Hub)
-
uaCSTA over SIP - Requests and Events (Snom Service Hub)
-
Via SIP NOTIFY (Snom Service Hub)