Telefonanlagen und Anbindungen

CallerHub bindet Telefonanlagen auf vier Wegen an: per HTTP-Abfrage je Anruf, als LDAP-Telefonbuch, über exportierte Telefonbücher und – für die Anrufanalyse – über Verbindungsdaten.

Namensabfrage per HTTP

Jede Telefonanlage wird als eigene Schnittstelle mit eigenem API-Key und eigenen erlaubten IP-Adressen angebunden. Die Grundversion erlaubt eine Schnittstelle, die Vollversion bis zu zehn (mehr mit Sonderlizenz). Alle Anlagen nutzen denselben Port; CallerHub erkennt sie an ihrem API-Key.

Anlage bzw. Profil	Antwortformat	Beispiel-Adresse	Einrichtung	Stand
STARFACE	Text	`…/lookup?number=` + Header `X-Api-Key`	über ein Modul der STARFACE; Beispielmodul `CRM-Lookup_v3.sfm` liegt bei	im Einsatz erprobt
3CX	JSON	`…/lookup?format=json&apikey=…&number=[Number]`	CRM-Vorlage, die CallerHub erzeugt („3CX-Vorlage …“)	ungeprüft
Asterisk / FreePBX	Text	`…/lookup?apikey=…&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})}`	Wählplan mit `CURL` (Modul `func_curl`)	ungeprüft
VitalPBX	Text	`…/lookup?apikey=…&number=[CIDNUM]`	CID-Lookup-Quelle in der eingehenden Route	ungeprüft
Issabel (auch FreePBX)	Text	Pfad `/lookup`, Abfrage `format=text&apikey=…&number=[NUMBER]`	CallerID Lookup Sources	ungeprüft
Yealink / Fanvil	XML-Telefonbuch	`…/lookup?format=yealink&apikey=…&number=#SEARCH`	Remote-Telefonbuch am Telefon oder per Provisionierung	ungeprüft
Snom	XML-Telefonbuch	`…/lookup?format=snom&apikey=…&number=#SEARCH`	XML-Telefonbuch am Telefon	ungeprüft
Allgemein (HTTP)	Text, JSON, XML	`…/lookup?format=json&apikey=…&number=071112345678`	jede Anlage, die bei einem Anruf eine Adresse per HTTP GET abrufen kann	allgemein

Nur die STARFACE-Anbindung ist im Einsatz erprobt. Die Anleitungen für die übrigen Anlagen beruhen auf veröffentlichten Schnittstellen; gleichen Sie Platzhalter, Menüpfade und Einstellungsnamen mit der Dokumentation Ihrer Version ab.

Eine Karte je Telefonanlage

Auf der Seite Schnittstellen hat jede Anlage eine eigene Karte mit Bezeichnung, Zustand der letzten Anfrage, API-Key, erlaubten IP-Adressen und den abgefragten Datenquellen. „Anleitung kopieren“ liefert die Einrichtungsanleitung für die gewählte Anlage mit dem echten API-Key.

Seite Schnittstellen mit einer geöffneten Karte für die Telefonanlage. — Seite Schnittstellen: eine Karte je Telefonanlage.

Karte Telefonanlage mit der Anleitung für die STARFACE. — Karte „Telefonanlage“ mit Anleitung für die STARFACE.

Beispiel Asterisk / FreePBX

