# 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

<details>

<summary><strong>A. L'interno non risulta "Registered"</strong></summary>

* 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.

</details>

<details>

<summary><strong>B. Audio monodirezionale o assente</strong></summary>

* 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.

</details>

<details>

<summary><strong>C. La chiamata cade dopo circa 30 secondi</strong></summary>

* 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.

</details>

<details>

<summary><strong>D. Errori `403 Forbidden` / `401 Unauthorized`</strong></summary>

* 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.

</details>

<details>

<summary><strong>E. Qualità audio scarsa (RTT elevato)</strong></summary>

* 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.

</details>