NethVoice e agente vocale AI: collegare il trunk

Per collegare NethVoice all'agente vocale AI di Aptiva crei un trunk che si registra verso di noi e poi, con i percorsi del centralino, decidi quali chiamate mandare all'agente e su quali interni l'agente può trasferire. NethVoice su NethServer 8 è un FreePBX 16 con un'interfaccia propria e un proxy SIP davanti: le due cose da sapere in più rispetto a un FreePBX qualunque sono come si crea un trunk verso un provider che non è in elenco e cosa passa dal NethVoice Proxy e cosa no. È anche il motivo per cui, su NethVoice, la via indicata è IAX2.

Istruzioni scritte sulla documentazione ufficiale di NethVoice per NethServer 8 (modulo 1.7, FreePBX 16 su Asterisk 18). Se la tua interfaccia è diversa, scrivici: ti aiutiamo noi. Per requisiti, credenziali, sicurezza e problemi comuni a tutti i centralini vale la guida generale al collegamento del centralino; i campi del trunk, riga per riga, sono spiegati nella guida per FreePBX.

Cosa cambia in NethVoice rispetto a FreePBX#

NethVoice aggiunge a FreePBX tre cose che toccano il collegamento: un'interfaccia semplificata con un elenco chiuso di provider, un proxy SIP obbligatorio e una regola di nomenclatura per i trunk modificati dall'interfaccia avanzata.

• La procedura guidata conosce solo provider in elenco. In Configurazione → Trunk → VoIP scegli tra i «Trunk VoIP supportati», quasi tutti operatori italiani; non c'è una voce «provider generico». Per tutto il resto la documentazione rimanda all'interfaccia avanzata, cioè FreePBX, raggiungibile da Amministrazione → Avanzate.
• Il NethVoice Proxy è obbligatorio. La documentazione lo dice senza eccezioni: «NethVoice Proxy è richiesto per ogni distribuzione di NethVoice». È un proxy SIP (Kamailio) con un proxy RTP (RTPengine) che gestisce TLS, NAT e l'instradamento tra istanze: tutto il traffico SIP e RTP di NethVoice lo attraversa, e la procedura guidata lo imposta come Proxy in uscita dei trunk registrati.
• Gli aggiornamenti rigenerano i trunk della procedura guidata. Se modifichi un trunk creato dal wizard, la documentazione prescrive di rinominarlo aggiungendo Custom- al nome, «altrimenti la configurazione verrà sovrascritta durante gli aggiornamenti».

Il resto è FreePBX 16: il contesto from-trunk, le rotte in entrata, le destinazioni. Chi conosce FreePBX si orienta subito; gli altri trovano ogni campo spiegato nella guida dedicata.

Perché su NethVoice indichiamo IAX2#

Su NethVoice IAX2 è la strada più prevedibile perché non passa dal NethVoice Proxy: il proxy tratta SIP e RTP, mentre IAX2 è un protocollo diverso che l'istanza Asterisk parla direttamente con Aptiva.

• Segnalazione e audio viaggiano dall'istanza Asterisk ad Aptiva su un'unica porta UDP, direttamente: niente RTPengine in mezzo, niente NAT helper da considerare.
• La cifratura è nativa di IAX2, con chiave derivata dalla password: nessun certificato da creare, nessun trasporto TLS da preparare.
• Nessun indirizzo da autorizzare: la stessa sezione del trunk accetta le chiamate che arrivano da Aptiva, cioè i trasferimenti verso i tuoi interni.
• La porta lato NethVoice è la porta IAX (UDP) dell'istanza, che la documentazione elenca tra le porte del modulo e che leggi in Impostazioni → Firewall del cluster: il canale c'è ed è previsto dal firewall del nodo.

Quello che la documentazione non descrive è un trunk IAX2 verso un provider esterno: la procedura guidata non lo offre e la strada passa dall'interfaccia avanzata, dove FreePBX 16 espone i trunk IAX2 normalmente. Lo diciamo con la prudenza che merita: il collegamento IAX2 — trunk, registrazione, chiamata e trasferimento a un interno — è provato sul campo su FreePBX, ma su NethVoice non l'abbiamo ancora visto in esercizio. Se qualcosa non torna, scrivici.

