Skip to main content

3CX TAPI – Installation und Einrichtung unter Windows

1. Allgemeine Informationen

Mit dem 3CX TAPI Service Provider können TAPI-fähige Anwendungen, beispielsweise CRM-Systeme, mit einer 3CX-Telefonanlage verbunden werden. Dadurch lassen sich Anrufe über die jeweilige Nebenstelle steuern.

Diese Anleitung beschreibt die Installation, Konfiguration und Fehleranalyse des 3CX TAPI Service Providers unter Windows in Verbindung mit dem separaten 3CX-TAPI-Server.

Voraussetzungen:

  • 3CX-Telefonanlage

  • Installierter und konfigurierter 3CX-TAPI-Server

  • Windows-PC mit Administratorrechten für die Installation

  • TAPI-Client-Installationsdatei 3cxTsp.exe

  • Netzwerkverbindung zwischen Windows-PC und TAPI-Server

  • Freigeschaltete Nebenstelle auf dem TAPI-Server

2. TAPI-Server prüfen

Vor der Einrichtung des Windows-Clients muss sichergestellt werden, dass der TAPI-Server auf dem 3CX-Host installiert und erreichbar ist.

2.1 Dienststatus prüfen

Auf dem Linux-Server folgenden Befehl ausführen:

sudo systemctl status 3cxtapiserver --no-pager

Befehlstyp: LESEND

Der Dienst sollte den Status active (running) besitzen.

Falls der Dienst nicht vorhanden ist, muss zunächst die Installation des TAPI-Serverpakets geprüft werden.

2.2 Netzwerkports prüfen

sudo ss -lntp | grep -E ':(8888|9998|9999)\b'

Befehlstyp: LESEND

Standardmäßig verwendet der TAPI-Server folgende Ports:

Port Funktion
TCP 8888 HTTP-Schnittstelle und TSP-Verbindung
TCP 9999 WebSocket
TCP 9998 Secure WebSocket

Die tatsächlich verwendeten Ports können von diesen Standardwerten abweichen.

Auswertung:

  • 0.0.0.0:8888 – Der Dienst lauscht auf allen IPv4-Adressen.

  • 127.0.0.1:8888 – Der Dienst lauscht ausschließlich lokal.

  • <SERVER-IP>:8888 – Der Dienst lauscht auf der angegebenen IP-Adresse.

  • Keine Ausgabe – Auf Port 8888 lauscht kein TCP-Dienst.

Ein lauschender Port bestätigt nicht automatisch die Erreichbarkeit von anderen Geräten.

2.3 Serverkonfiguration prüfen

Die Konfigurationsdatei befindet sich laut Herstelleranleitung unter:

/usr/lib/3cxtapiserver/3cxtapisrv.xml

Die relevanten Einstellungen können mit folgendem Befehl angezeigt werden:

sudo grep -E '<(extension|http|ws|wss|authenticate)' /usr/lib/3cxtapiserver/3cxtapisrv.xml

Befehlstyp: LESEND

Die Ausgabe kann interne Konfigurationsinformationen enthalten und sollte vor einer Weitergabe geprüft werden.

Beispiel:

<tapisrv>
  <extensions>
    <extension>10</extension>
    <extension>11</extension>
  </extensions>
  <http port="8888" ssl="0"/>
  <ws port="9999"/>
  <wss port="9998"/>
</tapisrv>

Die benötigte Nebenstelle muss auf dem TAPI-Server eingetragen sein.

3. Installation auf dem Windows-PC

3.1 TAPI-Treiber installieren

  1. Installationsdatei 3cxTsp.exe mit Administratorrechten ausführen.

  2. Installation abschließen.

  3. Win + R drücken.

  4. Folgenden Befehl eingeben:

control.exe telephon.cpl

  1. Das Fenster Telefon und Modem öffnen.

3.2 Windows-Standortinformationen einrichten

Beim ersten Öffnen erscheint gegebenenfalls die Standortkonfiguration.

Folgende Angaben hinterlegen:

Einstellung Wert
Land/Region Deutschland
Ortskennzahl Lokale Ortsvorwahl ohne führende 0
Netzkennzahl Leer lassen, sofern nicht benötigt
Amtskennziffer Entsprechend der Telefonie-Konfiguration
Wählverfahren MFV (Ton)

Die Ortskennzahl ist nicht mit der 3CX-Nebenstellennummer zu verwechseln.

