# Integrazione con 3CX
Il modulo Centralino 3CX è dedicato alla gestione delle operazioni di integrazione del gestionale OpenSTAManager con il sistema di centralini 3CX, al fine di registrare le chiamate e fornire una consultazione rapida delle informazioni disponibili.
Sono disponibili due moduli distinti:
* **Centralino 3CX** gestisce la registrazione delle chiamate e la visualizzazione dello storico;
* **Operatori 3CX** permette l'assegnazione di anagrafiche Tecnico a uno specifico interno di chiamata, con gestione del relativo storico delle assegnazioni.
{% hint style="info" %}
[Clicca qui ](https://shop.openstamanager.com/prodotto/3cx/)per procedere all'acquisto
{% endhint %}
Il centralino 3CX si registra automaticamente nel browser in utilizzo una volta effettuato l'accesso a OpenSTAManager. Tutti gli utenti ricevono una notifica desktop all'arrivo di ogni chiamata in entrata, con 10-15 secondi di anticipo prima che il telefono inizi a suonare effettivamente.
Chrome mostra in automatico un popup per abilitare le notifiche, mentre per Firefox le notifiche sono disabilitate di default e compare un pulsante in alto a sinistra dell'interfaccia. Il click sulla notifica apre la schermata di riepilogo della chiamata, dove è possibile aggiungere una descrizione e modificare lo stato tra Aperta e Gestita.
**Attenzione**: la chiamata va posta come Gestita solo a seguito della chiusura fisica della telefonata.
Una volta aperti i dettagli della chiamata, è possibile procedere alla creazione o all'associazione con una Attività.
{% hint style="warning" %}
**Attenzione**: le chiamate in uscita non generano mai una notifica, ma sono accessibili dall'elenco principale del modulo Centralino 3CX.
{% endhint %}
### Caratteristiche principali
#### Integrazione API
Il sistema espone le seguenti API REST per l'integrazione con 3CX:
* **contact-lookup**: Ricerca automatica di contatti in base al numero telefonico
* **contact-creation**: Creazione automatica di nuovi contatti (opzionale)
* **call-journaling**: Registrazione completa delle chiamate (in entrata, in uscita, perse, senza risposta)
* **call-notification**: Invio notifiche desktop in tempo reale per chiamate in entrata
#### Normalizzazione numeri telefonici
Il sistema implementa una normalizzazione avanzata dei numeri telefonici che:
* Rimuove caratteri di formattazione (spazi, punti, trattini, parentesi, segni più)
* Gestisce correttamente i prefissi internazionali (0039, +39)
* Supporta ricerche parziali per numeri corti (< 6 cifre)
* Cerca automaticamente tra anagrafiche, sedi e referenti
#### Gestione notifiche desktop
* Utilizzo di Service Worker e Web Push API
* Supporto per Chrome e Firefox
* Notifiche con azioni rapide (Info, Anagrafica)
* Gestione automatica delle credenziali push nella tabella `3cx_push`
#### Widget di statistica
* **Statistiche Numeri**: Analisi numeri conosciuti vs sconosciuti con dettagli su chiamate e durata
* **Statistiche Telefonate**: Statistiche per operatore con numero chiamate risposte e tempo totale
#### Configurazione 3CX
La configurazione di 3CX deve essere effettuata attraverso il menu **Impostazioni -> CRM**, aggiungendo una personalizzazione in *Seleziona una soluzione CRM*.
Caricare il file [`OpenSTAManager.xml`](OpenSTAManager.xml:1) e configurare i seguenti parametri:
**Configurazione generale**
* **API Key**: Token di accesso all'API del gestionale (preferibilmente di Amministratore)
* **URL di OpenSTAManager**: URL di base per raggiungere il gestionale
**Opzionali**
* **Enable Contact Creation**: Abilita la creazione automatica di nuovi contatti (default: False)
* **New Contact First Name**: Nome per nuovi contatti (default: \[Number])
* **New Contact Last Name**: Cognome per nuovi contatti (default: Nuovo contatto (3CX))
* **Enable Call Journaling**: Abilita la registrazione delle chiamate (default: True)
* **Call Subject**: Oggetto delle chiamate (default: 3CX PhoneSystem Call)
* **Answered Inbound Call**: Testo per chiamate in entrata risposte
* **Missed Call**: Testo per chiamate perse
* **Answered Outbound Call**: Testo per chiamate in uscita risposte
* **Unanswered Outbound Call**: Testo per chiamate in uscita senza risposta
Il campo *Interrogazione CRM* deve essere impostato a "Sempre".
#### Configurazione notifiche desktop
Per abilitare le notifiche desktop, è necessario:
1. Includere il file JavaScript `centralino/ajax/caller.js` in tutte le pagine del gestionale modificando il file `config.inc.php`:
```php
// Ulteriori file CSS e JS da includere
$assets = [
'css' => [],
'print' => [],
'js' => [
'https://miainstallazione.osmbusiness.it/modules/3cx_centralino/ajax/caller.js',
],
];
```
2. Aggiungere i file delle chiavi VAPID nel percorso `modules/3cx_centralino/keys/`:
* `public_key.txt`: Chiave pubblica per le notifiche
* `private_key.txt`: Chiave privata per le notifiche
#### Configurazione operatori
Il modulo Operatori 3CX permette di assegnare anagrafiche di tipo Tecnico a specifici interni di chiamata:
1. Accedere al modulo Operatori 3CX
2. Aggiungere un nuovo operatore specificando:
* **Interno**: Il numero interno telefonico
* **Anagrafica**: Il tecnico associato all'interno
3. Il sistema mantiene automaticamente lo storico delle assegnazioni (soft delete)
### Funzionamento
#### Flusso delle chiamate
1. **Lookup contatto** (contact-lookup):
* 3CX invia una richiesta di ricerca contatto per ogni chiamata
* Il sistema normalizza il numero e cerca tra anagrafiche, sedi e referenti
* Viene creata una chiamata con durata 0 e stato "Aperta"
* Per chiamate in entrata, viene inviata una notifica push
2. **Notifica chiamata** (call-notification):
* Il sistema invia notifiche desktop a tutti i browser registrati
* Le notifiche includono azioni rapide per accedere ai dettagli
* Click sulla notifica apre la schermata di riepilogo della chiamata
3. **Journaling chiamata** (call-journaling):
* Al termine della chiamata, 3CX invia i dettagli completi
* Il sistema aggiorna la chiamata esistente o ne crea una nuova
* Se la chiamata è stata associata a un intervento, viene creata una sessione di tipo "CALL"
#### Gestione delle chiamate
**Chiamate in entrata**
* Ricevono notifica desktop 10-15 secondi prima che il telefono inizi a suonare
* Chrome mostra automaticamente un popup per abilitare le notifiche
* Firefox richiede l'abilitazione manuale tramite pulsante in alto a sinistra
* Click sulla notifica apre la schermata di riepilogo
**Chiamate in uscita**
* Non generano notifiche desktop
* Sono accessibili dall'elenco principale del modulo Centralino 3CX
* Vengono registrate automaticamente al termine della chiamata
**Stati della chiamata**
* **Aperta**: Chiamata in corso o appena ricevuta
* **Gestita**: Chiamata completata (da impostare solo dopo la chiusura fisica della telefonata)
#### Associazione con interventi
Dai dettagli della chiamata è possibile:
* Creare una nuova Attività collegata
* Associare la chiamata a un intervento esistente
* Aggiungere descrizioni e note
Se la chiamata viene associata a un intervento, il sistema crea automaticamente una sessione di tipo "CALL" con i tempi della chiamata.
### Test delle chiamate
Per testare il funzionamento del sistema, è possibile simulare chiamate tramite curl:
#### Chiamata in entrata senza risposta
```bash
curl -X POST -d '{"token":"il_tuo_token","version":"3cx","resource":"call-journaling","Number":"numero_chiamante","CallDirection":"Inbound", "CallStartTimeLocal":"2025-07-25 10:00:00", "CallEndTimeLocal":"2025-07-25 10:00:00", "Answered":0, "DurationSeconds":0, "Duration":"00:00:00", "CallType":"Voice", "Description":"Chiamata di test"}' 'https://miainstallazione.osmbusiness.it/api/'
```
#### Chiamata in entrata con risposta
```bash
curl -X POST -d '{"token":"il_tuo_token","version":"3cx","resource":"call-journaling","Number":"numero_chiamante","CallDirection":"Inbound", "CallStartTimeLocal":"2025-07-25 10:00:00", "CallEndTimeLocal":"2025-07-25 10:05:00", "Answered":1, "DurationSeconds":300, "Duration":"00:05:00", "CallType":"Voice", "Description":"Chiamata di test"}' 'https://miainstallazione.osmbusiness.it/api/'
```
***
## Changelog
### 5.0 (2026-03-10)
#### Aggiunto
* Generazione file JSON per verifica integrità moduli
* Aggiunta gulpfile e package.json per build automatizzata
* Ricerca con Google del numero su una nuova tab quando questo non è stato riconosciuto
#### Correzioni
* Ricerca associazione numero che inizia con 39 per coincidenza, non perché ha il prefisso internazionale
* `filtraNumero()` non rimuove più 39 in modo indiscriminato
### 4.1 (2025-09-30)
#### Aggiunto
* Introduzione widget Statistiche Numeri
* Introduzione widget Statistiche Telefonate
* Aggiunto periodo dinamico al widget Statistiche Telefonate
* Implementata normalizzazione avanzata numeri telefonici
#### Modificato
* Refactor: statistiche per operatore
#### Correzioni
* Inclusione corretta delle date nel periodo
* Escluse anagrafiche cancellate dalla ricerca numeri telefonici
* Aggiunto controllo validità numero prima della ricerca (no vuoto, minimo 3 cifre)
* Matching numeri telefonici
### 4.0 (2025-07-25)
#### Modificato
* Miglioria modulo centralino
### 3.1 (2024-11-22)
#### Correzioni
* Rimozione dipendenza carbon
* Orario fine chiamata
* Salvataggio orario inizio chiamata
### 3.0 (2024-06-14)
#### Aggiunto
* Aggiunto php-cs-fixer
* Aggiunto rector
* Allineato a OSM 2.5.2
### 2.0 (2023-10-06)
#### Aggiunto
* Gestione input telefono
### 1.0 (2023-04-27)
#### Aggiunto
* Rilascio iniziale del modulo centralino 3CX
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.openstamanager.com/2.10.4/moduli-premium/integrazione-con-3cx.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.