Contents

Via HTTP

Phones can be controlled via HTTP requests. 

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

Note: This will not work if you have set Authentication Scheme to "on". "On" means that you are using digest-authentication which just supports the username and password as encrypted (MD5-hash-sum) values and not to be given as clear text in the URI. If you want to use digest-authentification, you have to pass the credentials to the tool which calls the URL or the library you are using for calling the URL, most of the tools/library support this method.

Note: If you have changed HTTP user nameHTTP password and the Administrator Password from the default value, hidden tags have to be disabled in order to use the remote control feature.

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)
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 keypad NOTE: 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/command.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=0
Remote Reset of Missed Calls: http://phoneIP/index.htm?misseddel=0
Remote Reset of Received Calls: http://phoneIP/index.htm?receiveddel=0
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

  1. 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.
  2. 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"
  3. http://192.168.0.1/line_login.htm?PLAY_RINGER:9=Play+Ringer plays  the ring tone 9  remotely
  4. http://192.168.0.1/command.htm?key_dtmf=1234 will send DTMF tones 1234 (only available during an active call)
  5. 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):

  1. http://192.168.6.252/command.htm?key=F_HOLD --> Holds the call "A"
  2. 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
  3. http://192.168.6.252/command.htm?key=ENTER --> "B" makes a call to "C" and announces transfer
  4. 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.

Note: Line Toggline is not possible to manage like this. If a second call comes in and gets answered automatically the phone will put the first on HOLD. There is no way to unhold using a RE-INVITE with sendrecv except using HTTP remote commands/uaCSTA/Event Headers. 

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.

Note: These are not registred with the IANA as event types. It's a private vendor specification.

CSTA

There are several ways to remote control the phone via the CSTA Protocol

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.:

http://192.168.100.100/incoming.php?Caller=$remtote&Callee=$local&csta_id=$csta_id

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.


Resposes 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.

i.e. since 8.7.3:

<?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>

or when request was made without soap-envelope:

<?xml version="1.0" encoding="utf-8"?>
<AnswerCallResponse xmlns:csta="http://www.ecma-international.org/standards/ecma-323/csta/ed5"/>

in versions before 8.7:

<?xml version="1.0" encoding="UTF-8"?>
<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):

since 8.7.3:

<?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>

or when request was made without soap-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>

in versions before 8.7:

<?xml version="1.0" encoding="UTF-8"?>
<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.


Example:

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
...
<?xml version="1.0" encoding="UTF-8"?>
<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
<?xml version="1.0" encoding="UTF-8"?>
<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
<?xml version="1.0" encoding="UTF-8"?>
<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:


CTI Application => Phone
 <?xml version="1.0" encoding="UTF-8"?>
<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>


Phone => CTI Application
<?xml version="1.0" encoding="UTF-8"?>
<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:


CTI Application => Phone
<?xml version="1.0" encoding="UTF-8"?>
<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>
Phone => CTI Application
<?xml version="1.0" encoding="UTF-8"?>
 <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:


CTI Application => Phone
<?xml version="1.0" encoding="UTF-8"?>
<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>


Phone => CTI Application
<?xml version="1.0" encoding="UTF-8"?>
<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



Related Links:

There is no content with the specified labels