FreePBX e agente vocale AI: guida al collegamento

Per collegare FreePBX all'agente vocale AI di Aptiva crei un trunk che si registra verso di noi, con le credenziali che ti forniamo, e poi decidi con le rotte del centralino quali chiamate mandare all'agente e su quali interni l'agente può trasferire. Non devi aprire porte in ingresso, non serve un IP statico e non installi nulla sul centralino: bastano i moduli standard di FreePBX.

Il collegamento con FreePBX — trunk, registrazione, chiamata all'agente e trasferimento a un interno — è già stato provato sul campo. Le rotte con cui decidi quali chiamate mandare all'agente sono invece configurazione del tuo centralino, e le descriviamo come FreePBX le documenta. La guida prende come riferimento FreePBX 17 (Debian 12, Asterisk 21 o 22) e segnala dove FreePBX 16 e le versioni precedenti si comportano diversamente. Per i requisiti generali, la richiesta delle credenziali e i problemi comuni a tutti i centralini rimandiamo alla guida generale al collegamento del centralino: qui trovi solo ciò che è proprio di FreePBX.

Cosa ti serve su FreePBX#

Prima di aprire l'interfaccia ti servono tre cose: le credenziali del collegamento, un centralino che risolva i nomi DNS e, solo se scegli SIP, un trasporto TLS funzionante.

• Le credenziali del collegamento, che richiedi a noi indicando il protocollo scelto: ricevi utente, password, server, porta e, per SIP, l'indirizzo da autorizzare. Nei blocchi qui sotto compaiono come <UTENTE>, <PASSWORD>, <SERVER>, <PORTA> e <INDIRIZZO_APTIVA>. Copia server e porta dal foglio di configurazione, senza fidarti dei valori predefiniti del centralino.
• Un FreePBX che risolve i nomi: il server Aptiva è indicato per nome, non per IP. Su alcune installazioni datate la build di Asterisk è compilata senza resolver DNS e il nome non viene risolto affatto (vedi gli errori tipici).
• Per SIP, un trasporto TLS in chan_pjsip (spiegato nel prerequisito più sotto). Per IAX2 non serve nulla di più.

Su quale protocollo scegliere vale la regola della guida generale: IAX2 per i centralini della famiglia Asterisk, SIP su TLS per gli altri. FreePBX li supporta entrambi, e la FAQ ufficiale della versione 17 conferma che i trunk IAX restano supportati.

Il trunk IAX2 (consigliato)#

Il trunk IAX2 verso Aptiva è una sola sezione di tipo friend con registrazione in uscita: copre sia le chiamate che mandi all'agente sia i trasferimenti che l'agente fa squillare sui tuoi interni. Si crea da Connectivity → Trunks → Add Trunk → Add IAX2 Trunk.

I due campi «Trunk Name»#

Nella scheda del trunk IAX2 ci sono due campi con la stessa etichetta «Trunk Name», e non sono intercambiabili. Quello nella scheda General è solo l'etichetta con cui il trunk compare negli elenchi: scrivi «Aptiva» o quello che preferisci. Quello nella scheda iax2 Settings, sezione Outgoing, diventa il nome della sezione in iax.conf e deve essere esattamente <UTENTE>, perché è l'identificativo con cui Aptiva autentica il tuo centralino nelle due direzioni.

Nella scheda General, inoltre, lascia Outbound CallerID vuoto e CID Options su «Allow Any CID»: il numero di chi chiama deve attraversare il trunk intatto. Se imposti Maximum Channels, tieni conto che per quel campo ogni chiamata affidata all'agente conta una sola chiamata, anche durante la conversazione trasferita: il campo conta solo le chiamate in uscita sul trunk, e la gamba del trasferimento entra dal trunk. A pesare di più sono le licenze e i canali del centralino nel suo complesso: due chiamate mentre il chiamante parla con l'agente e tre durante la conversazione trasferita (la gamba dall'operatore, quella verso Aptiva e, nel trasferimento, quella di ritorno verso l'interno).

PEER Details e Register String#

Nella sezione Outgoing, campo PEER Details, cancella il testo precompilato da FreePBX e incolla:

host=<SERVER>
port=<PORTA>
username=<UTENTE>
secret=<PASSWORD>
type=friend
context=from-trunk
qualify=yes
encryption=yes
forceencryption=yes
requirecalltoken=yes
disallow=all
allow=alaw
allow=ulaw

