Start / Installation

Installation und Ersteinrichtung

Für Administration und IT · vom API-Zugang bis zum ersten Popup, etwa eine Stunde

1. Voraussetzungen

Die Edition steht in der 3CX unter Admin → Systemübersicht, Kachel System Information:

In kleineren Editionen zeigt die API-Seite einen Hinweis statt des Formulars:

2. 3CX: API-Zugang anlegen

1. Dienstprinzipal hinzufügen

   Admin → Integrationen → API → Hinzufügen. Als Client-ID zum Beispiel erpnext eintragen.

2. Konfigurations-API (XAPI) freischalten

   Haken bei Aktivieren dieser Anwendung für den Zugriff auf die 3CX-Konfigurations-API. Abteilung DEFAULT, Rolle „Systemeigentümer".

   Wichtig: Mit der Rolle „Systemadministrator" verweigert die 3CX die Anrufberichte (HTTP 403). Dann funktionieren Verbindungstest und Telefonbuch, aber die Anrufliste lässt sich nicht importieren.

3. Call Control API freischalten

   Haken bei Aktivieren des Zugriffs auf die 3CX Call Control API. Keine DID-Nummern eintragen, denn die Integration beobachtet Anrufe nur und nimmt selbst keine an. Die Chat-API bleibt aus.

   

4. Nebenstellen auswählen

   Über Nebenstellen auswählen alle Nummern markieren, deren Anrufe das ERP sehen soll: die Benutzer-Nebenstellen und auch Warteschleifen und Ringgruppen. Nur so erkennt das Popup, dass ein Anruf über die Zentrale kommt.

   

5. Speichern und API-Schlüssel sichern

   Nach dem Speichern zeigt die 3CX den API-Schlüssel genau einmal an. Kopiere ihn direkt in das ERP (Schritt 4) oder in deinen Passwort-Tresor. Geht er verloren, erzeugst du im API-Zugang mit API-Schlüssel generieren einen neuen. Der alte wird damit ungültig.

   

3. ERPNext: App installieren

Auf dem ERP-Server als Bench-Benutzer, vorher ein Backup:

cd ~/frappe-bench
bench --site erp.example.com backup
bench get-app https://github.com/itsdave-de/frappe_3cx --branch main
bench --site erp.example.com install-app frappe_3cx
bench --site erp.example.com migrate
bench build --app frappe_3cx
sudo supervisorctl restart all

Ersetze erp.example.com durch den Namen deiner Site. Die App bringt keine zusätzlichen Python-Pakete mit. Die Verbindung zur 3CX nutzt Bibliotheken, die Frappe ohnehin installiert.

4. Verbindung einrichten und testen

Im ERP ThreeCX → ThreeCX Settings öffnen:

1. Zugangsdaten eintragen

   Aktiviert setzen, PBX-URL der 3CX (zum Beispiel https://ihre-firma.3cx.de), Client-ID und Client Secret (den API-Schlüssel) eintragen und speichern.

2. Verbindung testen

   Mit Verbindung testen holt das ERP ein Token von der 3CX. Erwartet wird „Verbindung erfolgreich!". Ein Fehler hier bedeutet fast immer eine falsche URL, einen falschen Schlüssel oder eine fehlende Netzfreigabe von ERP zu 3CX auf Port 443.

5. Nebenstellen zuordnen

Jeder Benutzer, der Popups bekommen oder per Klick anrufen soll, braucht eine Zuordnung zu seiner Nebenstelle.

1. Automatisch abgleichen

   Nebenstellen von 3CX synchronisieren legt Zuordnungen überall dort an, wo die E-Mail-Adresse in der 3CX und im ERP übereinstimmt. Bestehende Zuordnungen bleiben unverändert.

2. Rest von Hand ergänzen

   Unter ThreeCX User Extension → Hinzufügen Benutzer und Nebenstellennummer eintragen. Das ist nötig, wenn in der 3CX andere E-Mail-Adressen hinterlegt sind als im ERP.

Was die Felder Popup bei eingehenden Anrufen und Primäre Nebenstelle bewirken, steht unter Funktionen im Detail.

6. Anrufliste importieren

Das ERP holt alle 5 Minuten die Anrufe seit dem jüngsten vorhandenen Eintrag im Anrufprotokoll. Ist das Protokoll noch leer, importiert der erste Lauf die gesamte Historie der 3CX. Bei großen Datenmengen startest du diesen Erstimport besser selbst auf dem Server, dort läuft er ohne Zeitlimit:

bench --site erp.example.com execute frappe_3cx.tasks.sync_call_history

Bei wenigen tausend Anrufen reicht auch der Button Anrufprotokoll von 3CX synchronisieren. Der Import ist wiederholbar, bereits vorhandene Anrufe werden erkannt und nicht doppelt angelegt.

7. Telefonbuch-Abgleich einschalten

1. Probelauf

   Telefonbuch-Abgleich prüfen (Probelauf) zeigt, wie viele Kontakte angelegt, geändert und gelöscht würden, ohne etwas zu schreiben.

2. Erster Abgleich

   Telefonbuch jetzt abgleichen überträgt die Kontakte. Das Ergebnis steht rechts im Feld Ergebnis des letzten Abgleichs.

3. Automatik einschalten

   Telefonbuch-Abgleich aktivieren setzen und speichern. Danach gleicht das ERP alle 15 Minuten ab.

8. Live-Ereignisse und Popup einschalten

Für Popup und Live-Anrufprotokoll hält ein Hintergrunddienst, der Listener, eine dauerhafte Verbindung zur 3CX. Er läuft als eigenes Supervisor-Programm neben den übrigen Frappe-Diensten.

1. Supervisor-Programm anlegen

   Als root die Datei /etc/supervisor/conf.d/frappe-3cx-callcontrol.conf anlegen. Pfade, Benutzer und Site-Namen an deine Installation anpassen:

   [program:frappe-3cx-callcontrol]
   command=/home/frappe/frappe-bench/env/bin/python -m frappe.utils.bench_helper frappe --site erp.example.com threecx-callcontrol
   directory=/home/frappe/frappe-bench/sites
   user=frappe
   autostart=true
   autorestart=true
   startsecs=10
   stopsignal=TERM
   stopwaitsecs=15
   stopasgroup=true
   killasgroup=true
   stdout_logfile=/home/frappe/frappe-bench/logs/threecx-callcontrol.log
   stderr_logfile=/home/frappe/frappe-bench/logs/threecx-callcontrol.error.log

   sudo supervisorctl reread
   sudo supervisorctl update
   sudo supervisorctl status frappe-3cx-callcontrol

   Die eigene Datei überlebt bench setup supervisor, das nur die von Bench erzeugte Konfiguration neu schreibt.

2. Live-Ereignisse aktivieren

   In den Einstellungen Live-Anrufereignisse aktivieren setzen und speichern. Innerhalb von etwa 30 Sekunden verbindet sich der Listener. Der Status des Listeners wechselt auf Verbunden und zeigt die Zahl der überwachten Nummern.

   

3. Funktionen prüfen

   Im Abschnitt Funktionen sind Click-to-Call, Popup und Anrufprotokollierung ab Werk eingeschaltet. Unter Telefonnummer-Zuordnung steht die Landesvorwahl, für Deutschland 49.

9. Abnahmetest

Klappt ein Punkt nicht, hilft die Fehlersuche.