CISCO CTI API

Die CISCO CTI API Schnittstelle ermöglicht Ihnen die Nutzung unserer REST API zur Steuerung Ihres CISCO Tischtelefons.

Bitte beachten Sie, dass unsere API stetig erweitert wird. Nur die technische Dokumentation stellt den aktuellsten Stand korrekt dar. Dieser Artikel dient nur als Hilfestellung und liefert entsprechende Hintergrundinformationen.

Das Telefon kommuniziert mit einem Websocket Server bei Placetel. Um Ihnen die Anbindung so einfach wie möglich zu gestalten, stellen wir Ihnen eine übersichtliche REST Schnittstelle zur Verfügung um Steuerungsbefehle an das Telefon senden zu können. Events des Telefons erhalten Sie per Webhook an einen Endpunkt, den Sie selber festlegen können. Konfigurationen im Telefon sind nicht notwendig.

Funktionen

Folgende Funktionen bietet die CTI API derzeit an:

• Call Control
  • Dial
  • Dial digit
  • Hangup
  • Answer
  • Decline
  • Hold
  • Resume
  • Start transfer
  • Complete transfer
  • Start conference
  • Complete conference
  • Blind transfer
  • Send DTMF digits
• Konfiguration
  • Set config parameter
  • Get config parameter

Aktivieren der CISCO CTI REST API

Bevor Sie die API Befehle senden können, müssen Sie die CTI API aktivieren. Wechseln Sie dazu in das Placetel Kundenkonto Integrationen → Cisco CTI API und klicken Sie auf Aktivieren.

Starten Sie nun bitte Ihr Telefon neu.

Steuerungsbefehle senden

Die in der API Dokumentation beschriebenen Endpunkte können mit den üblichen Schnittstellen und Programmen angesteuert werden. Die einfachste Variante wäre z.B. ein curl-Befehl.
Jeder Befehl muss im Header folgende Informationen erhalten:

• Content-Type: application/json
• Authorization: API_KEY

Den API Key erhalten Sie in Ihrem Placetel Kundenkonto unter folgendem Link (Sie müssen dafür eingeloggt sein):
https://web.placetel.de/integrations/web_api

Die URL des Aufrufs muss immer die MAC Adresse des zu steuernden Telefons beinhalten.

curl--request POST 'https://api.placetel.de/v2/cti/{{MAC}}/endpunkt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f-...ac2ee9' \
--data-raw '{
    "param1": "string",
    "param2": "string"
    ...
}'

Sie erhalten bei korrekter Syntax immer folgende Rückmeldung:

{
"status": "published"
}

Der eigentliche Inhalt der Responds wird per Webhook zurückgemeldet. Wie Sie diesen abrufen, erfahren Sie im Verlaufe des Artikels unter Events des Telefons erhalten.

Beispiel 1: Nummer wählen und auflegen

Der einfachste Anwendungsfall ist die Wahl einer Rufnummer am Telefon.

Die Anwahl geschieht mit folgenden Parametern:

• Leitung 1
• MAC des Telefons: 8D-05-8B-48-30-5F
• zu wählende Rufnummer: 0221-29191999
• API Token: a2c3a624-ac5f…ac2ee9

curl --request POST 'https://api.placetel.de/v2/cti/8D058B48305F/dial' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw '{
    "line": "1",
    "number": "022129191999"
}'

Das Telefon meldet daraufhin per Webhook zurück:

{"type":"event","params":{"line":1,"callId":0,"callState":"Dialing"},"name":"/api/Call/v1/CallStateChanged","phone_id":XXXXX}

Sie erfahren hiermit die CallID und die genutzte Line. Mit diesen Informationen können Sie das Gespräch jetzt auch wieder auflegen:

curl --request POST 'https://api.placetel.de/v2/cti/8D058B48305F/hangup' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw '{
    "line": "1",
    "call_id": "0"
}'

Beispiel 2: Blind Transfer

Ein „unattended“ oder „blind“ Transfer ist einfach umzusetzen. Im laufenden Gespräch sprechen Sie dazu einfach den Endpunkt /blind_transfer an. Im Body übergeben Sie die Line, auf der das aktuelle Gespräch läuft, die CallID (bei einem einzigen Call i.d.R. 0) und die Nummer, an die Sie vermitteln wollen, in diesem Beispiel die interne Durchwahl 401.

curl --request POST 'https://api.placetel.de/v2/cti/8D058B48305F/blind_transfer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw '{
    "line": "1",
    "call_id": "0",
    "number": "401"
}'

Beispiel 3: Attended Transfer

Ein „attended“ Transfer, also ein Übergeben des Gesprächs mit Rückfrage ist ein bisschen aufwändiger. Hierzu müssen Sie mehrere Endpunkt nacheinander ansprechen:

Zunächst starten Sie den Transfer auf der aktuellen Line und dem aktuellen Call mit /start_transfer

curl --request POST 'https://api.placetel.de/v2/cti/8D058B48305F/start_transfer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw '{
    "line": "1",
    "call_id": "0"
}'

