Centralini e connessioni
CallerHub si collega ai centralini in quattro modi: con una ricerca HTTP a ogni chiamata, come rubrica LDAP, tramite rubriche esportate e – per l’analisi – tramite i dati delle chiamate.
Guide passo passo: STARFACE · 3CX · Asterisk/FreePBX · Yealink/Snom · Mitel 100 · FRITZ!Box · tutte le soluzioni
Ricerca del nome via HTTP
Ogni centralino è collegato come interfaccia separata con propria chiave API e propri IP consentiti. L’edizione base consente un’interfaccia, quella completa fino a dieci (di più con licenza speciale). Tutti usano la stessa porta; CallerHub li distingue dalla chiave API.
| Sistema o profilo | Formato di risposta | Indirizzo di esempio | Configurazione | Stato |
|---|---|---|---|---|
| STARFACE | Testo | …/lookup?number= + header X-Api-Key | tramite un modulo STARFACE; modulo di esempio CallerHub_Interface_v49.sfm incluso | testato |
| 3CX | JSON | …/lookup?format=json&apikey=…&number=[Number] | modello CRM generato da CallerHub («Modello 3CX …») | Cercasi tester |
| Asterisk / FreePBX | Testo | …/lookup?apikey=…&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})} | dial plan con CURL (modulo func_curl) | Cercasi tester |
| VitalPBX | Testo | …/lookup?apikey=…&number=[CIDNUM] | sorgente di ricerca CID nella rotta in ingresso | Cercasi tester |
| Issabel (anche FreePBX) | Testo | percorso /lookup, query format=text&apikey=…&number=[NUMBER] | CallerID Lookup Sources | Cercasi tester |
| Yealink / Fanvil | Rubrica XML | …/lookup?format=yealink&apikey=…&number=#SEARCH | rubrica remota sul telefono o tramite provisioning | Cercasi tester |
| Snom | Rubrica XML | …/lookup?format=snom&apikey=…&number=#SEARCH | rubrica XML sul telefono | Cercasi tester |
| Generico (HTTP) | Testo, JSON, XML | …/lookup?format=json&apikey=…&number=03023125017 | qualsiasi sistema che a una chiamata possa richiamare un indirizzo via HTTP GET | generico |
Testati: il collegamento STARFACE, il collegamento CSTA di Mitel 100, Aastra e OpenCom, i telefoni Mitel 6800/6900 e la FRITZ!Box. Le guide per gli altri sistemi si basano su interfacce pubblicate; verificate segnaposto, percorsi di menu e nomi delle impostazioni nella documentazione della vostra versione.
Una scheda per centralino
Nella pagina Interfacce ogni sistema ha la sua scheda con nome, stato dell’ultima richiesta, chiave API, IP consentiti e fonti interrogate. «Copia guida» fornisce la guida di configurazione del sistema scelto con la vera chiave API.


Esempio 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)
Esempio Yealink (provisioning)
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
Modulo STARFACE
STARFACE non ha una ricerca del nome integrata tramite indirizzo web; un modulo nel Module Designer chiede il nome a CallerHub a ogni chiamata in arrivo. Per configurarlo, importate Samples\CallerHub_Interface_v49.sfm; questo modulo gestisce la ricerca del nome. Un modulo esteso segnala anche tutti gli eventi di una chiamata (squillo, risposta, riaggancio, inoltro) per analisi, statistiche e vista live; dettagli su richiesta al supporto. Le chiamate anonime non vengono cercate.
Rubrica LDAP per sistemi senza ricerca HTTP
Molti centralini e telefoni da tavolo non interrogano un indirizzo web ma una directory LDAP. Per loro il modulo Rubrica fornisce una directory LDAPv3 di sola lettura (porta 389, 636 con LDAPS). La ricerca inversa delle chiamate in arrivo interroga tutte le fonti attive, comprese regole e liste di blocco e VIP.
Dispositivi tipici: Unify OpenScape Business, Auerswald COMtrexx/COMpact, Avaya J100 su IP Office, Yeastar serie P, innovaphone (ricerca inversa), Ascom IP-DECT, Grandstream UCM, pascom, Gigaset, Yealink e la famiglia Mitel 100 (Mitel 112, 130, 150).

Server: nome o IP del computer CallerHub, porta 389 (636 con LDAPS)
Base DN: ou=callerhub
Filtro nome: (|(cn=%)(sn=%))
Filtro numero: (|(telephoneNumber=%)(mobile=%))
Attributo nome: cn Attributo numero: telephoneNumber
I tentativi di scrittura vengono rifiutati, StartTLS non è supportato. Il collegamento LDAP della famiglia Mitel 100 è testato con CallerHub.
Export rubrica e FRITZ!Box
I centralini cloud come Microsoft Teams, Zoom, NFON o Placetel e la FRITZ!Box usano proprie liste di contatti. Per questi CallerHub esporta le voci di tutte le liste di numeri (dopo le regole, senza numeri bloccati).
| Formato | Uso |
|---|---|
| FRITZ!Box (XML) | FRITZ!Box: Telefonia → Rubrica → Ripristina. Il numero di voci è limitato a seconda del modello. |
| vCard 3.0 (.vcf) | Outlook, Auerswald, Gigaset e molti centralini cloud |
| CSV | Excel e import nei centralini cloud (ad es. Zoom, NFON, Placetel) |
| Yealink (XML) | Rubrica remota per Yealink e telefoni compatibili |
I telefoni con rubrica remota possono anche caricare la lista direttamente: /phonebook?format=yealink&key=ACCESS_KEY (formati yealink, fritzbox, vcard, csv). Per l’analisi CallerHub legge il monitor chiamate della FRITZ!Box sulla porta 1012.
Sincronizzare la rubrica STARFACE
Per le chiamate in uscita, app STARFACE, client web e liste chiamate mostrano solo nomi dalle rubriche STARFACE. Per questo CallerHub scrive i contatti delle sue liste di numeri in una rubrica dedicata tramite la REST API di STARFACE – ogni notte all’ora impostata, dopo ogni ricaricamento delle fonti e con un clic.
- Solo nella propria rubrica: CallerHub crea, modifica ed elimina voci solo lì. Se una fonte è vuota o si è ridotta di oltre la metà, non elimina nulla.
- Nessun accesso in ingresso: la connessione va da CallerHub al centralino; con OAuth da STARFACE 10.
- Grandi volumi a tappe: limiti per esecuzione e per l’intera rubrica, scelta delle fonti.

