Welcome!

This manual provides a comprehensive overview of the CTI API and its functions. The CTI API is continuously being developed to meet the changing requirements and expectations of our customers. 

Please send an email to integration@nfon.com to stay up to date with developments and any 'breaking changes'.

Subject to change
Version 2 / 08/2025 (EN)

Die CTI API erweitert den NFON-Dienst "Telefonsystem" um eine leistungsstarke Schnittstelle zur Unterstützung von CTI (Computer Telephony Integration) Aktivitäten. Diese Schnittstelle ermöglicht sowohl PUT, POST als auch GET Befehle direkt über das NFON-Rechenzentrum. Für die Nutzung der CTI API sind die Einrichtung der CTI API sowie die Buchung des Business Premium Tarifs erforderlich.

Die CTI API ermöglicht die optimale individuelle Integration von Cloud Telefonie mit CTIKomfortmerkmalen. Dies führt zu einer signifikanten Verbesserung der Kommunikation und Zusammenarbeit innerhalb des Unternehmens und darüber hinaus.

Dieses Handbuch ergänzt zusätzlich die Dokumentation der OpenAPI Spezifikation.

Die CTI API ist als server-to-server API konzipiert und ermöglicht den Zugriff auf Informationen im Kontext einer Telefonanlage (siehe auch Zugriff und Sicherheit). Die CTI API wird aktuell nur ausgewählten Partnern zur Verfügung gestellt.

Die API credentials können bei vertrieb@nfon.com bzw. auftragsbearbeitung@dt-standard.de beantragt werden. In der E-Mail müssen folgende Informationen enthalten sein:

• K-Anlage

• Ungefähre Anzahl der Nebenstellen

• Ausgefüllte Einwilligungserklärung (die Vorlage finden Sie hier: Vorlage Einwilligungserklärung)

• E-Mail-Adresse des Partners, an die Zugangsdaten geschickt werden sollen

• E-Mail-Adresse des Kundenvertreters, der als Verantwortlicher kontaktiert werden kann

Die CTI API ist eine API, die für Server/Server Kommunikation konzipiert wurde. Sie ist mit jedem Device, wie z.B. Hardphone, Softphone oder der Mobile App, kompatibel. Zu den unterstützten Features gehören u.a. Call Control, Call Event streams und Device Management.

Die CTI API wurde entwickelt, um auf Grundlage der API kundenindividuelle Integrationslösungen zu entwickeln. Dazu gehören u.a. die Integration von Drittanwendungen mit z.B. folgenden Features:

• Contact Pop Up
  Bei einem eingehenden Anruf, wird anhand der eingehenden Rufnummer ein CRM-System geöffnet. Dabei kann je nach Kundenanforderung der Kontaktfenster beim Klingeln, nach Entgegennahme des Anrufs oder erst durch eine Aktion (z.B. hotkey) geöffnet werden.

• Contact Preview
  Bei einem eingehenden Anruf erscheint ein Popup, mit dem Namen zu der Rufnummer, der aus einem CRM system ausgelesen wurde. Diese Informationen können noch mit weiteren Informationen aus dem CRM-System, wie z.B. Anzahl offener Tickets angereichert werden.

• Line Status synchronisieren
  Um die Verfügbarkeit von Mitarbeitern transparent darzustellen, kann der Line Status ausgelesen und in einer individuellen Übersicht dargestellt werden. Der NFON Line Status kann ebenfalls noch mit Informationen aus weiteren Kommunikationsanwendungen (MS Teams, Slack) oder Kalendern (MS Office, Google Kalender) angereichert werden.

• Anruf starten/beenden
  Mit CTI API können Anrufe direkt gestartet oder beendet werden. Dies ermöglicht das Starten und Beenden von Anrufen aus CRM-Systemen.

Folgende Anwendungsfälle sind grundsätzlich ebenfalls möglich:

• Action-URL
  Auf Grundlage der CTI API kann „Action URL“ für eingehende Anrufe, angenommene Anrufe und beendete Anrufe entwickelt werden.

