Yeastar P-Series e agente vocale AI: guida al trunk

Un centralino Yeastar P-Series (edizioni Cloud, Appliance e Software) si collega all'agente vocale AI di Aptiva con un Register Trunk su trasporto TLS e audio cifrato SRTP. Tieni il tuo numero e il tuo centralino: le chiamate che scegli tu escono sul trunk verso l'agente, e quando serve l'agente le riporta a un interno, a una coda o a un gruppo del tuo Yeastar, presentando la chiamata a chi risponde con l'istruzione che imposti.

Questa guida copre ciò che è proprio di Yeastar: trunk e opzioni Advanced, firmware minimo, Inbound Route per i trasferimenti, Outbound Route verso l'agente, whitelist dell'indirizzo Aptiva, differenze fra le edizioni e problemi 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 uno Yeastar P-Series ad Aptiva servono un firmware almeno V24.1, le credenziali del collegamento e il TLS in modalità client impostato a 1.2.

Istruzioni scritte sulla documentazione ufficiale di Yeastar P-Series V25.1 (edizioni Cloud, Appliance e Software). Se la tua interfaccia è diversa, scrivici: ti aiutiamo noi.

• Firmware. La versione di riferimento è V25.1-GA (37.24.0.30 Appliance, 83.24.0.30 Software, 84.24.0.30 Cloud, 18 agosto 2026). Il minimo è V24.1 (37.23.0.24 / 83.23.0.24 / 84.23.0.24, 14 maggio 2026), che corregge il difetto dell'audio a senso unico dopo 15 minuti sulle chiamate uscenti via trunk con SRTP. I firmware di Appliance e Software Edition non sono intercambiabili.
• Credenziali. Utente, password, server, porta e indirizzo da autorizzare te li mandiamo noi in un foglio di configurazione: Come richiedere le credenziali.
• TLS. In PBX Settings > SIP Settings, sezione TLS, sotto «When PBX acting as a Client» imposta TLS Connection Method su TLS V1.2, che Yeastar stesso consiglia rispetto alla 1.0: il nostro lato accetta TLS 1.2 e 1.3. Nella stessa sezione c'è l'interruttore generale TLS: se il trunk non si registra con Transport = TLS, controlla che sia attivo. Il nostro certificato è pubblico, emesso da Let's Encrypt e rinnovato automaticamente ogni pochi mesi. La documentazione Yeastar non descrive il caricamento di una CA radice per verificare il server di un trunk: se la tua versione lo chiede, la radice da usare è ISRG Root X1, non il certificato del server, che cambierebbe al primo rinnovo.
• Rete. È il centralino a registrarsi da noi: niente porte aperte né IP statico, basta che lo Yeastar esca verso Internet (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. Le etichette dei menu sono quelle dell'interfaccia in inglese, la lingua della documentazione ufficiale.

Come creare il Register Trunk verso Aptiva#

Il trunk verso Aptiva è un Register Trunk con template General: lo Yeastar si registra da noi con nome utente e password, come farebbe presso un operatore. Vai in Extension and Trunk > Trunk > Add e compila così:

Basic
  Name                    Aptiva
  Trunk Status            Enabled
  Select ITSP Template    General

Detailed Configuration
  Trunk Type              Register Trunk
  Transport               TLS
  Hostname/IP             <SERVER>
  Port                    <PORTA>
  Domain                  <SERVER>
  Username                <UTENTE>
  Password                <PASSWORD>
  Authentication Name     <UTENTE>
  Enable Outbound Proxy   disattivato

Copia server e porta dal foglio di configurazione, senza fidarti dei valori predefiniti. Nella scheda DIDs/DDIs ti consigliamo di aggiungere come Single DID gli interni che l'agente potrà raggiungere (per esempio 201, 202): sono i numeri chiamati che arriveranno con i trasferimenti. Sulla Cloud Edition la scheda va compilata comunque, perché un Register Trunk richiede almeno un DID; su Appliance e Software Edition è facoltativa.

Premi Save and Apply e torna in Extension and Trunk > Trunk: l'icona verde o la spunta accanto al trunk indica che la registrazione è riuscita.

Le opzioni Advanced che contano#

Nella scheda Advanced del trunk imposta cifratura, codec, limiti e intestazioni SIP:

VoIP Settings
  Qualify                     attivo
  Enable SRTP                 attivo
  T.38 Support                disattivato (come consiglia Yeastar)
  Support SIP REFER           disattivato

Call Restriction
  Call Restriction Type       Outbound Call oppure All (vedi sotto)
  Maximum Concurrent Calls    vedi sotto

Codec
  a-law, u-law                in quest'ordine; rimuovi tutti gli altri

SIP Headers > Outbound Parameters
  From User Part              Originator Caller ID

Get DID From                  Follow System (se i trasferimenti non arrivano: Invite oppure To)
Get Caller ID From            Follow System

Enable SRTP è obbligatorio: sul collegamento la cifratura dell'audio non è opzionale e non esiste un ripiego in chiaro, quindi una chiamata senza SRTP fallisce. Il Qualify manda periodicamente un SIP OPTIONS e ti dà uno stato del trunk affidabile.

Support SIP REFER resta disattivato: non usiamo SIP REFER, il trasferimento è una nuova chiamata sul collegamento, che funziona anche sui firmware precedenti a V24.1 in cui l'opzione non esiste.

Codec. Il collegamento Aptiva usa solo G.711: metti a-law per primo, che in Italia è il codec della rete, u-law come seconda scelta, e togli G.729, G.722, Opus e gli altri (perché G.711 e non Opus).

Maximum Concurrent Calls limita le chiamate contemporanee sul trunk, come consiglia la Security Guide di Yeastar; il campo accanto, Call Restriction Type, decide se il limite conta solo le chiamate in uscita («Outbound Call») o tutte («All»), e la documentazione non dice quale sia il valore predefinito. Per dimensionarlo: una chiamata affidata all'agente occupa una chiamata sul trunk mentre il chiamante parla con l'agente; durante la conversazione trasferita se ne aggiunge una seconda, di ritorno verso l'interno, che sul trunk è in ingresso: con «All» il trunk ne conta due, con «Outbound Call» dovrebbe contarne ancora una. Sul centralino nel suo insieme sono due e tre, perché c'è anche la gamba dal tuo operatore: conta se il tuo modello ha un limite di chiamate contemporanee.

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. Sul Yeastar le intestazioni di identità del trunk seguono impostazioni proprie: per Remote-Party-ID, P-Asserted-Identity e P-Preferred-Identity il valore «[Default]» applica una catena di priorità (Outbound Caller ID della route, DOD dell'interno, DOD del trunk, Username del trunk, Extension Caller ID e solo in fondo l'Originator), mentre per il From User Part la documentazione non dice cosa parta con il valore predefinito su una chiamata rilanciata da un IVR, da una coda o da un failover. Il rischio è che nel From arrivi un tuo numero o il nome utente del trunk, che non è un numero di telefono.

La leva documentata è il valore Originator Caller ID su From User Part nella sezione SIP Headers > Outbound Parameters del trunk Aptiva: Yeastar lo descrive come il numero del primo chiamante nel caso di un trasferimento, ed è quel campo a decidere cosa parte nel From. Il nostro lato accetta qualunque numero di telefono e rifiuta solo un valore che non è un numero, come il nome utente del trunk: è il primo controllo da fare quando l'agente non risponde.

L'Inbound Route che porta i trasferimenti agli interni#

Quando l'agente trasferisce, la chiamata rientra dal trunk Aptiva con il numero dell'interno come DID (una voce di rubrica da 1 a 5 cifre, mandata così com'è). Serve quindi una Inbound Route legata al solo trunk Aptiva che porti quel DID all'interno giusto; senza, la chiamata finirebbe sulla route predefinita del centralino, che di norma manda tutto a un IVR.

Vai in Call Control > Inbound Route > Add. Hai due modi documentati.

Una route per ogni destinazione (semplice, consigliata per pochi interni):

Name                   Aptiva verso interno 201
Trunk                  solo il trunk Aptiva
DID Pattern            201
Caller ID Pattern      vuoto
Default Destination    Extension 201

Ripeti per ogni interno, coda o gruppo in rubrica all'agente: la destinazione può essere anche un Ring Group o una Queue, con lo stesso numero nella voce di rubrica. Quel gruppo o quella coda non deve avere l'agente come Failover Destination né come destinazione fuori orario: il trasferimento tornerebbe all'agente stesso, che presenterebbe la chiamata a un'altra sessione dell'agente. Se ti servono entrambi i ruoli, usa due gruppi distinti. Attenzione anche alla segreteria: se sull'interno scatta la casella vocale prima che finisca il tempo di squillo dell'agente (30 secondi per default), per l'agente «ha risposto qualcuno» e fa la presentazione alla segreteria. Tieni il tempo di squillo dell'agente più corto, e imposta sempre anche il messaggio di mancata risposta, che fa riprendere la conversazione con il chiamante quando nessuno risponde.

Una sola route per tutti gli interni ammessi, con il DID Matching Mode «Match DID Pattern to Extensions»:

Name                   Aptiva verso gli interni
Trunk                  solo il trunk Aptiva
DID Matching Mode      Match DID Pattern to Extensions
DID Pattern            {{.Ext}}
Default Destination    Match Selected Extensions → gli interni che l'agente può raggiungere

La variabile {{.Ext}} rappresenta il numero dell'interno; il pattern è uno solo e non ammette . né !. L'esempio della documentazione Yeastar usa un prefisso (882{{.Ext}}); che il pattern funzioni con la sola variabile non è documentato, quindi verificalo con un trasferimento di prova. Se preferisci un prefisso, mettilo anche nelle voci di rubrica dell'agente, che restano di massimo 5 cifre: con interni a 3 cifre puoi usare 88{{.Ext}} e la voce 88201; con interni a 4 cifre il prefisso è di una cifra sola. «Match Selected Extensions» copre solo gli interni: per code e gruppi serve comunque una route dedicata come quella sopra. Esiste anche «Match DID Range to Extension Range», per mappare un intervallo di DID su un intervallo di interni della stessa ampiezza.

Tre attenzioni:

• Get DID From. Se il centralino estrae il numero chiamato dall'intestazione sbagliata, la chiamata fallisce. Aptiva mette l'interno sia nella Request-URI sia nel To, quindi «Follow System» va bene; in caso di dubbio imposta Invite (Request-URI) sul trunk Aptiva.
• Priorità. La route dedicata deve avere la precedenza sulla route predefinita e su eventuali route senza criteri, che accettano tutte le chiamate in ingresso.
• Caller ID Pattern vuoto: la chiamata di ritorno porta nel From il numero del chiamante originale, che varia a ogni chiamata. Controlla per lo stesso motivo le route per caller ID già presenti: possono intercettare il trasferimento ogni volta che un chiamante coperto da quella regola arriva comunque all'agente, per esempio dal failover di un gruppo o dal fuori orario.

Sull'interno che risponde compare il numero del chiamante originale, che il centralino può comunque riscrivere con le proprie regole di Inbound Caller ID Reformatting.

L'Outbound Route verso l'agente#

Le chiamate arrivano all'agente componendo un numero che una Outbound Route dedicata manda sul trunk Aptiva. Il numero non è vincolante (la chiamata arriva comunque al tuo agente): scegli un valore che non sia un interno né l'inizio di un numero reale, per esempio 7701. In Call Control, nella sezione delle Outbound Route, crea:

Name                          Verso l'agente Aptiva
Dial Pattern
  Pattern                     7701
  Strip                       vuoto
  Prepend                     vuoto
Trunks                        solo il trunk Aptiva
Outbound Caller ID            vuoto
Password                      Disable
Extension/Extension Group     tutti gli interni, o quelli che possono avviare la chiamata
Time Condition                Always

Le route si confrontano dalla priorità più alta alla più bassa fino alla prima corrispondenza: dopo averla creata, spostala sopra le route generiche con pattern . verso l'operatore, altrimenti sarebbero quelle a catturare 7701. Valgono le wildcard di Yeastar (X, Z, N, .): per un intervallo, 77XX. Sulle chiamate che partono da IVR, code o gruppi la documentazione non dice quale permesso di Extension/Extension Group si applichi: se una di quelle destinazioni non raggiunge l'agente mentre un interno sì, allarga gli interni abilitati.

Le destinazioni che la usano#

Ogni destinazione di tipo External Number compone 7701 e passa dalla route appena creata. Le vie documentate da Yeastar:

Un gruppo o una coda con Failover Destination verso l'agente non deve essere anche una voce della rubrica dell'agente (vedi la sezione sull'Inbound Route). 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. I Caller ID Pattern ammettono solo cifre e wildcard numeriche, quindi una route che intercetti «anonymous» non si può scrivere: rovescia la logica. Sulla Inbound Route del tuo numero che manda tutto all'agente metti come Caller ID Pattern X. (e +X., se l'operatore consegna il numero con il più), così passano solo le chiamate con un numero; sotto di essa, una route con Caller ID Pattern vuoto raccoglie le chiamate senza numero e le manda a una coda o alla casella vocale.

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 allo Yeastar dal trunk Aptiva, con il numero da chiamare in formato internazionale, e lo Yeastar 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.

Sullo Yeastar 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: Allowed IPs e limiti sul trunk#

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

L'impostazione propria di Yeastar è la whitelist dell'indirizzo Aptiva, che cambia da un'edizione all'altra. Da quell'indirizzo arrivano i trasferimenti: su Appliance e Software Edition l'Auto Defense, che blocca gli indirizzi oltre certe soglie di pacchetti, potrebbe metterlo fra i Blocked IPs, e i trasferimenti non arriverebbero più; sulla Cloud Edition l'Auto Defense non è documentata, ma i Blocked IPs esistono anche lì.

• Cloud Edition: Security > Security Rules > Allowed IPs > Add, Name «Aptiva», Type IP Address, indirizzo <INDIRIZZO_APTIVA>. Il centralino accetta sempre le connessioni da quell'indirizzo.
• Appliance e Software Edition: Security > Security Rules > Static Defense > Add, una regola con l'indirizzo <INDIRIZZO_APTIVA> e azione Accept. La documentazione non dice se una regola Accept esenti l'indirizzo dall'Auto Defense: se il trunk smette di funzionare all'improvviso, controlla comunque i Blocked IPs.
• Allowed Country IPs (Security > Security Settings): se usi la protezione per Paese, l'indirizzo Aptiva deve restare un'eccezione, con gli Allowed IPs sulla Cloud e la regola Static Defense con Accept sulle altre edizioni.
• Blocked IPs (Security > Security Rules): se il trunk smette di funzionare all'improvviso, cerca qui l'indirizzo Aptiva, sbloccalo e verifica che sia fra gli IP consentiti.

Sul trunk bastano le impostazioni già viste: Maximum Concurrent Calls dimensionato e Inbound Route legate al trunk Aptiva. Il quadro completo è nella guida generale, sezione Sicurezza del collegamento.

Cloud, Appliance e Software Edition: cosa cambia#

Il collegamento si configura allo stesso modo sulle tre edizioni; cambiano pochi dettagli documentati.

Nelle fonti consultate il trunk SIP Register non risulta legato a un piano specifico.

Hai una S-Series?#

La S-Series (S20, S50, S100, S300) è la linea precedente: S100 e S300 sono fuori vendita dal 1° luglio 2022 con fine supporto al 1° luglio 2027, mentre S20 e S50 ricevono ancora firmware (agosto 2026). Il collegamento si può fare anche lì, con questi cambiamenti:

• i trunk stanno in Settings > PBX > Trunks, nella categoria VoIP Trunk il tipo si chiama Register Trunk, il template Select Country va su General e il campo Protocol offre SIP e IAX;
• Enable SRTP e Qualify sono nella sezione Advanced; Maximum Channels (0 = illimitati) è il limite di chiamate contemporanee;
• Inbound e Outbound Route stanno in Settings > PBX > Call Control, con Member Trunks e Extensions; le Inbound Route mappano un DID su una destinazione o un intervallo di DID su un intervallo di interni (Extension Range);
• l'indirizzo Aptiva si autorizza in Settings > System > Security > Firewall Rules, con una regola Accept, Protocol BOTH, Type IP, Port 1:65535.

La S-Series offre anche IAX2, il protocollo che consigliamo per i centralini della famiglia Asterisk, ma non abbiamo verificato che l'interfaccia permetta di attivarne la cifratura: resta consigliato SIP su TLS. La P-Series non offre IAX2. Se hai una S-Series, scrivici: ti mandiamo le indicazioni per la tua versione.

Problemi tipici su Yeastar#

Qui trovi i sintomi propri dello Yeastar; audio a senso unico per motivi di rete, registrazione che non arriva e gli altri casi comuni sono in Problemi comuni della guida generale.

L'audio cade a senso unico dopo circa 15 minuti#

È il difetto delle release precedenti a V24.1 sulle chiamate uscenti via trunk SIP con SRTP, corretto nelle release notes 37.23.0.24. L'unico rimedio è il firmware: su Appliance e Software Edition aggiornalo; sulla Cloud Edition lo aggiorna Yeastar, quindi controlla la versione della tua istanza e chiedi l'aggiornamento se è precedente.

Il trunk non si registra o resta in «Registering»#

Controlla Transport = TLS, la porta come nel foglio, Domain uguale a Hostname/IP, Username e Authentication Name identici a <UTENTE>, la modalità client TLS su 1.2 e i Blocked IPs. Se il trunk funziona ma lo stato mostra «Registering», è un difetto di visualizzazione che Yeastar corregge nella V25.2 (37.24.0.73, 15 settembre 2026): verifica con una chiamata di prova, o aggiorna il firmware.

Il trasferimento non arriva all'interno#

Nell'ordine: la Inbound Route è legata al trunk Aptiva e ha priorità sulla route predefinita; il DID Pattern coincide con la voce di rubrica dell'agente; Get DID From legge l'intestazione giusta (prova Invite); sulla Cloud Edition, controlla anche che l'interno sia tra i DID del trunk. Per vedere che numero chiamato arriva davvero, cattura i pacchetti come descritto sotto: è il metodo che Yeastar stesso consiglia per scegliere Get DID From.

Il trasferimento torna all'agente#

Il gruppo o la coda in rubrica ha come Failover Destination o destinazione fuori orario il numero che porta all'agente: cambiala, o usa un gruppo distinto per le chiamate da passare all'agente.

L'agente non risponde o non riconosce il chiamante#

Se il trunk è registrato ma l'agente non risponde, il nostro lato sta rifiutando la chiamata perché il From non porta un numero di telefono: imposta From User Part = Originator Caller ID negli Outbound Parameters del trunk. Stesso rimedio se l'agente risponde ma vede sempre lo stesso numero. Se succede solo con alcune chiamate, sono chiamate con numero nascosto, che oggi l'agente non gestisce.

L'IVR o la coda non raggiungono l'agente, un interno sì#

La Outbound Route è sotto una route generica, oppure il permesso Extension/Extension Group non copre le chiamate generate dal sistema. Sposta la route in alto e allarga gli interni abilitati. Se la route ha uno Strip, il Prefix della destinazione External Number deve ricomporre il pattern.

Catturare il traffico e leggere i log#

Maintenance > Troubleshooting > Ethernet Capture Tool: su Appliance e Software Edition scegli Ethernet Interface «Any» e metti <INDIRIZZO_APTIVA> nel filtro IP Address; sulla Cloud Edition ci sono solo Start, Stop e Download, senza filtri. Avvia, riproduci il problema, Stop e Download. Ottieni un file .tar con dentro un .pcap da aprire con Wireshark; se ci scrivi, allegalo. In Maintenance > System Logs il livello Debug con sottotipo SIP mostra i messaggi del trunk; i log si cancellano da soli dopo 7 giorni o a 10 MB.

Passi successivi#

1. Richiedi le credenziali del collegamento indicando protocollo SIP, edizione e firmware del tuo Yeastar, 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.