3CX e agente vocale AI: collegare il trunk SIP

Un centralino 3CX V20 si collega all'agente vocale AI di Aptiva con un trunk SIP generico con registrazione, su TLS e con audio cifrato SRTP. Tieni il tuo numero e il tuo 3CX: le chiamate che decidi tu (tutte, solo fuori orario, quelle senza risposta, un tasto dell'IVR) escono su quel trunk verso l'agente, e quando serve l'agente le riporta a un interno o a una coda del tuo centralino, presentando la chiamata a chi risponde con l'istruzione che imposti.

Questa guida copre solo ciò che è proprio di 3CX: template, campi, riconoscimento del numero chiamato, regola in uscita, licenze ed errori tipici. Requisiti, credenziali, sicurezza e problemi comuni a tutti i centralini stanno nella guida generale al collegamento del centralino.

Cosa serve prima di iniziare#

Per collegare 3CX ad Aptiva servono un'edizione che accetti trunk generici, le credenziali del collegamento e il Secure SIP attivo.

Istruzioni scritte sulla documentazione ufficiale di 3CX V20 Update 9. Se la tua interfaccia è diversa, scrivici: ti aiutiamo noi.

• Edizione. Basic, PRO o AI, che accettano il trunk generico (il perché è nella sezione sulle licenze). Per la 4SC Free, la Basic gratuita self-hosted, la documentazione non dice se accetti trunk generici: se la usi, scrivici.
• Credenziali. Utente, password, server, porta e l'indirizzo da autorizzare te li mandiamo noi in un foglio di configurazione: Come richiedere le credenziali.
• Secure SIP. 3CX avvia il TLS sui trunk solo se il Secure SIP è attivo: sta in Admin > Advanced > Secure SIP ed è attivo di default.
• Rete. È il tuo 3CX a registrarsi da noi: niente porte aperte né IP statico, basta che il centralino esca verso Internet. Disattiva il SIP ALG sul router, come 3CX indica per ogni installazione (Cosa ti serve).

Nei blocchi che seguono i valori tra parentesi angolari, come <UTENTE> e <SERVER>, sono quelli del foglio di configurazione che ti mandiamo.

Come creare il trunk verso Aptiva#

Il trunk verso Aptiva è un Generic VoIP Provider (Registration): 3CX si registra da noi con le credenziali del collegamento, come farebbe con un operatore telefonico.

1. Vai in Admin > Voice & Chat > Add Trunk.
2. Nel selettore del Paese scegli la voce generica e come provider Generic VoIP Provider (Registration). Lascia attiva l'opzione Create an outbound rule for this SIP Trunk: la sistemiamo dopo.
3. Compila la scheda General:

Name                       Aptiva
Default route              <una destinazione interna, per esempio la casella vocale>
Type of authentication     Registration/Account based
Registrar/Server           <SERVER>
Port                       <PORTA>        (Auto-discovery disattivato)
Outbound Proxy             vuoto
Authentication ID          <UTENTE>
Authentication Password    <PASSWORD>
Main Trunk Number          <il numero che userai per chiamare l'agente, es. 7701>

Nel Main Trunk Number non va il tuo numero pubblico, che appartiene al trunk dell'operatore, ma un valore tecnico come il numero della regola in uscita: fa da identità di riserva in uscita e da criterio di riconoscimento in ingresso. Il Default route è spiegato nella sezione sulla sicurezza.

4. Nella scheda DID Numbers aggiungi gli interni e gli interni di sistema che l'agente deve poter raggiungere (li assegni più avanti).
5. Nella scheda Options imposta trasporto, cifratura e codec come descritto qui sotto.
6. Save. L'indicatore del trunk in Admin > Voice & Chat diventa verde quando la registrazione riesce e resta rosso finché non è registrato.

Trasporto TLS e audio SRTP#

Il trunk Aptiva accetta solo SIP su TLS con audio SRTP: SIP in chiaro non è previsto. Nella scheda Options del trunk:

