# 3CX x Bookli
## Obiettivo
Creare un interno in 3CX e configurare Bookli affinché si registri su quell'interno, agendo come un telefono IP o softphone. Questo permetterà a Bookli di ricevere ed effettuare chiamate tramite il centralino 3CX.
***
### 1. Prerequisiti
* Un'installazione di 3CX attiva e accessibile tramite la Management Console.
* Il dominio o l'IP pubblico del server 3CX (es. `pbx.tuodominio.com`) e la porta SIP (di default `5060/UDP`).
* Accesso al firewall per aprire le seguenti porte:
* **SIP**: `5060/UDP` (o `5061/TLS` se si utilizza la crittografia TLS).
* **RTP**: Il range predefinito di 3CX (es. `9000–10999/UDP`).
* Le credenziali dell'interno che verrà creato (ID e Password).
* Gli indirizzi IP di uscita di Bookli, da inserire nella whitelist del firewall (disponibili nella dashboard di Bookli).
{% hint style="warning" %}
Nota: Non utilizzare i dati di esempio presenti in questa guida. Sostituiscili sempre con i valori reali del tuo ambiente.
{% endhint %}
***
### 2. Creazione dell'Interno in 3CX
{% stepper %}
{% step %}
### Accedi alla Management Console
Accedi alla **Management Console** di 3CX.
{% endstep %}
{% step %}
### Aggiungi una nuova interno
Vai su **Extensions → Add**.
{% endstep %}
{% step %}
### Compila i campi principali
* **Extension Number**: `300` (esempio).
* **First/Last Name**: `Bookli`.
* **Authentication ID**: `300` (o un ID diverso, se preferisci).
* **Authentication Password**: Imposta una password sicura (es. `p4ssBookli!`).
{% endstep %}
{% step %}
### Salva la configurazione
Salva l'interno appena creato.
{% endstep %}
{% endstepper %}
#### Impostazioni Consigliate per l'Interno
Apri l'interno appena creato (`300`) per verificare le seguenti opzioni:
* **Scheda "General" → "Options"**:
* Disattiva “Disallow use of extension outside the LAN” per consentire la registrazione da remoto.
* (Opzionale ma consigliato per NAT) Abilita “PBX Delivers Audio” per prevenire problemi di audio monodirezionale.
> Non è necessario "aggiungere un telefono" tramite MAC address. Bookli si registrerà come un client SIP standard utilizzando le credenziali dell'interno. Una volta registrato, lo stato in 3CX diventerà **Registered**.
***
### 3. Dati da Recuperare in 3CX per Bookli
Annota i seguenti valori (gli esempi sono fittizi):
* **SIP Server / Realm**: `pbx.tuodominio.com`
* **SIP Port**: `5060` (o `5061` se usi TLS)
* **Auth ID**: `300`
* **Auth Password**: `p4ssBookli!`
* **Extension Number (From User / Caller ID)**: `300`
* **RTP Range**: `9000–10999` (necessario per la configurazione del firewall)
***
### 4. Configurazione del "Carrier SIP" in Bookli
{% stepper %}
{% step %}
### Accedi a Bookli e crea un nuovo Carrier SIP
Accedi a Bookli e vai su **Impostazioni → Carrier SIP → Nuovo Carrier SIP**.
{% endstep %}
{% step %}
### Campi principali da compilare
* **Nome Carrier**: `3CX Interno 300`
* **Richiede Registrazione**: ✅ Selezionato
{% endstep %}
{% step %}
### Registrazione SIP
* **Username Registrazione**: `300` *(corrisponde all'Authentication ID di 3CX)*
* **Password Registrazione**: `p4ssBookli!` *(corrisponde all'Authentication Password di 3CX)*
* **SIP Realm**: `pbx.tuodominio.com` *(dominio o IP pubblico del tuo 3CX)*
* **From User**: `300` *(corrisponde all'Extension Number)*
* **From Domain**: (lascia vuoto se non richiesto)
* **Usa TLS**: Attiva solo se usi TLS in 3CX (ricorda di usare la porta `5061`).
* **IP Pubblico nel Contact**: Abilita solo in scenari NAT complessi, se necessario.
{% endstep %}
{% step %}
### Numero e Gateway
* **Numero di Telefono**: `300` *(l'interno su cui Bookli riceverà le chiamate)*
Gateway:
* **Indirizzo IP**: IP pubblico del server 3CX (es. `203.0.113.20`)
* **Porta**: `5060` (o `5061` se TLS)
* **Netmask**: `32`
* Spunta sia **Chiamate in entrata** che **Chiamate in uscita**.
{% endstep %}
{% step %}
### Salva la configurazione
Salva il nuovo Carrier SIP in Bookli.
{% endstep %}
{% endstepper %}
***
### 5. Firewall e Rete (lato 3CX)
Assicurati di consentire il traffico IN/OUT tra il server 3CX e gli IP di Bookli:
* **SIP**: `5060/UDP` (o `5061/TLS`).
* **RTP**: `9000–10999/UDP` (o il range configurato nel tuo 3CX).
{% hint style="warning" %}
Importante: Se il tuo router/firewall ha una funzionalità **SIP ALG** (Application Layer Gateway), **disattivala**. Può corrompere i pacchetti SIP e causare problemi di audio o di registrazione. Se 3CX è in cloud, configura le regole del Security Group/Firewall per consentire il traffico dalle sorgenti IP di Bookli.
{% endhint %}
***
### 6. Test di Registrazione
* In 3CX: Vai su **Extensions** e controlla l'interno `300`. Lo stato (**Status**) dovrebbe essere verde e mostrare **Registered**.
* In Bookli: Nella lista dei Carrier SIP, lo stato del carrier appena creato dovrebbe risultare **Registrato**.
***
### 7. Test delle Chiamate
* Chiamata interna verso Bookli: Da un altro interno (es. `301`), chiama il `300`. Bookli dovrebbe ricevere la chiamata.
* Chiamata in uscita da Bookli: Da Bookli, effettua una chiamata verso un altro interno (es. `301`). Il telefono associato all'interno `301` dovrebbe squillare.
Per instradare le chiamate esterne (es. da un numero geografico) verso Bookli, utilizza le **Inbound Rules** di 3CX per reindirizzare il traffico all'interno `300` o a un Ring Group/Queue di cui l'interno `300` è membro.
***
### 8. Mappatura dei Campi (3CX → Bookli)
| In 3CX | In Bookli (Carrier SIP) |
| ------------------------- | -------------------------------- |
| Extension Number (`300`) | `Numero di Telefono` = 300 |
| Authentication ID (`300`) | `Username Registrazione` = 300 |
| Authentication Password | `Password Registrazione` |
| SIP Server/FQDN/IP | `SIP Realm` = pbx.tuodominio.com |
| Extension Number (CLI) | `From User` = 300 |
| IP Pubblico di 3CX | `Gateway IP` |
| Porta SIP (`5060`/`5061`) | `Porta` |
***
### 9. Troubleshooting
A. L'interno non risulta "Registered"
* Verifica che Auth ID, Password e SIP Realm in Bookli siano corretti.
* Controlla che il firewall permetta il traffico dagli IP di Bookli verso la porta `5060/UDP` (o `5061/TLS`) del server 3CX.
* Assicurati che l'opzione **“Disallow use of extension outside the LAN”** sia disattivata nell'interno 3CX.
* Se usi TLS, verifica che sia attivo anche in Bookli e che il certificato su 3CX sia valido.
B. Audio monodirezionale o assente
* Abilita l'opzione **“PBX Delivers Audio”** nell'interno `300` su 3CX.
* Verifica che le porte RTP (`9000–10999/UDP`) siano aperte sul firewall in entrambe le direzioni.
* Disattiva il **SIP ALG** sul router.
C. La chiamata cade dopo circa 30 secondi
* Questo è un classico sintomo di problemi NAT/UDP. L'abilitazione di **“PBX Delivers Audio”** può risolvere.
* Verifica che i pacchetti di keep-alive/OPTIONS vengano scambiati correttamente.
D. Errori `403 Forbidden` / `401 Unauthorized`
* Le credenziali sono errate. Prova a rigenerare la password in 3CX e aggiornarla in Bookli.
* Controlla che gli IP di Bookli non siano stati inseriti nella blacklist automatica di 3CX.
E. Qualità audio scarsa (RTT elevato)
* Assicurati di usare i codec **G.711 (PCMA/PCMU)** e che ci sia banda sufficiente.
* Preferisci UDP a TCP per il trasporto SIP, se possibile, per ridurre la latenza.
---
# 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.bookli.ai/casi-duso/centralini-e-interni/3cx-x-bookli.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.