exten => _X.,1,Set(CURLOPT(httptimeout)=2)
 same => n,Set(CALLERID(name)=${CURL(http://192.168.10.5:8080/lookup?apikey=API-KEY&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})})})
 same => n,Goto(from-pstn,${EXTEN},1)

Beispiel Yealink (Provisionierung)

remote_phonebook.data.1.url = http://192.168.10.5:8080/lookup?format=yealink&apikey=API-KEY&number=#SEARCH
remote_phonebook.data.1.name = CallerHub
features.remote_phonebook.enable = 1

STARFACE-Beispielmodul

Die STARFACE hat keine eingebaute Namensabfrage per Web-Adresse; sie fragt CallerHub über ein Modul ab. Das Beispiel Samples\CRM-Lookup_v3.sfm zeigt den Aufbau im Module Designer (Bausteine GetCaller, CreateHttpUrlWithParams, HttpRequest, ReadFromStream mit UTF-8, SetCallerId). Es ist als Vorlage zum Nachschlagen gedacht, nicht von STARFACE geprüft und fragt anonyme Anrufe nicht ab.

LDAP-Telefonbuch für Anlagen ohne HTTP-Abfrage

Viele Telefonanlagen und Tischtelefone fragen keine Web-Adresse ab, sondern ein LDAP-Verzeichnis. Dafür stellt das Modul Telefonbuch ein schreibgeschütztes LDAPv3-Verzeichnis bereit (Port 389, mit LDAPS 636). Die Rückwärtssuche bei eingehenden Anrufen fragt alle aktiven Datenquellen ab, einschließlich Regeln, Sperr- und VIP-Liste.

Typische Geräte: Unify OpenScape Business, Auerswald COMtrexx/COMpact, Avaya J100 an IP Office, Yeastar P-Series, innovaphone (Reverse Lookup), Ascom IP-DECT, Grandstream UCM, pascom, Gigaset, Yealink sowie die Mitel-100-Familie (Mitel 112, 130, 150).

Karte Telefonbuch mit LDAP-Telefonbuch, Anleitung je Gerät und Export. — Schnittstellen → Telefonbuch: LDAP-Telefonbuch, Anleitung je Gerät und Export.

Server:            Name oder IP-Adresse des CallerHub-Rechners, Port 389 (636 mit LDAPS)
Base DN:           ou=callerhub
Namensfilter:      (|(cn=%)(sn=%))
Nummernfilter:     (|(telephoneNumber=%)(mobile=%))
Anzeige-Attribut:  cn          Nummern-Attribut: telephoneNumber

Einträge enthalten uid, cn/sn/displayName, telephoneNumber (national und E.164), labeledURI und die Objektklasse inetOrgPerson; höchstens 200 Einträge je Suche. Schreibversuche werden abgelehnt, StartTLS wird nicht unterstützt. Die Anbindung der Mitel-100-Familie ist beschrieben, mit CallerHub aber noch nicht getestet.

Telefonbuch-Export und FRITZ!Box

Cloud-Anlagen wie Microsoft Teams, Zoom, NFON oder Placetel und die FRITZ!Box verwenden eigene Kontaktlisten. CallerHub exportiert dafür die Einträge aller Telefonnummernlisten (nach Regeln, ohne gesperrte Nummern).

Format	Verwendung
FRITZ!Box (XML)	FRITZ!Box: Telefonie → Telefonbuch → Wiederherstellen. Die Anzahl der Einträge ist je nach Modell begrenzt.
vCard 3.0 (.vcf)	Outlook, Auerswald, Gigaset und viele Cloud-Anlagen
CSV	Excel sowie Import in Cloud-Anlagen (z. B. Zoom, NFON, Placetel)
Yealink (XML)	Remote-Telefonbuch für Yealink und kompatible Telefone

Telefone mit Remote-Telefonbuch laden die Liste auch direkt: /phonebook?format=yealink&key=ZUGANGSSCHLUESSEL (Formate yealink, fritzbox, vcard, csv). Für die Anrufanalyse liest CallerHub den FRITZ!Box-Anrufmonitor auf Port 1012.

Verbindungsdaten für die Anrufanalyse

Die Anrufanalyse benötigt die Verbindungsdaten (CDR) der Telefonanlage. Diese gelangen als Datei, live über eine Verbindung oder per API zu CallerHub. Bis zu fünf Live-Empfänger lassen sich einrichten.

Schema: Verbindungsdaten erreichen CallerHub per Socket/TCP, über Verbindungen, die CallerHub aufbaut, per API-Abruf und per HTTP; CallerHub speist daraus Anrufanalyse und Anrufereignisse. — Wege der Verbindungsdaten zu CallerHub (Diagramm aus der CallerHub-Hilfe).

Quelle	Weg	Einstellung in der Telefonanlage
Asterisk / FreePBX	Datei `Master.csv` oder live über AMI (CallerHub verbindet sich, Port 5038)	`manager.conf`: Benutzer mit `read = cdr`; `cdr_manager.conf`: `enabled = yes`
STARFACE	Datei `output.csv`	Admin → Auswertung → Verbindungsdaten exportieren
3CX (v18/v20)	CDR-Socket aktiv (CallerHub wartet, z. B. Port 5100) oder passiv; CSV-Export	Admin → Einstellungen → CDR
3CX V20 (Cloud oder lokal)	API: CallerHub ruft XAPI ab (`/xapi/v1/ReportCallLogData`)	Integrationen → API: Client mit XAPI-Zugriff
Microsoft Teams Telefonie	API: Microsoft Graph, Berechtigung `CallRecords.Read.All`	App-Registrierung in Microsoft Entra ID
Webex Calling	API: `analytics.webexapis.com`, Scope `spark-admin:calling_cdr_read`	Control Hub: Rolle „Detailed Call History API access“
Mitel MiVoice Office 400	SMDR im Format PC5, CallerHub verbindet sich (Port 1080)	Ausgabe der Verbindungsdaten über TCP
Unify OpenScape Business	Gebührendaten per LAN, CallerHub wartet (z. B. Port 5101)	TCP-Client an CallerHub-Adresse:Port
innovaphone	TCP oder HTTP `/cdr`	Gateway → CDR0
FRITZ!Box	Anrufmonitor, CallerHub verbindet sich (Port 1012)	einmalig `#965` an einem Telefon wählen
Placetel	HTTP `/event`	Notify-API mit der Adresse von CallerHub
sipgate.io	HTTP `/event`	URL für eingehende und ausgehende Anrufe
Beliebige Anlage oder Skript	HTTP `/event` oder `/cdr`, CSV-Datei im Ordner `CallData`	siehe Schnittstelle

Einrichtung in fünf Schritten

Unter Schnittstellen eine Schnittstelle hinzufügen, die Telefonanlage wählen und eine Bezeichnung eingeben.
Unter „Erlaubte IP-Adressen“ die Adresse der Anlage bzw. das Netz der Telefone eintragen, z. B. 192.168.10.20 oder 192.168.20.0/24.
Die abgefragten Datenquellen prüfen und „Speichern und übernehmen“ wählen.
Im Browser eines Rechners im selben Netz testen: http://192.168.10.5:8080/lookup?apikey=API-KEY&number=030 1234560 liefert den Namen.
Die Anlage nach der Anleitung einrichten und einen Testanruf führen. Der Zugriff erscheint auf der Startseite unter „Letzte Zugriffe“.

Typische Fehler bei der Anbindung

Symptom	Ursache und Abhilfe
Kein Eintrag unter „Letzte Zugriffe“, Status „Wartet auf Anfragen“	Die Anfrage erreicht CallerHub nicht. Adresse in der Anlage (IP, Port, http/https), Windows-Firewall und Firewalls zwischen den Netzen prüfen.
`status=401`	API-Key falsch oder fehlend. Die Anleitung erneut kopieren; ein neu erzeugter Schlüssel muss auch in der Anlage geändert werden.
`status=403`	Die Absenderadresse steht nicht in den erlaubten IP-Adressen. Hinter NAT oder Reverse Proxy weicht der Absender ab.
`status=429`	Zu viele falsche Schlüssel von dieser Adresse. Das Ende der Sperre (Vorgabe 5 Minuten) abwarten.
Anfrage kommt an, aber kein Name	Nummer unbekannt, falsches `format` für die Anlage oder Zeitüberschreitung der Anlage kürzer als die Antwortzeit.
HTTPS schlägt fehl	Die Anlage vertraut dem Zertifikat nicht oder der Zertifikatsname passt nicht. Stammzertifikat in die Anlage importieren.
Umlaute falsch oder Name abgeschnitten	Antworten sind UTF-8; Zeichensatz der Anlage prüfen. Maximale Namenslänge unter Administration → Erweitert einstellen.

Bleibt die Ursache unklar, zeichnet „Fehleranalyse → Erweiterte Aufzeichnung starten …“ jede Anfrage mit allen Headern auf (Schlüssel maskiert). Der eingebaute Telefonanlagen-Simulator testet eine Einrichtung, ohne dass eine echte Anlage anruft.