Con SIP il trunk passerebbe dal NethVoice Proxy, con alcune impostazioni della procedura guidata da verificare sulla singola installazione. Se ti serve SIP, scrivici: lo verifichiamo insieme sulla tua installazione.

Il trunk IAX2 dall'interfaccia avanzata#

Il trunk IAX2 verso Aptiva si crea direttamente in FreePBX, da Amministrazione → Avanzate, poi Connettività → Trunk e il pulsante per aggiungere un trunk, scegliendo la tecnologia IAX2. Chiamalo Custom-Aptiva: la documentazione usa il prefisso Custom- per proteggere dagli aggiornamenti i trunk modificati dall'interfaccia avanzata, e conviene usarlo anche qui. Il nome che compare negli elenchi è questo; il secondo campo «Trunk Name», nella sezione Outgoing, è un'altra cosa e deve essere <UTENTE>.

I campi del trunk sono esattamente quelli della guida per FreePBX, sezione sul trunk IAX2, che spiega anche il perché di ogni riga: il blocco PEER Details da incollare, la Register String, USER Context e USER Details vuoti, Outbound CallerID vuoto e opzioni CID su «Allow Any CID». Le tre cose da non sbagliare sono type=friend (il trunk deve accettare anche le chiamate che arrivano da Aptiva, cioè i trasferimenti), context=from-trunk (il contesto standard dei trunk, così le chiamate da Aptiva seguono i tuoi percorsi in entrata; diventa from-aptiva se attivi le chiamate in uscita, vedi più sotto) e le due righe di cifratura (dal lato Aptiva è forzata: un trunk senza non si collega affatto). Copia server e porta dal foglio di configurazione, senza fidarti dei valori predefiniti.

Ciò che è proprio di NethVoice è poco: il percorso nell'interfaccia avanzata, il nome Custom-Aptiva e la porta IAX dell'istanza, che deve poter uscire dal firewall davanti al nodo (vedi più sotto). Poi Invia e Applica configurazione.

Per verificare, dalla CLI dell'istanza (vedi più sotto come raggiungerla) iax2 show registry deve mostrare Registered e iax2 show peers il peer <UTENTE> come OK.

I percorsi in entrata dedicati agli interni#

Per ogni interno o gruppo che l'agente deve poter far squillare crei un percorso in entrata dedicato con il numero dell'interno come numero chiamato. Il meccanismo è quello di FreePBX: quando l'agente trasferisce, Aptiva compone verso NethVoice il numero della voce di rubrica così com'è (per esempio 201), la chiamata entra dal trunk e segue i tuoi percorsi in entrata come una chiamata dall'operatore; il percorso dedicato la consegna all'interno, con il numero del chiamante originale sul display.

Hai due strade, equivalenti:

• Dall'interfaccia di NethVoice: Configurazione → Percorsi → In entrata → Crea nuovo percorso apre Visual Plan, dove imposti il pattern del numero chiamato (DID) uguale all'interno e come destinazione l'interno stesso o il gruppo.
• Dall'interfaccia avanzata: le rotte in entrata di FreePBX (Connettività, voce delle rotte in entrata), con DID Number uguale all'interno, CID Number vuoto e destinazione l'interno. Qui puoi anche aggiungere un CID name prefix come AI: per far riconoscere a chi risponde che la chiamata arriva dall'agente.

Due attenzioni sulle voci di rubrica. Se sull'interno scatta la casella vocale o un inoltro prima della fine del tempo di squillo dell'agente (predefinito 30 secondi), per l'agente «ha risposto qualcuno»: fa la presentazione alla segreteria ed esce, quindi tieni il tempo di squillo dell'agente più corto di quello della segreteria. E se in rubrica c'è un gruppo o una coda, la sua destinazione di mancata risposta, di coda piena o di fuori orario non deve essere l'agente: il trasferimento tornerebbe all'agente, che presenterebbe la chiamata a un'altra sessione dell'agente. Se ti servono entrambi i ruoli, usa gruppi distinti.

