Centralino telefonico 3CX
Collegare il centralino 3CX in sola lettura per vedere dove finiscono le chiamate di un interno, sorvegliare le linee e il backup, e prediagnosticare i ticket di telefonia.
FirstSI legge il centralino 3CX tramite la sua API di configurazione, in sola lettura. Senza aprire la console 3CX si vede così dove arrivano le chiamate di un interno a seconda del suo stato, che cosa succede a un numero in entrata fuori orario, se le linee dell'operatore sono in linea e se il backup è stato eseguito. La prediagnosi lo usa per i ticket di tipo «telefonia».
Che cosa può leggere FirstSI
| Argomento | Contenuto |
|---|---|
| Sistema | Versione, interni registrati sul totale, servizi del centralino (fermi o no), ultimo backup |
| Linee dell'operatore | Ogni linea (trunk), in linea o no, numero di chiamate simultanee |
| Interni | Telefono registrato o no, stato attuale (Disponibile, Assente, Fuori ufficio…), e per ogni stato dove vanno le chiamate in caso di mancata risposta, occupato o telefono non registrato |
| Numeri in entrata | Destinazione in orario d'ufficio, fuori orario e nei giorni festivi |
| Code di chiamata | Agenti di ogni coda, statistiche su un periodo (chiamate ricevute, risposte) |
| Registro delle chiamate | Chiamate ricevute o effettuate da un interno, con il percorso di ogni chiamata: regola d'arrivo, inoltro, segreteria, trasferimento, chi ha riagganciato |
| Registro di audit | Chi ha modificato la configurazione, quando, da quale indirizzo e su quale oggetto |
| Altro | Giorni festivi dichiarati, registro degli eventi, indirizzi bloccati dalla protezione anti-hacking |
Lato 3CX: creare il client API
Nella console di amministrazione 3CX, Integrazioni → API → Aggiungi:
- Indicate un ID client (un numero libero del piano di numerazione, di solito a 4 cifre). Annotatelo esattamente com'è.
- Spuntate Accesso all'API di configurazione.
- Scegliete il reparto e il ruolo. Per leggere tutti gli interni, il client deve vedere tutti i reparti. I report (registro delle chiamate, statistiche delle code, registro di audit) richiedono il ruolo Proprietario del sistema (System Owner); con un ruolo inferiore la configurazione si legge, ma i report rispondono «accesso negato».
- Salvate, poi copiate la chiave API mostrata. Non viene mostrata di nuovo.
Lato FirstSI: dichiarare il connettore
Connettori → Nuovo connettore, tipo REST API:
| Campo | Valore |
|---|---|
| Nome | un nome che contiene «3CX»: è così che la prediagnosi lo riconosce |
| Indirizzo di base | l'indirizzo della console 3CX, per esempio https://centralino.esempio.it |
| Autenticazione | Identità dell'applicazione → token (OAuth client_credentials) |
| Indirizzo del token (https) | https://centralino.esempio.it/connect/token |
| ID dell'applicazione (client_id) | l'ID client creato sopra |
| Segreto | la chiave API creata sopra |
| Agente di esecuzione | un agente che raggiunge il centralino; nessuno se il centralino è pubblicato su Internet |
Le query interrogano /xapi/v1/…. Un elenco restituisce al massimo 100 righe per chiamata, e il registro delle chiamate si legge su un periodo breve: 7 giorni al massimo.
Query utili
Scrivetele come qualsiasi query REST (vedi Connettori), poi testatele e convalidatele. Una buona base:
| Query | Parametri | Serve a |
|---|---|---|
| Stato del sistema | nessuno | Interni registrati, servizi, versione |
| Linee dell'operatore | nessuno | Linee non in linea |
| Backup | nessuno | Data dell'ultimo backup riuscito |
| Scheda di un interno | numero dell'interno | Registrazione, stato attuale |
| Inoltri di un interno | numero dell'interno | Destinazione delle chiamate per ogni stato |
| Destinazione di un numero | le ultime cifre del numero | Aperto, chiuso, festivi |
| Code e agenti | nessuno o numero di coda | Chi risponde in ogni coda |
| Chiamate ricevute da un interno | interno, inizio, fine | Registro con il percorso delle chiamate |
| Statistiche di un interno | interno, inizio, fine | Chiamate ricevute con o senza risposta, chiamate effettuate, durate. Passa dal report del gruppo 3CX dell'interno: il report «per interno» di 3CX può rispondere «errore 500» |
| Statistiche delle code | inizio, fine | Chiamate ricevute e risposte per coda |
| Modifiche della configurazione | oggetto (facoltativo) | Chi ha cambiato un inoltro, gli orari |
Date a ogni query una descrizione precisa: l'Assistente IA la legge per scegliere quella giusta. I registri delle chiamate contengono numeri di telefono: spuntate Dati sensibili (solo amministratori).
Sonde consigliate
| Sonda | Normale se | Gravità, frequenza |
|---|---|---|
| Linee dell'operatore non in linea | nessuna riga | critica, ogni 15 min |
| Servizi del centralino fermi | nessuna riga | critica, ogni 15 min |
| Ultimo backup di meno di 2 giorni | almeno una riga | avviso, ogni 6 h |
Nella prediagnosi
Il tipo telefonia esegue tre controlli quando esiste un connettore 3CX:
| Controllo | Che cosa dice |
|---|---|
| Stato del centralino | Linee dell'operatore non in linea, servizi fermi, quota di interni registrati, backup vecchio |
| Interno 3CX e inoltri | L'interno citato nel ticket o, in mancanza, quello del richiedente ritrovato tramite il suo indirizzo e-mail nella directory: telefono registrato, stato attuale e dove vanno le sue chiamate in quello stato; chiamate ricevute nelle ultime 48 h, con o senza risposta, e percorso dell'ultima chiamata persa |
| Numero in entrata | Il numero citato: la sua destinazione aperto, chiuso e nei festivi, poi lo stato e gli inoltri dell'interno di destinazione; le regole doppie vengono segnalate |
Un ticket «il mio telefono non squilla più» arriva così con la risposta più frequente: l'interno è rimasto nello stato Assente e le sue chiamate finiscono in segreteria.
Domande frequenti
Il token viene rifiutato (401). L'ID client o la chiave non corrispondono. Ricopiate l'ID così come appare in Integrazioni → API, rigenerate la chiave lato 3CX se serve e inseritela di nuovo nel connettore.
La configurazione si legge, i report rispondono 403. Il client API non ha il ruolo Proprietario del sistema.
Le query falliscono a intermittenza con 401. Un altro strumento usa lo stesso client API e annulla il token di FirstSI. Assegnategli un client proprio.
Il registro delle chiamate risponde «errore 500». Il periodo è troppo lungo o l'interno non esiste: riducetelo a pochi giorni e verificate il numero.
Fonte: · Docs FirstSI · aggiornato il 10/10/2026