Transport Protocol     TLS
Certificato radice     ISRG Root X1 (la radice di Let's Encrypt)
SRTP Mode              Enforced
Number of SIM Calls    vedi «Licenze e chiamate simultanee»
Allow inbound calls    attivo
Allow outbound calls   attivo

Con il trasporto TLS 3CX chiede il certificato radice dell'autorità che ha emesso il certificato del provider. Il nostro è un certificato pubblico di Let's Encrypt che si rinnova automaticamente ogni pochi mesi: carica la radice ISRG Root X1, non il certificato del server, che cambierebbe al primo rinnovo. 3CX non accetta certificati wildcard e vuole che il certificato coincida con il nome del server: il nostro è intestato proprio al nome che trovi nel foglio di configurazione, quindi la verifica va a buon fine. Copia server e porta dal foglio di configurazione, senza fidarti dei valori predefiniti, e lascia disattivato l'Auto-discovery: non pubblichiamo record NAPTR o SRV.

SRTP Mode = Enforced, non Enabled: sul collegamento non esiste un ripiego in chiaro, quindi una chiamata negoziata senza SRTP non parte in chiaro: secondo la documentazione 3CX cade, oppure resta senza audio.

Codec: G.711 A-law in cima#

Nel campo Codec Priority lascia solo G.711 A-law e G.711 U-law, nell'ordine, e rimuovi gli altri: il collegamento Aptiva usa solo G.711 (perché G.711 e non Opus). Sulle chiamate in ingresso 3CX usa il primo codec della INVITE ricevuta che sia abilitato sul trunk: conta che i due G.711 ci siano, non il loro ordine.

Il numero del chiamante deve arrivare intatto#

L'agente deve ricevere il numero di chi sta chiamando: lo usa per riconoscere il contatto e lo presenta a chi risponde al trasferimento. Su 3CX una chiamata entrante rilanciata su un trunk esce con il caller ID della catena di priorità (Outbound Caller ID della regola, dell'interno, del trunk, infine il Main Trunk Number), cioè con un tuo numero al posto di quello del chiamante.

La leva documentata è la variabile OriginatorCallerID nella scheda Outbound Parameters del trunk Aptiva: mappa From : User Part su OriginatorCallerID. La variabile porta il numero del chiamante della gamba entrante, a meno che la regola in uscita verso Aptiva non abbia un Outbound Caller ID valorizzato, che avrebbe la precedenza: lascialo vuoto. Il nostro lato accetta qualunque numero di telefono e rifiuta solo un valore che non è un numero, per esempio il nome del trunk.

Come 3CX riconosce il numero chiamato#

Quando l'agente trasferisce una chiamata a un interno, la chiamata arriva sul trunk Aptiva come nuova chiamata in ingresso con il numero dell'interno come numero chiamato: non usiamo SIP REFER, quindi il trasferimento funziona anche dove il REFER dal trunk non è accettato. 3CX associa la chiamata al trunk grazie al parametro rinstance della registrazione, che rimandiamo nella Request-URI dell'INVITE; poi legge il numero chiamato (CalledNum, da RURI : User Part o da To : User Part: Aptiva mette l'interno in entrambi) e lo confronta con i DID del trunk.

La regola è una sola: se CalledNum coincide esattamente con un DID assegnato, la chiamata va alla sua destinazione; altrimenti finisce sulla Default route del trunk, e un numero non censito non raggiunge l'interno omonimo (a differenza di Asterisk). Nel log delle attività il numero chiamato compare come called=XXXXX: è dove verificare che arrivi come lo hai scritto tra i DID.

Un DID per ogni interno raggiungibile dall'agente#

Ogni interno, coda, gruppo di squillo o IVR che l'agente deve poter chiamare va dichiarato come DID del trunk Aptiva e assegnato alla sua destinazione. Il valore del DID è il numero stesso: per l'interno 201 il DID è 201, e la voce di rubrica dell'agente avrà lo stesso numero (da 1 a 5 cifre).

1. Voice & Chat > trunk Aptiva > DID Numbers > +Add: aggiungi 201, 202, e così via. Il confronto è esatto: nessun prefisso, nessun formato internazionale.
2. Assegnazione a un utente: Admin > Users > utente > General > Assigned DID Number(s).
3. Assegnazione a coda, gruppo o IVR: Admin > Call Handling > interno di sistema > Assigned DID Number(s).

Due accortezze: non usare lo stesso DID su due trunk, e ricorda che un DID non assegnato manda la chiamata sulla Default route. La prima è una buona pratica più che un vincolo: 3CX rifiuta la chiamata quando deve riconoscere il trunk dal numero chiamato e trova quel DID su due trunk, mentre le chiamate Aptiva le riconosce prima, dal parametro rinstance; tenere i DID distinti evita comunque ambiguità. Censisci solo gli interni in rubrica all'agente, tre o quattro per uno studio tipico. L'accortezza conta se colleghi più numeri: ogni numero collegato ad Aptiva ha le sue credenziali e quindi il suo trunk su 3CX, ed è meglio non dichiarare lo stesso interno come DID su entrambi. Puoi collegare più numeri, ognuno con il suo agente: scrivici e ti indichiamo come organizzare DID e rubrica.