Vale poi l'avvertenza di FreePBX sulla precedenza delle rotte: una regola che filtra sul numero del chiamante batte una regola sul numero chiamato, e il trasferimento porta il numero del chiamante originale. Può quindi essere intercettato da una tua regola per chiamante ogni volta che quel chiamante arriva comunque all'agente — dal fallback di un gruppo, dal fuori orario, da un'opzione del menu — oppure perché Aptiva restituisce il numero in formato internazionale con il +, che potrebbe non coincidere con il formato in cui il tuo operatore lo consegna.

Mandare le chiamate all'agente#

Le chiamate arrivano all'agente vocale AI instradandole sul trunk Aptiva, con gli strumenti che NethVoice e FreePBX già ti danno. Il numero composto sul trunk non è vincolante: la chiamata arriva comunque al tuo agente.

• Tutte le chiamate di un numero: il percorso in entrata di quel numero con destinazione il trunk Aptiva. 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 un percorso dedicato a quel tipo di chiamante.
• Fuori orario, mancata risposta, opzione del menu: dall'interfaccia avanzata crei una rotta in uscita dedicata al solo trunk Aptiva con un numero breve che non usi altrove (per esempio 8000) e una Destinazione Varia («Destinazioni Varie» è la traduzione ufficiale di Misc Destinations) che compone quel numero. Quella destinazione la usi poi nelle condizioni temporali, come destinazione di mancata risposta di un gruppo o di una coda (non di uno che è anche in rubrica: vedi sopra), o in un'opzione dell'IVR. Nei percorsi in uscita di NethVoice (Configurazione → Percorsi → In uscita) tieni il trunk Aptiva fuori da «Nazionale», «Cellulare», «Internazionale» e «Pagamento»: serve solo alla sua rotta dedicata.

Puoi collegare più numeri, ognuno con il suo agente: ogni numero è un collegamento con le proprie credenziali, quindi un trunk distinto su NethVoice, ed è il trunk usato a decidere quale agente risponde, non il numero composto.

Una precisazione che evita una prova sbagliata: una chiamata da un interno di NethVoice 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 chiamando il tuo numero da un telefono esterno.

Chiamate in uscita dal tuo numero con NethVoice#

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 NethVoice dal trunk Custom-Aptiva, con il numero da chiamare in formato internazionale (per esempio +393331234567), e NethVoice la fa uscire dal trunk del tuo operatore, quello creato dalla procedura guidata, 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, la configurazione è la stessa di FreePBX, perché l'interfaccia avanzata di NethVoice è FreePBX: la trovi, campo per campo e con il perché di ogni scelta, nella guida per FreePBX, sezione sulle chiamate in uscita. È in tre parti:

1. Una Outbound Route dedicata, creata dall'interfaccia avanzata, con una riga per lunghezza di numero: lascia uscire solo cellulari, fissi e VoIP italiani, presenta numero e nome della tua azienda e, con il campo Optional Destination on Congestion su Terminate Call → Congestion, chiude senza rispondere le chiamate che non possono uscire, così l'agente non parla sopra il messaggio di linee occupate.
2. Un contesto di due righe in extensions_custom.conf, from-aptiva, che manda a quella rotta i numeri con +39 arrivati dal trunk Aptiva e lascia i trasferimenti agli interni esattamente com'erano.
3. Il Maximum Channels del trunk del tuo operatore, tetto delle chiamate in uscita contemporanee, da tenere sotto il numero di linee del contratto per lasciarne sempre di libere alle chiamate in arrivo.

I percorsi in uscita di NethVoice («Nazionale», «Cellulare», «Internazionale», «Pagamento») non c'entrano: il trunk Aptiva ne resta fuori, e l'uscita dell'agente passa solo dalla rotta dedicata. Quello che cambia su NethVoice è poco, ed è qui sotto.

Cosa cambia su NethVoice#