Die tatsächlichen Wählregeln müssen zur eingesetzten Telefonie-Anwendung passen.

4. TAPI-Nebenstelle konfigurieren

  1. Im Fenster Telefon und Modem den Reiter Erweitert öffnen.

  2. Auf Hinzufügen klicken.

  3. 3CX Tapi Service Provider auswählen.

  4. Den Konfigurationsdialog öffnen.

Hinweis: Der 3CX Tapi Service Provider ist nicht mit dem 3CX TAPI Multi-Line Service Provider gleichzusetzen. Diese Anleitung bezieht sich auf den separaten TAPI-Server des Drittanbieters.

4.1 Verbindungsdaten eintragen

Feld Beschreibung
Nebenstelle 3CX-Nebenstellennummer des Mitarbeiters
Server IP-Adresse oder FQDN des TAPI-Servers
Port Standardmäßig 8888
Schlüssel Entsprechend der Serverkonfiguration
Globaler Schlüssel Systemschlüssel bei aktivierter Client-Authentifizierung
SSL verwenden Entsprechend der SSL-Konfiguration des Servers
Erweiterte Leitungsnamen Optionale Einstellung

Beispiel:

Nebenstelle: 10
Server: pbx.intern.example
Port: 8888
SSL verwenden: Nein

Dieses Beispiel setzt voraus, dass auf dem Server ssl="0" konfiguriert ist und eine vertrauenswürdige interne Verbindung besteht.

Anschließend auf Hinzufügen klicken.

Die Nebenstelle sollte als Leitung erscheinen, beispielsweise:

3CX Line(10)

Mit OK bestätigen.

Die angezeigte Leitung bestätigt zunächst nur die lokale Konfiguration und noch keine erfolgreiche Verbindung.

5. Serveradresse: IP oder FQDN

Für die Verbindung kann eine IP-Adresse oder ein auflösbarer Hostname verwendet werden, sofern der TAPI-Client diesen unterstützt.

Interne IP-Adresse:

192.0.2.10

Interner FQDN:

pbx.intern.example

Öffentlicher FQDN:

pbx.example.com

Die Adressen dienen ausschließlich als Beispiele.

Ein FQDN ist sinnvoll, wenn die DNS-Auflösung zuverlässig funktioniert und auf die richtige Serveradresse verweist.

Dabei ist zu beachten:

  • Die Serveradresse muss vom Windows-PC erreichbar sein.

  • Der FQDN muss zur richtigen IP-Adresse aufgelöst werden.

  • Bei SSL muss die Zertifikatskonfiguration zum verwendeten Hostnamen passen.

  • Eine öffentlich auflösbare Domain bedeutet nicht automatisch, dass der TAPI-Dienst erreichbar ist.

  • Der TAPI-Port sollte nicht unnötig über das Internet freigegeben werden.

Für interne Verbindungen können interne IP-Adressen oder interne DNS-Namen verwendet werden.

6. SSL und Authentifizierung

Die SSL-Konfiguration des Windows-Clients muss mit der Serverkonfiguration übereinstimmen.

Servereinstellung Windows-Client
ssl="0" SSL deaktivieren
ssl="1" SSL aktivieren

Bei aktiviertem SSL müssen außerdem die TLS- und Zertifikatseinstellungen des TAPI-Servers korrekt eingerichtet sein.

Die Client-Authentifizierung kann laut Herstelleranleitung serverseitig über folgenden Eintrag aktiviert werden:

<authenticate act="1" />

Bei aktivierter Authentifizierung muss der Client den passenden Systemschlüssel verwenden.

Die genaue Zuordnung der beiden Windows-Felder Schlüssel und Globaler Schlüssel ist anhand der vorliegenden Herstelleranleitung nicht vollständig beschrieben und muss gegebenenfalls anhand der eingesetzten Version geprüft werden.

7. Verbindung vom Windows-PC testen

7.1 TCP-Verbindung prüfen

PowerShell öffnen und folgenden Befehl ausführen:

Test-NetConnection <SERVER-IP> -Port 8888

Befehlstyp: LESEND

Erwartete Ausgabe:

TcpTestSucceeded : True

Bedeutung:

  • True – Die TCP-Verbindung zum angegebenen Port konnte hergestellt werden.

  • False – Die TCP-Verbindung konnte nicht hergestellt werden.

Ein erfolgreicher TCP-Test bestätigt noch nicht die korrekte TAPI-Anmeldung oder Funktionsfähigkeit der Nebenstelle.