Anschließend wählen Sie die Durchwahl, an die Sie den Call vermitteln möchten. Bitte beachten Sie, dass Sie hier den Endpunkt /dial_digit verwenden müssen, nicht den Endpunkt /dial!
Wählen Sie wieder die Line 1, aber generieren Sie einen neuen Call mit der Call ID 1. Die Durchwahl, an die Sie vermitteln möchten, terminieren Sie bitte mit der Raute (#), dann geht der Wahlprozess schneller.

curl --request POST 'https://api.placetel.de/v2/cti/8D058B48305F/dial_digit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw '{
    "line": "1",
    "call_id": "1",
    "digit": "401#"
}'

Jetzt können Sie Rücksprache halten.
Wenn Sie das Gespräch endgültig übergeben wollen, sprechen Sie den Endpunkt /complete_transfer an.

curl --request POST 'https://api.placetel.de/v2/cti/8D058B48305F/complete_transfer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw '{
    "line": "1",
    "call_id": "1"
}'

Beispiel 4: 3er Konferenz

Der Ablauf für eine 3er Konferenz ist vergleichbar zu einem „attended transfer“, also:

1. start_conference
2. dial_digit
3. complete_conference

Beachten Sie die korrekte Ansprache der Line und CallID.

Konfiguration anpassen und auslesen

Sie können über die API Schnittstelle die Konfiguration des Telefons abfragen und setzen.
Die Parameter entsprechen den Punkten, die Sie in den Config- und Status-Dateien des Telefons finden

Config Datei: https://IP-ADRESSE-DES-TELEFONS/admin/advanced/cfg.xml
Status Datei: https://IP-ADRESSE-DES-TELEFONS/admin/advanced/status.xml

Bitte beachten Sie, dass Sie einen Unterstrich hinter die Parameter setzen müssen, wenn Sie Arrays verwenden (also z.B. ein Parameter öfter existiert und Sie einen bestimmten pro Line auslesen wollen).

Eine kleine Auswahl an Parametern sind:

- Registration_State_1_
- Registration_State_2_
- Erste Nummer CallID, zweite Nummer Line:
    - Call_State_1__1_
    - Peer_Phone_1__1_
    - Peer_Name_1__1_
- Line_1_LED_Color
- Line_2_LED_Cadence
- Ringer_Volume
- Speaker_Volume
- ...

Beachten Sie hierzu auch die Dokumentation der CISCO MPP Remote SDK, auf der unsere CTI API basiert:
https://developer.cisco.com/docs/multiplatform-phones/#!config

Parameter auslesen

Sie können mehrere Status-Parameter des Telefons mit einem API Call auslesen:

 GET .../?params[]=parameter1&params[]=parameter2

Beispiel 1: Registrierung abfragen

Um den Status der Registrierung der ersten beiden Lines eines Telefons auslesen zu können, müssen Sie folgende Parameter abfragen:

- Registration_State_1_
- Registration_State_2_

also

curl --request GET 'https://api.placetel.de/v2/cti/8D058B48305F/?params[]=Registration_State_1_&params[]=Registration_State_2_' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \

Die Webhook Antwort des Telefons lautet beispielsweise:

{"type":"result","result":{"paramvalues":{"Registration_State_1_":"Registered","Registration_State_2_":"Not Registered"},"respcode":0},"success":true,"status":200,"phone_id":XXXXX}

Beispiel 2: Klingellautstärke abfragen

Die Klingellautstärke ist global für alle Lines identisch, die Abfrage erfolgt so:

curl --request GET 'https://api.placetel.de/v2/cti/8D058B48305F/?params[]=Ringer_Volume' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \

Das Telefon meldet:

{"type":"result","result":{"paramvalues":{"Ringer_Volume":"13"},"respcode":0},"success":true,"status":200,"phone_id":XXXXXX}

Beispiel 3: BLF Status abfragen

Sie können derzeit nicht direkt den Status der BLF Tasten abfragen, wohl aber Farbe und Kadenz aller LEDs der eingebauten Funktionstasten:

curl --request GET 'https://api.placetel.de/v2/cti/8D058B48305F/?params[]=Line_1_LED_Color&params[]=Line_1_LED_Cadence' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \

Das Telefon meldet:

{"type":"result","result":{"paramvalues":{"Line_1_LED_Cadence":"Steady","Line_1_LED_Color":"Green"},"respcode":0},"success":true,"status":200,"phone_id":XXXXXX}

Sie können Line_1_LED_Color entsprechend der Tasten hochzählen. Schauen Sie dazu auch in die status.xml für weitere Parameter.

Parameter setzen

Über die API können Sie Parameter im Telefon setzen. Dazu nutzen Sie PUT mit der entsprechenden MAC Adresse.
Bitte beachten Sie, dass die Einstellungen unter Umständen durch die Autoprovisionierung überschrieben werden. Wir empfehlen daher, dauerhafte Settings per benutzerdefnierter Autoprovisionierung festzulegen und nicht über diese API.

Beispiel 1: Lautstärke setzen

Um beispielsweise die Klingellautstärke und Lautsprecherlautstärke zu setzen, nutzen Sie folgenden Befehl. Natürlich können Sie auch nur einen Parameter hinterlegen.
Auch wenn die Klingelautstärke eine Integer-Variable zu sein scheint, muss sie hier als String übergeben werden. Dies gilt für alle Parameter.

curl --request PUT 'https://api.placetel.de/v2/cti/8D058B48305F' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f...ac2ee9' \
--data-raw ' {
 "params": {
    "Ringer_Volume": "11",
    "Speaker_Volume": "6"
  }
}'

Events des Telefons erhalten

Allgemein

Um Antworten des Telefons zu erhalten um z.B. über einen eingehenden Anruf benachrichtigt zu werden, müssen Sie einen Endpunkt für Webhooks registrieren. Verwenden Sie den Endpunkt /subscriptions um Ihren persönlichen Webhook-Endpunkt anzulegen oder zu löschen. Anschließend werden Ihnen Events aller CISCO Telefone in Ihrem Kundenkonto an diese Adresse zugestellt. Sie können die verschiedenen Nachrichten anhand der Device ID unterscheiden. Welche Device ID zu welchem Endgerät gehört können Sie mit dem Endpunkt /devices abfragen.

Beispiel 1: Registrierung am Webhook Service

Zur Verdeutlichung erfolgt hier ein Praxisbeispiel für die Registrierung Ihres Webhook Endpunktes.
Sofern Sie keinen eigenen Endpunkt in Ihrer Software haben und die Events dennoch testweise empfangen möchten, können Sie einen kostenfreien Dienst dafür nutzen. Folgender Dienst dient hier als Beispiel, es besteht kein Zusammenhang zwischen Placetel und dem Diensteanbieter.
https://requestbin.com/

1. Legen Sie ein RequestBin an. Wählen Sie unbedingt „private“ um zu verhindern, dass Unbefugte Ihre Events abgreifen können.
2. Führen Sie einen API Call auf den Endpunkt /subscriptions durch. Ersetzen Sie die URL durch die Bin URL Ihres eben erstellten RequestBins.

curl --request PUT 'https://api.placetel.de/v2/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f-...ac2ee9' \
--data-raw '{
"service": "ciscocti",
"url": "https://requestbin.com/12345",
"phone": true
}'