• Dove si lavora. Outbound Route e trunk stanno nell'interfaccia avanzata, Amministrazione → Avanzate e poi Connettività: la rotta Aptiva-uscita la crei lì, con i Dial Patterns della guida FreePBX, e lì leggi l'id=N della rotta dall'URL della pagina di modifica.
• Dove sta il file. In NethVoice l'Asterisk dell'istanza gira nel container freepbx, e la sua configurazione è nel volume asterisk, montato nel container come /etc/asterisk: extensions_custom.conf va scritto lì, non sull'host. Per arrivarci, dal nodo, runagent -m nethvoice1 (con il nome della tua istanza) entra nell'ambiente del modulo e podman exec -it freepbx bash apre una shell nel container, dove il file è /etc/asterisk/extensions_custom.conf. Il volume sopravvive agli aggiornamenti del modulo; la documentazione di NethVoice non descrive le personalizzazioni del dialplan, quindi dopo il primo aggiornamento vale la pena controllare che il contesto sia ancora caricato.
• Il contesto del trunk. Nei PEER Details di Custom-Aptiva cambi context=from-trunk in context=from-aptiva, dopo aver scritto il file. Il prefisso Custom- è ciò che protegge questa modifica dagli aggiornamenti.
• Il trunk dell'operatore. Nella Trunk Sequence della rotta metti il trunk creato dalla procedura guidata per il tuo operatore: il suo Proxy in uscita (il NethVoice Proxy) è un'impostazione del trunk stesso e vale anche per queste chiamate. Il Maximum Channels è un campo di quel trunk e conta solo le chiamate in uscita, degli interni e dell'agente, non quelle in arrivo dei tuoi clienti: tienilo sotto il numero di linee del contratto, così ne restano sempre di libere per chi ti chiama anche durante una campagna. Per la regola di NethVoice un trunk della procedura guidata modificato dall'interfaccia avanzata andrebbe rinominato con il prefisso Custom-, altrimenti un aggiornamento può riportarlo com'era: se preferisci non rinominarlo, imposta il valore e ricontrollalo dopo ogni aggiornamento del modulo.
• Applicare e verificare. Applica configurazione dall'interfaccia (o fwconsole reload dall'ambiente del modulo) ricarica anche il file custom. Poi, sempre dall'ambiente del modulo, asterisk -rvvvvvv e:

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.

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. I sintomi tipici sono quelli della guida FreePBX, sezione La prima prova: la chiamata torna all'agente (il trunk è rimasto su from-trunk), viene rifiutata (il numero non corrisponde a nessun Dial Pattern, o N non è l'id giusto), 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). Su NethVoice se ne aggiunge uno: dialplan show from-aptiva non mostra nulla significa che il file è finito fuori dal volume dell'istanza, per esempio sull'host invece che nel container.

Una configurazione sicura, in breve#

Valgono le garanzie della configurazione FreePBX, riassunte nella sua sezione Una configurazione sicura, in breve: dal trunk Aptiva escono solo cellulari, fissi e VoIP italiani, della lunghezza giusta, con l'identità della tua azienda e dentro il tetto del Maximum Channels del trunk del tuo operatore. Su NethVoice il trunk è IAX2, quindi ogni chiamata che arriva da Aptiva è autenticata con la password del collegamento e la domanda sul trasporto non si pone. Resta un'accortezza dalla tua parte, che vale 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.

Firewall su NethServer 8#

Il collegamento con Aptiva non richiede porte aperte in ingresso, perché è NethVoice a registrarsi verso di noi; le regole del firewall di NethServer 8 che contano sono quelle già previste dalla documentazione per il funzionamento normale di NethVoice.