Quando puoi, fai puntare la rubrica dell'agente a interni di sistema (una coda o un gruppo di squillo) invece che a singoli utenti: non fanno chiamate verso l'esterno, quindi evitano l'effetto collaterale descritto qui sotto, e un gruppo fa squillare più telefoni con una sola voce di rubrica. Due attenzioni sui tempi:

• Il gruppo o la coda in rubrica non deve rimandare all'agente. Se la sua destinazione per le chiamate senza risposta o fuori orario è il numero che porta all'agente, il trasferimento torna all'agente stesso, che presenta la chiamata a un'altra sessione dell'agente. Se ti servono entrambi i ruoli, usa due gruppi distinti. Il Ring Time di un ring group è di 20 secondi per default.
• La casella vocale conta come risposta. Se sull'interno scatta la segreteria o un inoltro prima che finisca il tempo di squillo dell'agente (30 secondi per default), per l'agente «ha risposto qualcuno»: fa la presentazione alla segreteria ed esce. Tieni il tempo di squillo dell'agente più corto di quello della casella vocale, e imposta sempre anche il messaggio di mancata risposta, che fa riprendere la conversazione con il chiamante quando nessuno risponde.

L'effetto sul caller ID in uscita e come evitarlo#

Il manuale 3CX dice che «se un interno ha un DID assegnato, per default lo usa come caller ID»: l'utente 201 con il DID tecnico 201 potrebbe uscire verso l'operatore con caller ID 201, che l'operatore rifiuterebbe o sostituirebbe. Per evitarlo, imposta un caller ID esplicito, che nella catena di priorità documentata per le chiamate in uscita dovrebbe prevalere su quel valore predefinito:

• Admin > Users > utente > General > Outbound Caller ID, il numero pubblico con cui quell'utente si presenta;
• oppure, se tutti presentano lo stesso numero, l'Outbound Caller ID della regola in uscita verso il tuo operatore, primo livello della catena.

Dopo l'assegnazione dei DID, fai una chiamata di prova dall'interno verso il tuo cellulare e controlla il numero che compare. Tieni disattivata l'opzione Allow Users to Select Outbound Route & Caller ID (Admin > System > Options > Apps), com'è di default: con la V20 Update 10, oggi in alpha, permetterà all'utente di scegliere il DID di uscita nel selettore «Call using», e scegliendo 201 la sua chiamata uscirebbe sul trunk Aptiva.

La regola in uscita per raggiungere l'agente#

Le chiamate arrivano all'agente componendo un numero che una Outbound Rule manda sul trunk Aptiva. Il numero non è vincolante (la chiamata arriva comunque al tuo agente): usa un valore che non sia un interno né l'inizio di un numero reale, per esempio 7701. In Outbound Rules > Add della console di amministrazione (o modificando la regola creata con il trunk):

Name                                     Verso l'agente Aptiva
Calls to numbers starting with prefix    7701
Calls to numbers with a length of        4
Calls from extension(s)                  vuoto (tutti gli interni)
Calls from departments                   vuoto
Make outbound calls on – prima route     trunk Aptiva
  Strip Digits                           0
  Prepend                                vuoto
  Outbound Caller ID                     vuoto
Route successive                         Block Calls

Tre dettagli decidono se la regola funziona.

• Non limitarla agli interni. Le chiamate che partono da IVR, code, gruppi di squillo, Default route o inoltri sono generate da interni di sistema e, per l'esperienza riportata sul forum 3CX, una regola ristretta a «Calls from extension(s)» può non attivarsi per loro: nel log delle attività il sintomo è un messaggio che dice che il chiamante non è nell'elenco degli interni ammessi dalla regola.
• Mettila in cima. Le regole si valutano dall'alto in basso e la prima corrispondente vince; quelle nuove finiscono in fondo e si spostano con Move Up. Se una regola generica sull'operatore la precede, 7701 uscirebbe verso l'operatore.
• Outbound Caller ID vuoto, per il motivo spiegato nella sezione sul numero del chiamante.

3CX salta le route su trunk non registrati: finché il trunk Aptiva è rosso la regola non porta da nessuna parte.