7.2 DNS-Auflösung prüfen

Resolve-DnsName pbx.intern.example

Befehlstyp: LESEND

Prüfen, ob der Hostname zur erwarteten Server-IP aufgelöst wird.

Wenn sowohl die IP-Adresse als auch der FQDN beim Verbindungstest fehlschlagen, liegt das Problem wahrscheinlich nicht ausschließlich an der DNS-Auflösung.

7.3 TAPI-Leitung prüfen

In der TAPI-fähigen Anwendung prüfen, ob die konfigurierte Leitung, beispielsweise 3CX Line(10), zur Verfügung steht.

Für einen vollständigen Funktionstest sollte anschließend ein Testanruf über die TAPI-Anwendung durchgeführt werden.

8. Fehlerbehebung

8.1 Port 8888 nicht erreichbar

Wenn folgende Abfrage fehlschlägt:

Test-NetConnection <SERVER-IP> -Port 8888

sind folgende Prüfungen erforderlich.

1. Dienststatus auf dem TAPI-Server prüfen:

sudo systemctl status 3cxtapiserver --no-pager

2. Prüfen, ob Port 8888 lauscht:

sudo ss -lntp | grep ':8888'

3. Serverkonfiguration kontrollieren:

Prüfen, ob der konfigurierte HTTP-Port tatsächlich 8888 ist.

4. Firewall kontrollieren:

sudo nft list ruleset

Befehlstyp: LESEND

Die Firewallregeln können interne Netzwerkstrukturen offenlegen.

5. Netzwerkverbindung überprüfen:

  • Befinden sich Windows-PC und Server im selben Netzwerk?

  • Besteht eine Verbindung zwischen den VLANs?

  • Blockiert eine Firewall den TCP-Port?

  • Wird bei Verwendung eines FQDN die richtige IP-Adresse aufgelöst?

  • Lauscht der Dienst auf einer von den Clients erreichbaren Netzwerkschnittstelle?

Wichtig: Auch bei einer internen Verbindung können Firewallregeln den Zugriff blockieren.

Firewalländerungen dürfen nicht ohne Prüfung der bestehenden Regeln erfolgen. Insbesondere auf produktiven Servern muss sichergestellt werden, dass der Fernzugriff erhalten bleibt.

8.2 TAPI-Leitung vorhanden, aber keine Funktion

Mögliche Ursachen:

  • Nebenstelle auf dem Server nicht eingerichtet

  • Falsche Serveradresse

  • Falscher TCP-Port

  • Unterschiedliche SSL-Einstellungen

  • Fehlende oder falsche Authentifizierung

  • Netzwerkverbindung blockiert

  • Fehlerhafte Integration der TAPI-fähigen Anwendung

8.3 TAPI-Provider lässt sich nicht konfigurieren

Zunächst prüfen, ob die Konfiguration mit ausreichenden Administratorrechten geöffnet wurde.

Außerdem sicherstellen, dass der richtige TAPI-Provider verwendet wird.

Der 3CX TAPI Multi-Line Service Provider und der 3CX Tapi Service Provider verwenden unterschiedliche Integrationsverfahren.

9. Abschließende Funktionsprüfung

Vor der Übergabe sollten folgende Punkte kontrolliert werden:

  • TAPI-Serverdienst läuft.

  • Der konfigurierte TCP-Port lauscht.

  • Die benötigte Nebenstelle ist serverseitig hinterlegt.

  • Windows-PC erreicht den TAPI-Server.

  • DNS-Auflösung funktioniert bei Verwendung eines FQDN.

  • Der richtige TAPI-Provider ist installiert.

  • Nebenstellennummer und Serveradresse stimmen.

  • SSL-Einstellungen stimmen überein.

  • Authentifizierung ist korrekt eingerichtet.

  • Die Leitung erscheint in der TAPI-Anwendung.

  • Ein Testanruf wurde erfolgreich durchgeführt.

10. Weiterführende Dokumentation

Herstelleranleitung für den verwendeten Drittanbieter-TAPI-Server:

https://mail2fax.t38printer.de/manuals/3cxtapi.html

Diese Anleitung bezieht sich auf den dort beschriebenen 3CX TAPI Service Provider. Andere TAPI-Integrationen, insbesondere der offizielle 3CX Multi-Line TAPI Provider, können eine abweichende Installation und Konfiguration erfordern.