Provisioning dei telefoni Mitel (6800/6900)
Il modulo di provisioning fornisce ai telefoni Mitel le impostazioni via HTTP e TFTP – interno, account SIP, tasti e pagine – e mostra sul display info chiamata, ricerca CRM e pagina del team.
- Telefoni in tabella: MAC, modello, interno, nome; la colonna di stato mostra quando il telefono ha scaricato l’ultima volta il suo file.
- Tasti per tutti: BLF, selezione rapida, casella vocale, funzioni o nuova pagina – ordinati trascinando.
- Pagina del team: il softkey «Team» mostra i colleghi con il loro stato (in chiamata, squilla, libero); selezionandone uno si chiama.
STARFACE Cloud non risponde alle sottoscrizioni BLF di telefoni di terzi; i tasti dei colleghi si possono allora configurare come selezioni rapide e la pagina del team mostra comunque lo stato.
Dati delle chiamate per l’analisi
L’analisi richiede i dati dettagliati delle chiamate (CDR) del centralino. Arrivano a CallerHub come file, live su una connessione o tramite API. Si possono configurare fino a cinque ricevitori live.
| Fonte | Percorso | Impostazione nel centralino |
|---|---|---|
| Asterisk / FreePBX | File Master.csv o live via AMI (CallerHub si collega, porta 5038) | manager.conf: utente con read = cdr; cdr_manager.conf: enabled = yes |
| STARFACE | File output.csv | Admin → Report → Esporta dati chiamate |
| 3CX (v18/v20) | Socket CDR attivo (CallerHub è in ascolto, ad es. porta 5100) o passivo; export CSV | Admin → Settings → CDR |
| 3CX V20 (cloud o on-premise) | API: CallerHub interroga XAPI | Integrazioni → API: client con accesso XAPI |
| Microsoft Teams Phone | API: Microsoft Graph, autorizzazione CallRecords.Read.All | Registrazione app in Microsoft Entra ID |
| Webex Calling | API: analytics.webexapis.com, scope spark-admin:calling_cdr_read | Control Hub: ruolo «Detailed Call History API access» |
| Mitel MiVoice Office 400 | SMDR in formato PC5, CallerHub si collega (porta 1080) | Uscita dei dati chiamate via TCP |
| Unify OpenScape Business | Dati di tariffazione via LAN, CallerHub è in ascolto (ad es. porta 5101) | Client TCP verso indirizzo:porta di CallerHub |
| innovaphone | TCP o HTTP /cdr | Gateway → CDR0 |
| FRITZ!Box | Monitor chiamate, CallerHub si collega (porta 1012) | comporre una volta #96*5* su un telefono |
| Placetel | HTTP /event | API Notify con l’indirizzo di CallerHub |
| sipgate.io | HTTP /event | URL per chiamate in arrivo e in uscita |
| Qualsiasi sistema o script | HTTP o file CSV nella cartella CallData | dettagli su richiesta al supporto |
Configurazione in cinque passi
- In Interfacce aggiungete un’interfaccia, scegliete il centralino e inserite un nome.
- In «IP consentiti» inserite l’indirizzo del sistema o la rete dei telefoni, ad es.
192.168.10.20o192.168.20.0/24. - Controllate le fonti interrogate e scegliete «Salva e applica».
- Provate nel browser di un computer della stessa rete:
http://192.168.10.5:8080/lookup?apikey=API-KEY&number=040 66969000restituisce il nome. - Configurate il centralino secondo la guida e fate una chiamata di prova. La richiesta compare nella home in «Richieste recenti».

Errori di connessione frequenti
| Sintomo | Causa e rimedio |
|---|---|
| Nessuna voce in «Richieste recenti», stato «In attesa di richieste» | La richiesta non arriva a CallerHub. Controllate l’indirizzo nel centralino (IP, porta, http/https), il firewall di Windows e i firewall tra le reti. |
status=401 | Chiave API errata o mancante. Copiate di nuovo la guida; una chiave rigenerata va cambiata anche nel centralino. |
status=403 | L’indirizzo del mittente non è tra gli IP consentiti. Dietro NAT o un reverse proxy il mittente è diverso. |
status=429 | Troppe chiavi errate da questo indirizzo. Attendete la fine del blocco (5 minuti di default). |
| La richiesta arriva ma senza nome | Numero sconosciuto, format errato per il sistema, o il timeout del sistema è più breve del tempo di risposta. |
| HTTPS non funziona | Il sistema non si fida del certificato o il nome non corrisponde. Importate il certificato radice nel sistema. |
| Accenti errati o nome troncato | Le risposte sono in UTF-8; controllate il set di caratteri del sistema. Impostate la lunghezza massima del nome in Amministrazione → Avanzate. |
Se la causa resta poco chiara, «Risoluzione problemi → Avvia registrazione estesa …» registra ogni richiesta con tutti gli header (chiavi mascherate). Il simulatore integrato testa una configurazione senza che chiami un centralino reale.