PROFI Telefonanlage Integrationen & Schnittstellen
Menu

CISCO CTI API

Z6003

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.

Weitere Informationen

Die technische Dokumentation finden Sie in unserer API 2.0 Doku:
https://api.placetel.de/v2/docs/#placetel-api-cti

Sie k├Ânnen die Befehle auch mit einem Swagger Link in ein Programm wie Insomnia oder Postman importieren. Nutzen Sie dazu bitte folgenden Link:
https://api.placetel.de/v2/swagger_doc

Unser Webinar zum Thema CTI API mit Praxisbeispiel



























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.

CISCO CTI API
CISCO CTI API

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.

CISCO CTI API aktivieren

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/settings/api#api_token

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 exisitiert 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.r4r3.me/

  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.r4r3.me/12345",
"phone": true
}'
  1. 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.
  2. 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' \

Bitte beachten Sie! Sollten Sie auch andere Integrationen nutzen, z.B. Zapier k├Ânnen Ihnen hier weitere Endpunkte angezeigt werden. L├Âschen Sie diese nicht!

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.

Direktzugriff

Ticket er├Âffnen Status Kontakt Remote-Support