Nella sezione Incoming, compila solo la Register String:

<UTENTE>:<PASSWORD>@<SERVER>:<PORTA>

e lascia USER Context e USER Details completamente vuoti, cancellando il template che FreePBX propone (type=user, context=from-trunk, eccetera): con type=friend la sezione PEER vale già anche da user.

Quattro righe di questa configurazione non sono scelte estetiche:

• type=friend fa valere la stessa sezione da peer e da user. Un semplice type=peer coprirebbe le chiamate che mandi ad Aptiva ma non quelle che Aptiva manda a te, cioè il trasferimento verso l'interno: il trunk deve accettare anche le chiamate che arrivano da Aptiva.
• context=from-trunk (o from-aptiva, se hai attivato le chiamate in uscita) è la riga da cui dipende il trasferimento: fa entrare le chiamate provenienti da Aptiva nel contesto standard dei trunk di FreePBX, dove le tue Inbound Routes le consultano come farebbero con una chiamata dall'operatore. Senza questa riga l'interno non squilla.
• encryption=yes e forceencryption=yes sono obbligatorie perché dalla nostra parte la cifratura è forzata: un trunk senza cifratura non si collega in chiaro, non si collega affatto. È il primo sospetto se la registrazione non arriva.
• disallow=all più allow=alaw e allow=ulaw limitano i codec ai due che usiamo, con A-law per primo perché in Italia è quello della rete telefonica. Il perché di G.711 e non di Opus è spiegato nella guida generale, sezione Codec G.711 e perché non Opus.

requirecalltoken=yes mantiene la protezione dei call token che la documentazione Asterisk raccomanda su IAX2; Aptiva la supporta.

Dopo Submit e Apply Config, da asterisk -r il comando iax2 show registry deve mostrare lo stato Registered e iax2 show peers il peer <UTENTE> come OK con un tempo di risposta in millisecondi.

Il trunk SIP (PJSIP) su TLS#

Il trunk SIP verso Aptiva è un trunk chan_pjsip con registrazione in uscita, trasporto TLS e audio SRTP. Richiede un passo preliminare che su IAX2 non esiste: un trasporto TLS sul centralino.

Prerequisito: il trasporto TLS di PJSIP#

Asterisk crea un trasporto TLS solo se gli indichi un certificato, quindi il trasporto va preparato prima del trunk, in due mosse:

1. In Admin → Certificate Management deve esistere almeno un certificato. Va bene un certificato autofirmato generato da lì: Aptiva non chiede un certificato client al tuo centralino, il certificato serve solo a far nascere il trasporto.
2. In Settings → Asterisk SIP Settings → SIP Settings [chan_pjsip] abilita il trasporto TLS, seleziona quel certificato e attiva Verify Server: il certificato di Aptiva è pubblico, emesso da Let's Encrypt e rinnovato automaticamente, quindi il collegamento risulta autenticato oltre che cifrato. Nel campo CA Chain File, che è un percorso a un file e vale per tutto il trasporto TLS, indica un file che contenga la radice ISRG Root X1 di Let's Encrypt, per esempio il bundle delle CA di sistema, mai il certificato del nostro server, che cambia a ogni rinnovo.

Tre inciampi da conoscere:

• SSL Method: imposta sslv23, su tutte le versioni, FreePBX 17 incluso. Nonostante il nome — e l'etichetta «Insecure» che la GUI di FreePBX 17 gli mette accanto — sslv23 negozia la versione TLS più alta disponibile, cioè TLS 1.2 o 1.3, che sono quelle che il collegamento accetta. Il valore predefinito di FreePBX 17 (Default) si traduce in solo TLS 1.0, che Aptiva rifiuta; tlsv1_2 funziona ma esclude TLS 1.3. Su build di Asterisk più vecchie, inoltre, tlsv1_1 e tlsv1_2 non sono nemmeno riconosciuti e il trasporto non viene caricato, senza spiegazioni.
• Modifiche a un trasporto esistente. Un trasporto nuovo nasce con un normale Apply Config, ma ogni modifica a uno esistente richiede fwconsole restart. Il comando pjsip show transports non ti aiuta a capire in quale caso sei: può mostrare valori che non corrispondono al trasporto in esercizio finché non riavvii Asterisk.
• External Address nella sezione NAT delle impostazioni SIP deve essere un indirizzo o un nome risolvibile, altrimenti il trasporto TLS può rifiutarsi di partire.