• Individuelle Klingeltöne
  Die API kann dazu verwendet werden, um für interne, externe oder VIP-Anrufe dedizierte Klingeltöne zu nutzen. In diesem Fall ist es sinnvoll Cloudya bzw. das entsprechende Device zu muten.

• Call Analytics
  Werden die gestreamten events (siehe „Anruf Details streamen”) gespeichert, können darauf wichtige Informationen ausgelesen werden. Es muss aber beachtet werden, dass bei dem initialen Verbinden der API nicht der Status der einzelnen Nebenstellen übermittelt wird.

Nachfolgend sind die wichtigsten Funktionen aufgelistet:

1. Nebenstellenkonfiguration auslesen “Get /extension/phone/data”
   Mit diesem Endpunkt ist es möglich einen Überblick über alle konfigurierten Nebenstellen einer K-Anlage zu erhalten. Das beinhaltet sowohl Nummer als auch der Namen, der der Nebenstelle hinterlegt ist.

2. Line Status auslesen “Get /extensions/phone/states”
   Dieser Endpunkt ermöglicht das Auslesen des Line Status je Nebenstelle. Dadurch kann der jeweilige Verfügbarkeitsstatus je Nebenstelle in Third Party Anwendungen dargestellt werden. Beim erstmaligen Verbinden wird der Status aller konfigurierten Nebenstellen angezeigt.

3. Anruf starten “Post /extensions/phone/calls”
   Dieser Endpunkt initiiert einen Anruf für einer Nebenstelle. Zuerst wird der Anruf bei der A-Rufnummer durchgeführt und nach Annahme wird der Anruf zur B-Rufnummer aufgebaut. Welches Endgerät beim Nutzer der A-Rufnummer klingt kann der Nutzer individuell festlegen. Als Return Code wird für diesen Endpunkt eine UUID zurückgegeben, die zum Beenden von Anrufen verwendet werden kann.

4. Anruf beenden “Delete /extensions/phone/calls/{uuid}”
   Beendet einen über die API initiierten Anruf mittels der zurückgegebenen UUID.

5. Anruf Details streamen “Get /extensions/phone/calls”
   Dieser Endpunkt ermöglicht das Streamen aller ein- und ausgehender Telefon-Events einer K-Anlage in Echtzeit. In komplexen Umgebungen sind die Einschränkungen zu berücksichtigen. 
   Beim erstmaligen Verbinden wird, anders als beim Endpunkt zum Auslesen des Line Status (siehe oben),  nicht der aktuelle Status aller Nebenstellen angezeigt.

Mit Hilfe der CTI API kann der Client, um individuelle CTI Features ergänzt werden.

Der CTI-Server hat direkten Zugriff auf die oben genannten Endpunkte im NFON RZ und kann dort Get und Post Befehle ausführen. Ist noch ein Drittanbieter Client im Einsatz fungiert der CTI-Server als Mittelinstanz zwischen diesem Client und dem NFON RZ. Nachdem der CTI-Server im Kontext einer Telefonanlage auf die Daten zugreift, muss im CTI-Server der Zugriff der Daten für den jeweiligen Client sichergestellt werden.

Sicherheit und Datenschutz spielen bei der Nutzung der CTI API eine entscheidende Rolle. Bei den zur Verfügung gestellt Daten handelt es sich um sensible Telekommunikationsdaten, die mit der entsprechenden Professionalität zu verwalten sind.

Die CTI API ermöglicht den Zugriff auf sämtliche Daten im Kontext des K-Accounts. Der Verwender der API trägt die Verantwortung, dass jeder Nutzer nur die Daten erhält, für die dieser berechtigt ist.

Durch regelmäßige Sicherheitsupdates wird sichergestellt, dass alle technischen Komponenten den aktuellen Sicherheitsanforderungen gerecht werden. Der Nutzer der CTI API trägt ebenfalls die

Verantwortung. selbstständig für die Nutzung der Daten entsprechende sicherheitstechnische Vorkehrungen zu treffen.