• Nodo con IP pubblico diretto. «Il firewall perimetrale NS8 apre automaticamente tutte le porte necessarie», compresa la porta IAX dell'istanza. Non devi fare nulla.
• Nodo dietro un firewall. Lascia uscire il traffico della porta IAX (UDP) dell'istanza, che leggi in Impostazioni → Firewall della pagina di amministrazione del cluster. Non servono regole in ingresso per il collegamento.
• NAT helper e SIP ALG. La documentazione raccomanda di disabilitarli sui firewall per il normale funzionamento di NethVoice; il trunk IAX2 verso Aptiva non ne è toccato, perché segnalazione e audio viaggiano insieme su una sola porta.
• Protezioni automatiche. Se davanti al nodo hai un sistema che blocca gli indirizzi dopo tentativi falliti (fail2ban, IP blacklist), metti nelle sue eccezioni il nome <SERVER> (con IAX2 è questo l'indirizzo che conta; con SIP sarebbe <INDIRIZZO_APTIVA>): da lì arrivano i trasferimenti e i controlli del trunk, e un blocco li farebbe fallire.

Il collegamento è cifrato in entrambe le direzioni ed è NethVoice a collegarsi ad Aptiva, quindi non c'è nessuna porta da aprire. Il trunk Aptiva resta in un contesto d'ingresso da trunk (from-trunk o, con le chiamate in uscita attive, from-aptiva, che verso l'esterno apre solo la rotta dedicata), come quello di qualunque operatore, e il centralino non deve esporre SIP in chiaro su Internet: con IAX2, che è la via indicata su NethVoice, 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 vale anche l'accortezza della sezione Una configurazione sicura, in breve. Il resto è nella guida generale, sezione Sicurezza del collegamento.

Verifiche e problemi tipici su NethVoice#

Le verifiche su NethVoice si fanno dalla panoramica dei trunk di FreePBX e dalla CLI di Asterisk dentro l'istanza, raggiungibile come indica la documentazione «Verifiche rapide».

• Stato del trunk: Amministrazione → Avanzate, panoramica dei trunk (registrato o no).
• CLI di Asterisk: dal nodo, runagent -m nethvoice1 (con il nome della tua istanza) e poi asterisk -rvvvvvv. Da lì iax2 show registry, iax2 show peers e, durante una prova, iax2 set debug on (poi off).

I problemi propri di NethVoice:

Il trunk IAX2 non si registra. Nell'ordine: mancano le righe di cifratura; il «Trunk Name» della sezione Outgoing non è <UTENTE>; la porta IAX dell'istanza è bloccata in uscita da un firewall davanti al nodo.

L'agente non risponde e la chiamata cade subito. Il numero del chiamante è stato sostituito (Outbound CallerID compilato o opzioni CID diverse da «Allow Any CID»), oppure la chiamata è con numero nascosto, che oggi l'agente non gestisce (dal centralino risulta occupato), oppure è una prova fatta da un interno.

Il trasferimento non arriva all'interno. Manca il percorso in entrata dedicato, oppure lo ha intercettato una regola per numero del chiamante; se il trasferimento viene rifiutato del tutto, il context del trunk non è from-trunk (o from-aptiva, se hai attivato le chiamate in uscita) o il trunk è type=peer invece di friend. Le firme nei log e i casi sono quelli della guida per FreePBX.

Il trasferimento torna all'agente. Nessun percorso dedicato ha agganciato il numero (controlla che il numero chiamato del percorso 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.

Una chiamata in uscita dell'agente non parte o esce con un numero diverso da quello dell'azienda. Nell'ordine: il contesto del trunk Custom-Aptiva è from-aptiva; dialplan show from-aptiva mostra le due righe (se non mostra nulla, il file non è nel volume dell'istanza); 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 la sezione sulle chiamate in uscita; se non torna, scrivici con l'ora della prova. Dopo un aggiornamento del modulo NethVoice vale la pena rifare una chiamata di prova e ricontrollare il Maximum Channels del trunk dell'operatore.

L'agente presenta la chiamata alla casella vocale. La segreteria o l'inoltro 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.

Audio a senso unico. Con IAX2 non si presenta, perché audio e segnalazione viaggiano sulla stessa porta. Se lo vedi, verifica che sia proprio il trunk Aptiva a essere coinvolto e non un altro percorso della chiamata; il resto è nella sezione Problemi comuni della guida generale.

Nota su NethVoice 14 e versioni precedenti#

NethVoice 14 su NethServer 7 è la stessa base FreePBX, senza il NethVoice Proxy e con un lessico diverso: i trunk si chiamano Fasci, i percorsi Rotte in Entrata e Rotte in Uscita. La configurazione del trunk è quella della guida per FreePBX, e valgono le sue note per le versioni meno recenti. Se sei su una di queste versioni, scrivici indicando quale: ti seguiamo noi.

Passi successivi#

1. Richiedi le credenziali del collegamento indicando il protocollo (IAX2), la versione di NethVoice, il numero da collegare e gli interni o i gruppi a cui l'agente deve poter trasferire. L'attivazione non ha costi.
2. Leggi la guida generale al collegamento per requisiti, sicurezza, costi e problemi comuni, e la guida sul trasferimento assistito per rubrica, tempo di squillo, 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.