Le destinazioni che la usano#

In V20 gli orari d'ufficio sono per dipartimento (Admin Console > Office hours) e le destinazioni in orario e fuori orario si impostano sulla destinazione della chiamata, non sul trunk. Tutte le vie che seguono compongono 7701 come «numero esterno» e passano dalla regola in uscita:

Un gruppo o una coda che manda le chiamate all'agente non deve essere anche una voce della rubrica dell'agente (vedi la sezione sui DID). Se scegli «tutte le chiamate», tieni conto che oggi l'agente non gestisce le chiamate con numero nascosto: vengono rifiutate e dal centralino si vedono come occupato. Instrada altrove le chiamate anonime: la via documentata da 3CX è la CID Blacklist con la voce *nonymous, che però le blocca; se preferisci portarle a una coda o alla casella vocale invece di bloccarle, verifichiamo insieme la strada sulla tua versione.

Chiamate in uscita dell'agente#

Con il trunk collegato, l'agente vocale AI può anche chiamare i tuoi contatti mostrando il numero della tua azienda, per campagne e richiami: la chiamata arriva a 3CX dal trunk Aptiva, con il numero da chiamare in formato internazionale, e 3CX la fa uscire dal trunk del tuo operatore con il tuo piano tariffario. I requisiti che valgono per ogni centralino — solo cellulari, fissi e VoIP italiani, identità dell'azienda, limite di chiamate in uscita del trunk dell'operatore — sono nella guida generale, sezione Chiamate in uscita dal tuo numero.

Su 3CX questa parte non la descriviamo passo per passo: la documentazione del produttore non copre il caso di un numero variabile che arriva da un trunk e deve uscire verso l'operatore. La verifichiamo insieme sulla tua edizione, su richiesta, fino alla prima prova verso il tuo cellulare: scrivici, o indicalo quando richiedi le credenziali.

Sicurezza: Default route e IP Blacklist#

Sul fronte della sicurezza il collegamento chiede poco. È il tuo 3CX a collegarsi ad Aptiva, quindi non c'è nessuna porta da aprire sul firewall; segnalazione e audio viaggiano cifrati, con SIP su TLS e SRTP; le credenziali le rilasciamo noi e, se sospetti un problema, le rigeneriamo. Su 3CX restano due impostazioni.

• Default route su una destinazione interna, come per qualunque trunk: la casella vocale, un IVR o un interno. Lì arrivano le chiamate dal trunk il cui numero chiamato non corrisponde a un DID assegnato.
• Indirizzo Aptiva tra le eccezioni della IP Blacklist. Da quell'indirizzo arrivano i trasferimenti: se l'anti-hacking di 3CX o la Automatic Global IP Blacklist (Admin > Advanced > Anti-Hacking) lo bloccassero, i trasferimenti non arriverebbero più. Autorizzalo in Admin > Advanced > IP Blacklist > Add > Add single IP Address: indirizzo <INDIRIZZO_APTIVA>, Action = Allow, una descrizione, OK.

Il quadro completo è nella guida generale, sezione Sicurezza del collegamento.

Licenze e chiamate simultanee#

Le edizioni commerciali di 3CX (Basic, PRO e AI) si pagano per chiamate simultanee (SC), interne comprese, con un canone annuo per sistema che parte da 8 SC. Per il collegamento ad Aptiva contano due cose.

1. SMB Free non è utilizzabile. Con la V20 Update 10, annunciata a settembre 2026 e oggi in alpha, 3CX divide i template di trunk in «3CX Tested», «VoIP Provider Tested» e «Community», e conferma che «i sistemi 3CX SMB continuano a funzionare solo con template 3CX Tested». Aptiva oggi si configura con il template generico, quindi serve Basic, PRO o AI. Per la 4SC Free, la Basic gratuita self-hosted, la documentazione non dice se accetti il trunk generico.
2. Due conteggi da tenere separati. Sulla licenza, una chiamata affidata all'agente occupa due chiamate simultanee mentre il chiamante parla con l'agente (la gamba in entrata dal tuo operatore e la gamba verso Aptiva) e tre durante la conversazione trasferita, quando si aggiunge la gamba di ritorno verso l'interno. Sul solo trunk Aptiva, cioè nel campo Number of SIM Calls, la stessa chiamata ne occupa una, e due durante il trasferimento.

