Category/CSTA/HTTP

From Snom User Wiki

Jump to: navigation, search

Our phones always use CompoundCallState when reporting a callState.

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

Our phones support the following requests send to the phone via HTTP:

  1. RequestSystemStatus
  2. SnapshotDevice
  3. MakeCall, find example here (since 8.7.3) or here (before 8.7)
  4. ConsultationCall (since 8.7.4)
  5. AnswerCall, find example here (since 8.7.3) or here (before 8.7)
  6. ClearConnection, find example here (since 8.7.3) or here (before 8.7)
  7. ClearCall
  8. HoldCall, find example here (since 8.7.3) or here (before 8.7)
  9. RetrieveCall, find example here (since 8.7.3) or here (before 8.7)
  10. ConferenceCall
  11. TransferCall, find example here (since 8.7.3) or here (before 8.7)
  12. SingleStepTransferCall, find example here (since 8.7.4) or here (before 8.7.4)
  13. DeflectCall (since 8.7.4)
  14. GenerateDigits (since 8.7.3)
  15. GetSwitchingFunctionDevices
  16. GetDoNotDisturb (since 8.7.4)
  17. SetDoNotDisturb (since 8.7.4)
  18. GetForwarding (since 8.7.4)
  19. SetForwarding (since 8.7.4)

Detailed Description for these requests can be found in the CSTA standard document [1].

CSTA via HTTP additionally supports the requests described in 4 Proprietary CSTA Messages and Action URLs

CSTA via HTTP used to require the csta-xml to be enveloped in SOAP, since 8.7.3 this is no longer necessary except for the proprietary requests described in 4 Proprietary CSTA Messages and Action URLs and for ClearCall. For all other services this is now optional.


Contents

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>
Personal tools
Interoperability