3. Sie erhalten eine Response mit der ID Ihres angelegten Endpunkts, z. B. „id“: „ciscocti-52582113431b“. Speichern Sie die ID, diese wird benötigt um den Endpunkt später wieder abmelden zu können. Sie können sie aber auch später erneut abfragen.
4. Sie erhalten jetzt bereits die Events des Telefons als Webhook an Ihr RequestBin, z.B. wenn das Telefon klingelt

{"type":"event","params":{"line":1,"callId":0,"callState":"Ringing"},"name":"/api/Call/v1/CallStateChanged","phone_id":XXXXXX}

Bitte beachten Sie: Die gesandten Events werden nicht von Placetel übermittelt sondern kommen direkt aus dem Telefon. Wir können Ihnen derzeit keine vollständige Liste aller möglichen Events zur Verfügung stellen.

Beispiel 2: Abmelden am Webhook Service

Wenn Sie den Endpunkt wieder abmelden wollen, nutzen Sie folgenden Aufruf:

curl --request DELETE 'https://api.placetel.de/v2/subscriptions/ciscocti-52582113431b' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f-...ac2ee9' \

Beispiel 3: Webhook Registrierungen ausgeben

Sie können sich alle aktiven Webhook Subscrptions ausgeben lassen. Verwenden Sie dafür:

curl --request GET 'https://api.placetel.de/v2/subscriptions/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f-...ac2ee9' \

Beispiel 4: Eingehende Rufnummer auslesen

Wenn Sie einen eingehenden Anruf signalisiert bekommen, erhalten Sie im Event nicht die Rufnummer des Anrufers übertragen. Dazu müssen Sie mit der korrekten CallID den Endpunkt Get Params ansprechen:

Sie erhalten folgendes Event:

{"type":"event","params":{"line":1,"callId":0,"callState":"Ringing"},"name":"/api/Call/v1/CallStateChanged","phone_id":XXXXXX}

Daraufhin sprechen Sie folgenden Endpunkt mit dem Parameter Peer_Phone_1__1_ an:

curl --request GET 'https://api.placetel.de/v2/cti/8D058B48305F/?params[]=Peer_Phone_1__1_' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer a2c3a624-ac5f-...ac2ee9' \

Das Telefon schickt ein Event mit der Nummer des Anrufers:

{"type":"result","result":{"paramvalues":{"Peer_Phone_1__1_":"02211234567"},"respcode":0},"success":true,"status":200,"phone_id":XXXXXX}

Achtung: Sie müssen hier Peer_Phone_1__1_ abrufen, obwohl laut Event eigentlich Peer_Phone_1__0_ folgerichtig wäre. Die CallID beginnt an der Stelle also nicht bei 0 sondern bei 1. Möglicherweise wird dies in einem künftigen Firmware Update verändert.