3CX non assiste nella configurazione di provider non supportati: per il collegamento Aptiva il supporto lo diamo noi, senza costi di attivazione. Il tempo in cui l'agente è attivo costa 1 credito al minuto e la conversazione dopo il trasferimento costa 0,25 crediti al minuto (Quanto costa).

Aptiva o l'AI Receptionist nativa di 3CX?#

3CX ha una propria AI Receptionist, che cresce a ogni release: se stai valutando entrambe le strade, ecco i fatti che contano, presi dalla documentazione 3CX a settembre 2026.

Se hai già la AI Edition e ti bastano smistamento e risposte dalla knowledge base dentro 3CX, l'AI Receptionist nativa è la via più corta; Aptiva conviene quando vuoi che chi risponde sappia a voce chi chiama e perché, o quando l'agente deve lavorare sull'agenda e sul CRM. Come suona nella pratica lo racconta la guida sul trasferimento assistito.

Problemi tipici su 3CX#

Qui trovi solo i sintomi propri di 3CX; audio a senso unico, problemi di rete e gli altri casi comuni sono in Problemi comuni della guida generale.

Il trunk resta rosso#

Controlla nell'ordine: Secure SIP attivo (senza, 3CX non avvia il TLS); porta copiata dal foglio e Auto-discovery disattivato; radice ISRG Root X1 caricata; Authentication ID identico a <UTENTE> (3CX non accetta due trunk con lo stesso Auth ID). Poi esegui Check SIP Trunk sul trunk: la fase Trunk Analysis verifica DNS e registrazione.

Il trasferimento finisce sulla Default route#

Il numero chiamato non ha trovato un DID assegnato. Alza il Logging Level (Admin > Dashboard > Activity logs > Settings) e cerca called=: il valore deve coincidere esattamente con il DID inserito. Se coincide, il DID non è assegnato a nessuna destinazione; se non coincide, controlla da quale campo CalledNum viene letto negli Inbound Parameters.

Il trasferimento torna all'agente#

La coda o il gruppo in rubrica ha come destinazione di mancata risposta o fuori orario il numero che porta all'agente: cambiala, o usa un gruppo distinto per le chiamate da passare all'agente.

La chiamata viene rifiutata dopo l'aggiunta di un DID#

Se 201 esiste anche come DID dell'operatore o di un altro trunk, 3CX può rifiutare la chiamata quando riconosce il trunk dal numero chiamato. Con Aptiva il trunk viene riconosciuto prima, dal rinstance, ma togli comunque il doppione: i DID vanno tenuti distinti fra i trunk.

La coda o l'IVR non riescono a chiamare l'agente#

La regola in uscita è limitata agli interni oppure sta sotto una regola più generica. Nel log delle attività cerca i messaggi che gli utenti riportano sul forum 3CX: il chiamante non è nell'elenco degli interni ammessi (regola ristretta) oppure il numero non corrisponde a nessuna regola in uscita (regola mancante o prefisso diverso). Togli le restrizioni su interni e dipartimenti e sposta la regola in cima con Move Up.

L'agente non risponde o non riconosce il chiamante#

Se il trunk è verde ma l'agente non risponde, il nostro lato sta rifiutando la chiamata perché il numero del chiamante non è un numero di telefono: controlla la mappatura From : User Part = OriginatorCallerID e l'Outbound Caller ID vuoto sulla regola. Se succede solo con alcune chiamate, sono chiamate con numero nascosto, che oggi l'agente non gestisce.

«600 Busy Everywhere» sulle chiamate in ingresso#

3CX risponde 600 quando Allow inbound calls è disattivato sul trunk o quando il Number of SIM Calls è superato; oltre il limite blocca anche le uscenti. I conteggi per dimensionarlo sono nella sezione sulle licenze.

Catturare il traffico#

Admin > Dashboard > Troubleshooting > Capture: scegli l'interfaccia, avvia, riproduci il problema e premi Stop senza cambiare pagina. Se ci scrivi, allega il PCAP e il Support Info.

Passi successivi#

1. Richiedi le credenziali del collegamento indicando protocollo SIP, edizione e versione del tuo 3CX, il numero da collegare e gli interni o le code a cui l'agente deve poter trasferire.
2. Leggi la guida generale al collegamento per requisiti, sicurezza e problemi comuni, e quella sul trasferimento assistito per scrivere la presentazione che l'agente farà a chi risponde.
3. Scopri cosa fa l'agente una volta collegato nella pagina Centralino AI.