La porta locale su cui il trasporto TLS ascolta è un dettaglio interno al tuo centralino: non va aperta in ingresso, perché è FreePBX a iniziare la connessione.

I campi del trunk#

Crea il trunk da Connectivity → Trunks → Add Trunk → Add SIP (chan_pjsip) Trunk. Nella scheda General lascia Outbound CallerID vuoto e CID Options su «Allow Any CID». Nella scheda pjsip Settings, questi sono i campi che contano (la ripartizione tra le sotto-schede General e Advanced varia leggermente da una versione all'altra):

Due campi meritano una spiegazione, perché sono i modi in cui il trunk SIP fallisce senza dirlo.

From User e Outbound CallerID restano vuoti. Sono i due campi con cui FreePBX può sovrascrivere l'utente del campo From, ed è lì che viaggia il numero di chi sta chiamando. Se ne compili uno, quel valore sostituisce il numero del chiamante: l'agente non sa più chi chiama, sul display dell'interno comparirebbe sempre lo stesso numero e, se il valore non è un numero di telefono (per esempio il nome del trunk), Aptiva rifiuta la chiamata. Aptiva riconosce il tuo centralino dalla credenziale, non da quel campo.

Match (Permit) con <INDIRIZZO_APTIVA> serve nell'altra direzione. Il trunk deve accettare anche le chiamate che arrivano da Aptiva, cioè i trasferimenti. Quando l'agente trasferisce a un interno, la chiamata che parte da Aptiva porta nel From il numero del chiamante originale, non il nostro nome utente: è esattamente ciò che questo collegamento esiste per consegnarti. Il tuo FreePBX non può quindi riconoscerci per nome e deve riconoscerci per indirizzo; senza quella riga il trasferimento viene rifiutato come anonimo.

Dopo Apply Config, pjsip show registrations deve mostrare Registered e pjsip show endpoint <nome del trunk> lo stato Not in use.

Le rotte in entrata dedicate agli interni#

Per ogni interno o gruppo che l'agente deve poter far squillare crei una Inbound Route dedicata con DID Number uguale al numero dell'interno. È la forma che abbiamo scelto perché rende il percorso esplicito, riconoscibile nei log e indipendente dalle altre rotte che il tuo centralino già ha.

Il meccanismo è questo: quando l'agente trasferisce, Aptiva compone verso il tuo centralino il numero della voce di rubrica così com'è (per esempio 201, o 7 per un gruppo), e quella chiamata entra dal trunk nel contesto standard (from-trunk), quindi passa dalle tue Inbound Routes come farebbe una chiamata dall'operatore. La rotta dedicata la aggancia e la consegna all'interno.

Da Connectivity → Inbound Routes → Add Inbound Route, per ogni interno:

Il numero del chiamante originale arriva nel From della chiamata di trasferimento, quindi chi risponde vede sul display chi sta chiamando, come spiegato nella guida sul trasferimento assistito. Se il tuo centralino riscrive i caller ID con proprie regole (per esempio nella scheda Advanced della rotta), quelle regole valgono anche qui.

Due attenzioni sugli interni e i gruppi che metti in rubrica:

• Segreteria e Follow Me contano come risposta. Se sull'interno scatta la segreteria o un inoltro prima della fine del tempo di squillo dell'agente, per l'agente «ha risposto qualcuno»: fa la presentazione alla segreteria ed esce. Tieni il tempo di squillo dell'agente (predefinito 30 secondi) più corto di quello della segreteria o del Follow Me dell'interno.
• Un gruppo o una coda in rubrica non deve avere l'agente come fallback. Se in rubrica c'è un Ring Group o una coda, la sua Destination if no answer (o Fail Over Destination, o la destinazione fuori orario) non deve essere l'agente, cioè la Misc Destination «Agente vocale AI» o il trunk Aptiva: il trasferimento tornerebbe all'agente, che presenterebbe la chiamata a un'altra sessione dell'agente. Se ti servono entrambi i ruoli, usa gruppi distinti.

La precedenza delle rotte in FreePBX#

In FreePBX una rotta che filtra sul numero del chiamante batte una rotta che filtra solo sul numero chiamato, per quanto quest'ultima sia specifica. L'ordine effettivo, che abbiamo misurato sul campo, è: DID più CID, poi solo CID (con DID qualsiasi), poi solo DID, infine la rotta senza filtri. Non è «vince il DID più specifico».

La conseguenza pratica riguarda le regole per CID che il tuo centralino potrebbe già avere (blacklist, clienti VIP, numeri interni dell'azienda instradati a parte): il trasferimento dall'agente porta nel From il numero del chiamante originale, quindi una tua regola per CID può intercettarlo e portarlo a un'altra destinazione. Sul campo è successo: il primo trasferimento finì a un gruppo di chiamata invece che all'interno richiesto, per una regola su qualsiasi DID con filtro sul chiamante.

Succede ogni volta che un chiamante coperto da una tua regola per CID arriva comunque all'agente: perché la chiamata gli è passata dal fallback di un gruppo, dal fuori orario o da un'opzione del menu, oppure per il formato del numero. Il tuo operatore può consegnare il chiamante in forma nazionale (senza +39), mentre Aptiva lo restituisce sempre in formato internazionale con il +: una regola scritta in un formato non aggancia il chiamante all'ingresso, ma aggancia il trasferimento scritto nell'altro. Se hai regole per CID, controlla a quali chiamanti si applicano e in che formato sono scritte e, se serve, riscrivile in entrambe le forme o toglile.

Mandare le chiamate all'agente#

Le chiamate arrivano all'agente vocale AI instradandole sul trunk Aptiva, e in FreePBX puoi farlo da qualunque punto del flusso: una Inbound Route, un menu IVR, una Time Condition, il fallback di un Ring Group o di una coda. Il numero che il centralino compone sul trunk non è vincolante: la chiamata arriva comunque al tuo agente, quindi scegli il numero che ti torna comodo.

Tutte le chiamate di un numero. La via più corta è la Inbound Route del tuo numero (o quella senza DID, se vuoi tutto il traffico) con Set Destination → Trunks → il trunk Aptiva. FreePBX manda la chiamata sul trunk così com'è. Le chiamate con numero nascosto oggi l'agente non le gestisce (vengono rifiutate, e dal centralino risultano occupato): instradale altrove, per esempio ai telefoni, con una Inbound Route dedicata a quel tipo di chiamante. Puoi collegare più numeri, ognuno con il suo agente: ogni numero è un collegamento con le proprie credenziali, quindi un trunk distinto su FreePBX, ed è il trunk usato a decidere quale agente risponde, non il numero composto.

Solo alcune chiamate: fuori orario, mancata risposta, opzione del menu. Qui serve una destinazione riutilizzabile, in due passi:

1. Una Outbound Route dedicata al trunk Aptiva (Connectivity → Outbound Routes): Route Name «Aptiva», in Trunk Sequence for Matched Routes solo il trunk Aptiva, e in Dial Patterns un match pattern con un numero breve che non usi altrove, per esempio 8000. Lascia Route CID vuoto: il numero del chiamante deve passare intatto. Metti questa rotta in cima alla lista, così nessun'altra rotta intercetta quel numero.
2. Una Misc Destination (Applications → Misc Destinations): Description «Agente vocale AI», Dial 8000. Da questo momento «Agente vocale AI» compare tra le destinazioni selezionabili ovunque.

Con quella destinazione realizzi gli scenari tipici:

Una precisazione che evita una prova sbagliata: una chiamata fatta da un interno del tuo centralino verso 8000 non è il modo per provare il collegamento. Di default l'agente risponde alle chiamate che arrivano dall'esterno e che il centralino gli passa; l'interno che chiama direttamente l'agente è disponibile su richiesta. Prova sempre chiamando il tuo numero da un telefono esterno.

Chiamate in uscita dal tuo numero con FreePBX#

Con il trunk collegato, l'agente vocale AI può anche chiamare in uscita mostrando il numero della tua azienda: le campagne verso i tuoi contatti e i richiami annotati durante una conversazione. La chiamata arriva a FreePBX dal trunk Aptiva, con il numero da chiamare in formato internazionale (per esempio +393331234567), e FreePBX la fa uscire dal trunk del tuo operatore come una chiamata fatta da un tuo interno, con il tuo piano tariffario. Il quadro generale — cosa serve e perché — è nella guida generale, sezione Chiamate in uscita dal tuo numero.

Se preferisci farla da te, qui sotto trovi la configurazione completa. È in due parti. Una Outbound Route dedicata, creata dall'interfaccia, che lascia uscire solo cellulari, fissi e VoIP italiani, presenta numero e nome della tua azienda e chiude senza rispondere le chiamate che non possono uscire. E un contesto di due righe nel dialplan, che manda a quella rotta i numeri con +39 arrivati dal trunk Aptiva e lascia tutto il resto — i trasferimenti agli interni — esattamente com'è. Il tetto alle chiamate in uscita contemporanee è il Maximum Channels del trunk dell'operatore, che probabilmente hai già impostato e su cui torniamo più sotto.

Oltre ai soliti segnaposto ne servono due: <NUMERO_AZIENDA>, il numero da presentare a chi riceve, nel formato che il tuo operatore accetta (di norma lo stesso che già usi nell'Outbound CallerID del trunk dell'operatore), e <NOME_AZIENDA>, il nome da presentare.

La Outbound Route dedicata#

Da Connectivity → Outbound Routes → Add Outbound Route, nella scheda Route Settings:

Route CID e Override Extension vanno insieme perché l'identificativo con cui una chiamata arriva dal trunk Aptiva non è sempre quello da presentare fuori: un trasferimento verso un numero esterno, per esempio, porta il numero del chiamante originale, che serve sul display dei tuoi interni ma non può uscire sulla rete pubblica. Verso l'operatore deve partire sempre l'identità della tua azienda, ed è questo che le due impostazioni garantiscono.

Optional Destination on Congestion copre i casi in cui la rotta non riesce a far uscire la chiamata: Maximum Channels del trunk dell'operatore esaurito, rifiuto dell'operatore (per esempio un cellulare spento), nessuna risposta. Senza questo campo FreePBX riproduce il messaggio «tutti i circuiti sono occupati», e per riprodurlo risponde al canale: per Aptiva la chiamata risulta risposta, l'agente parla sopra il messaggio e l'esito registrato è sbagliato. Con Terminate Call → Congestion la chiamata viene chiusa senza risposta, e l'agente la registra per quello che è.

Nella scheda Dial Patterns, una riga per lunghezza, tutte con prefix +39 e un match pattern di sole cifre. X è una cifra qualsiasi e [1-9] una cifra da 1 a 9; senza il punto finale, un pattern accetta solo cifre e solo quella lunghezza.

Sono più righe di quante ne servirebbero con un pattern come 3X., e la differenza è voluta: il punto finale accetta qualunque carattere e qualunque lunghezza, mentre le cifre esatte garantiscono che dal centralino escano solo cellulari, fissi e VoIP italiani, mai numeri esteri né numerazioni che iniziano per 1 o per 8, come 144, 166, 892 e 899 (salvo i numeri verdi, se aggiungi le righe facoltative), anche davanti a un numero malformato. È una scelta che protegge la bolletta, e costa solo qualche riga in più. Lo 0[1-9] esclude anche lo 00 del prefisso internazionale. Con queste righe, e solo con queste, un numero estero, una numerazione come 899 o un numero di lunghezza sbagliata non corrisponde a nessuna riga e la chiamata viene rifiutata. L'unica numerazione speciale con la forma di un fisso è lo 0878: i pattern non la distinguono, ma Aptiva non chiama numerazioni a sovrapprezzo, quindi dal nostro lato non arriva. Il prefix +39 viene tolto prima di passare il numero al trunk, quindi l'operatore riceve il numero in formato nazionale (3331234567), come quando lo compone un tuo interno; se il tuo operatore vuole un altro formato, usa il campo prepend su ogni riga, per esempio 0039.

Dopo Submit riapri la rotta dall'elenco: nell'URL della pagina di modifica compare id=N. Quel numero è l'identificativo con cui FreePBX genera il contesto della rotta nel dialplan, outrt-N, e ti serve al passo successivo.

Il contesto del trunk Aptiva#

In /etc/asterisk/extensions_custom.conf aggiungi un contesto dedicato al trunk Aptiva, sostituendo N con il numero della rotta:

; /etc/asterisk/extensions_custom.conf
[from-aptiva]
; I numeri +39 vanno alla rotta Aptiva-uscita (N = id della rotta).
exten => _+39X.,1,Goto(outrt-N,${EXTEN},1)
; Tutto il resto, cioè i trasferimenti agli interni, segue le Inbound Routes come prima.
exten => _X!,1,Goto(from-trunk,${EXTEN},1)

Le due righe fanno questo:

• La prima aggancia ogni numero che inizia con +39 e lo consegna alla rotta dedicata, che fa uscire solo i numeri ammessi dai suoi Dial Patterns e rifiuta gli altri. Qui il punto finale va bene: non decide cosa esce, decide solo a chi passare il numero, e a decidere sono i Dial Patterns della rotta.
• La seconda aggancia i numeri senza +, cioè gli interni e i gruppi della rubrica (201, 7), e li manda in from-trunk, il contesto standard dei trunk, dove le tue Inbound Routes dedicate li consegnano come oggi. Per i trasferimenti non cambia nulla.

Un numero con un prefisso internazionale diverso da +39 non corrisponde a nessuna delle due righe e viene rifiutato. Il contesto non passa da from-internal, di proposito: quella è la porta d'ingresso dei telefoni, da cui si raggiungono tutte le rotte in uscita e i codici di servizio del centralino; il trunk Aptiva verso l'esterno vede solo Aptiva-uscita.

Poi sposta il trunk Aptiva nel nuovo contesto: su IAX2, in PEER Details, context=from-aptiva al posto di context=from-trunk; su SIP, il campo Context del trunk da from-pstn a from-aptiva. Fai prima il file e poi il trunk, così il contesto esiste già quando il trunk lo usa. Dopo Apply Config (il file custom si ricarica con il dialplan), da asterisk -r:

dialplan show from-aptiva
dialplan show outrt-N

Il primo comando deve mostrare le due righe del contesto; il secondo i Dial Patterns della rotta, uno per riga, con il +39 davanti.

Le chiamate contemporanee#

Il tetto è il Maximum Channels del trunk del tuo operatore, nella scheda General del trunk: conta le chiamate in uscita su quel trunk, quelle dei tuoi interni e quelle dell'agente, che passando dalla Outbound Route lo rispettano come le altre. Non conta le chiamate in arrivo dei tuoi clienti, che usano le stesse linee del contratto: per lasciarne sempre di libere, conviene impostarlo sotto il numero di linee del contratto, così la differenza resta a disposizione delle chiamate in arrivo anche durante una campagna. Se è vuoto, impostalo. Raggiunto il tetto, la chiamata in più non esce e, con Optional Destination on Congestion sulla rotta, viene chiusa come congestione senza essere risposta. Il Maximum Channels del trunk Aptiva, invece, conta le chiamate verso l'agente, non queste.

Prima di una campagna tieni conto che le chiamate dell'agente e quelle dei tuoi interni condividono lo stesso tetto: una campagna che lo raggiunge lascia i tuoi interni senza linea libera per chiamare fuori finché una chiamata non termina.

La prima prova#

La prima chiamata di prova falla verso il tuo cellulare; se vuoi, la seguiamo insieme dal nostro lato. Sul display devono comparire il numero e il nome della tua azienda. Se qualcosa non torna, questi sono i quattro sintomi tipici:

• La chiamata torna all'agente invece di uscire. Il trunk Aptiva è rimasto nel contesto standard (from-trunk o from-pstn): il numero +39… passa dalle Inbound Routes e, se la rotta senza DID punta all'agente, torna lì. Imposta il contesto from-aptiva sul trunk e riapplica.
• La chiamata viene rifiutata. Il numero non corrisponde a nessun Dial Pattern della rotta, oppure N nel file custom non è l'id giusto: confronta dialplan show outrt-N con il numero chiamato.
• La chiamata esce con un numero diverso da quello dell'azienda. Route CID vuoto o Override Extension su No.
• L'agente sente o parla sopra un messaggio di linee occupate. Manca Optional Destination on Congestion sulla rotta: quando la chiamata non può uscire, FreePBX riproduce il messaggio «tutti i circuiti sono occupati» e per farlo risponde al canale, quindi per l'agente la chiamata risulta risposta. Imposta il campo su Terminate Call → Congestion.

Una configurazione sicura, in breve#

Fatta così, la configurazione apre al trunk Aptiva una sola via verso l'esterno e la tiene stretta: escono solo cellulari, fissi e VoIP italiani, della lunghezza giusta; escono con l'identità della tua azienda; passano dalla rotta dedicata, quindi dal Maximum Channels del trunk del tuo operatore. Due accortezze restano dalla tua parte, e valgono per qualunque trunk da cui si può chiamare fuori:

• Le credenziali del collegamento. Con le chiamate in uscita attive, autorizzano chiamate che escono dalle tue linee a tue spese: trattale come quelle del tuo operatore e, al minimo dubbio, chiedici di rigenerarle.
• Il trasporto del trunk. Con un trunk SIP il centralino riconosce le chiamate di Aptiva dall'indirizzo, quindi nessun trasporto SIP in chiaro, UDP o TCP, deve essere raggiungibile da Internet. Se puoi scegliere, usa IAX2: ogni chiamata è autenticata con la password del collegamento, e la domanda non si pone.

Firewall e Intrusion Detection#

Il firewall di FreePBX non richiede regole in ingresso per questo collegamento, perché la connessione la apre il tuo centralino; conviene però assicurarsi che le protezioni automatiche non blocchino l'indirizzo da cui arrivano i trasferimenti e i controlli del trunk.

• Firewall (Connectivity → Firewall). La documentazione Sangoma dice che per i trunk configurati non serve alcuna configurazione aggiuntiva: gli host dei trunk vengono aggiunti automaticamente.
• Intrusion Detection (nel modulo Firewall; nelle versioni meno recenti stava in System Admin). Aggiungi alla Custom Whitelist (un indirizzo IP o un nome host per riga) <INDIRIZZO_APTIVA> (SIP) oppure il nome <SERVER> (IAX2): da quell'indirizzo arrivano i trasferimenti e i controlli del trunk, e un blocco li farebbe fallire.
• Responsive Firewall. Riguarda chi tenta di registrarsi verso il tuo centralino, non un trunk che si registra in uscita: non interferisce con il collegamento.
• SIP ALG sul router. Vale l'indicazione della guida generale, sezione Sicurezza del collegamento: disattivalo. Con IAX2 il problema non si pone, perché segnalazione e audio viaggiano insieme su una sola porta.

Il collegamento è cifrato in entrambe le direzioni ed è FreePBX a collegarsi ad Aptiva, quindi non c'è nessuna porta da aprire. Il trunk Aptiva resta in un contesto d'ingresso da trunk (from-trunk, from-pstn o, con le chiamate in uscita attive, from-aptiva, che verso l'esterno apre solo la rotta dedicata), come quello di qualunque operatore. Con un trunk SIP il centralino non deve esporre SIP in chiaro su Internet; dove puoi scegliere, IAX2 è la via più semplice, perché ogni chiamata è autenticata con la password del trunk. Le credenziali le rilascia Aptiva e, se sospetti un problema, le rigeneriamo su richiesta. Con le chiamate in uscita attive valgono anche le due accortezze della sezione Una configurazione sicura, in breve.

Errori tipici su FreePBX#

Gli errori del collegamento su FreePBX sono quasi sempre di configurazione del trunk, e ognuno ha una firma riconoscibile. Per i sintomi comuni a tutti i centralini (audio a senso unico, la chiamata cade con la cifratura, il numero del chiamante non compare) vale la sezione Problemi comuni della guida generale.

La registrazione IAX2 non arriva. Nell'ordine: mancano encryption=yes e forceencryption=yes (dalla nostra parte la cifratura è forzata); il «Trunk Name» della sezione Outgoing non è <UTENTE>; la Register String ha un refuso o non ha la porta.

La registrazione SIP non arriva. SSL Method diverso da sslv23 (con Default FreePBX 17 negozia solo TLS 1.0, che Aptiva rifiuta; su build più vecchie tlsv1_1 e tlsv1_2 impediscono il caricamento del trasporto); una modifica al trasporto applicata con un reload invece di fwconsole restart; la porta non è quella del foglio di configurazione; il nome <SERVER> non viene risolto perché la build di Asterisk è senza resolver DNS.

L'agente non risponde e la chiamata cade subito. Compilati From User oppure Outbound CallerID, o CID Options su Force Trunk CID: il numero del chiamante è stato sostituito da un valore che non è un numero di telefono e Aptiva rifiuta la chiamata. Stesso sintomo per una chiamata con numero nascosto (oggi l'agente non le gestisce: dal centralino risultano occupato) e per una prova fatta da un interno del centralino, che è disponibile su richiesta.

Il trasferimento viene rifiutato. Su SIP quasi sempre manca Match (Permit); su IAX2 il context del trunk non è from-trunk (o from-aptiva, se hai attivato le chiamate in uscita), quindi la chiamata non consulta le tue rotte, oppure il trunk è type=peer invece di friend.

Il trasferimento squilla sull'interno sbagliato o su un gruppo. Ha vinto una tua Inbound Route per CID: vedi la precedenza delle rotte qui sopra e il formato del numero.

Il trasferimento torna all'agente invece di squillare. Due cause. Nel log di Asterisk cerca la riga Catch-All DID Match - Found <interno> - You probably want a DID for this: significa che nessuna rotta dedicata ha agganciato il numero, quindi controlla che il DID Number della rotta sia scritto esattamente come la voce di rubrica. Oppure il gruppo o la coda in rubrica ha l'agente come destinazione di mancata risposta: usa gruppi distinti.

L'agente presenta la chiamata alla segreteria. La segreteria o il Follow Me dell'interno è scattato prima della fine del tempo di squillo dell'agente, che lo conta come una risposta. Accorcia il tempo di squillo dell'agente o allunga quello dell'interno.

Una chiamata in uscita dell'agente non parte o esce con un numero diverso da quello dell'azienda. Nell'ordine: il contesto del trunk Aptiva è from-aptiva; il numero corrisponde a un Dial Pattern di Aptiva-uscita e N è l'id giusto (dialplan show outrt-N); Route CID compilato con Override Extension su Yes. Se invece l'agente sente o parla sopra un messaggio di linee occupate, sulla rotta manca Optional Destination on Congestion. Vedi i sintomi nella sezione sulle chiamate in uscita; se non torna, scrivici con l'ora della prova.

L'audio è μ-law invece di A-law. Non hai selezionato codec nella scheda Codecs e FreePBX ha scritto allow=ulaw da solo. Funziona, ma seleziona alaw per evitare una transcodifica inutile.

Note per FreePBX 16 e versioni precedenti#

FreePBX 16 e le versioni precedenti si configurano con gli stessi campi della 17: le differenze stanno nella piattaforma sottostante, non nell'interfaccia dei trunk.

• FreePBX 16 (SNG7, Asterisk fino al 20) dal 1° settembre 2026 riceve solo correzioni di sicurezza. Il trunk chan_pjsip e quello IAX2 si configurano come descritto qui. Se il tuo centralino usa ancora trunk chan_sip, per il collegamento con Aptiva crea comunque un trunk chan_pjsip: chan_sip è stato rimosso da Asterisk 21 e la FAQ della versione 17 lo dichiara non raccomandato.
• FreePBX 15, 14 e precedenti funzionano (le note «sul campo» di questa guida vengono proprio da un'installazione di quella generazione), ma è qui che gli inciampi del trasporto TLS si fanno sentire di più: valori di SSL Method che la build non riconosce (sslv23 resta la scelta giusta), fwconsole restart per modificare un trasporto esistente, e build di Asterisk senza resolver DNS. Su queste versioni IAX2 è la scelta più semplice, perché nessuno dei tre inciampi la riguarda.

Passi successivi#

1. Richiedi le credenziali del collegamento indicando il protocollo (IAX2 consigliato), la versione di FreePBX, il numero da collegare e gli interni o i gruppi a cui l'agente deve poter trasferire. L'attivazione del collegamento non ha costi.
2. Leggi la guida generale al collegamento per requisiti, sicurezza, costi e problemi comuni, e la guida sul trasferimento assistito per configurare rubrica, presentazione e messaggio di mancata risposta (impostalo sempre: è ciò che fa riprendere la conversazione con il chiamante quando nessuno risponde).
3. Scopri cosa può fare l'agente una volta collegato nella pagina Centralino AI.