Snom Service Hub

Content

Page tree


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
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 name, HTTP 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)
  • 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 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

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.

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

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.


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

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

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