Creazione app vocale basata sull'IA con interni programmabili di 3CX

Collegare un'app vocale basata su IA ospitata esternamente a 3CX utilizzando l'API Call Control, l'SDK Call Control e un provider di IA in tempo reale supportato.

Introduzione

Gli interni programmabili di 3CX consentono a un'applicazione ospitata esternamente di connettersi al centralino 3CX e funzionare come un interno nativo. L'applicazione può ricevere chiamate, trasmettere audio in entrambe le direzioni e controllare l'instradamento delle chiamate tramite l'API Call Control di 3CX.

Gli esempi di Agentic Call Control forniscono applicazioni Node.js funzionanti per:

• OpenAI Realtime
• Google Gemini Live
• xAI Grok Voice Agent
• Alibaba Cloud Qwen Omni Realtime

Ciascun esempio utilizza un’unica sessione audio bidirezionale in tempo reale. Il riconoscimento vocale, il ragionamento e la generazione vocale sono gestiti dal fornitore di IA selezionato, mentre 3CX continua a fornire i servizi di telefonia, l’instradamento delle chiamate, gli interni, i trunk SIP e i DID.

Gli esempi si connettono tramite le API 3CX pubblicate e non richiedono modifiche al codice sorgente del centralino. Si connettono inoltre all’endpoint MCP di 3CX, in modo che l’applicazione vocale possa utilizzare strumenti autorizzati del centralino, come la ricerca nella rubrica. È possibile aggiungere server MCP esterni opzionali per calendari, CRM e altri sistemi aziendali.

Quale opzione dovrei utilizzare? 

Questa guida tratta gli interni programmabili, in cui l’app viene eseguita al di fuori di 3CX su un’infrastruttura gestita dall’utente. Per una soluzione pronta all’uso, utilizzare gli agenti IA integrati di 3CX. Per applicazioni personalizzate che vengono eseguite direttamente sul server 3CX, utilizzare gli script di chiamata IA.

Cosa realizzerai

Al termine di questa guida, avrai a disposizione un’applicazione vocale con IA esterna in grado di:

• Ricevere chiamate interne tramite il proprio ID cliente 3CX.
• Ricevere chiamate esterne tramite un numero DID assegnato.
• Condurre una conversazione vocale in tempo reale utilizzando il provider di IA selezionato.
• Effettuare ricerche nella rubrica 3CX tramite MCP.
• Trasferire una chiamata, inviarla alla segreteria telefonica o terminarla tramite 3CX Call Control.
• Connettersi a server MCP aggiuntivi e rendere disponibili al modello gli strumenti selezionati.

Il profilo agente fornito implementa un flusso di base per l’operatore di reception. È concepito come punto di partenza e può essere esteso per la prenotazione di appuntamenti, le informazioni sui clienti, i sondaggi, gli help desk interni e altri flussi di lavoro.

Prima di iniziare

È necessario disporre di:

• Un sistema 3CX V20 Update 10 con accesso all’API Call Control.
• Accesso come amministratore per creare un “Service Principal” API.
• Node.js 20 o versione successiva sul computer o sul server che ospiterà l’applicazione.
• La versione di Yarn inclusa nel repository.
• Una chiave API e una quota disponibile per almeno un provider di IA supportato.
• Accesso di rete dall’host dell’applicazione all’FQDN HTTPS di 3CX e agli endpoint WebSocket del provider selezionato.

Passo 1: Scaricare gli esempi

Clonare o scaricare il repository GitHub di Agentic Call Control:

Da un terminale, passare alla directory principale del repository e installare tutte le dipendenze dell'area di lavoro:

yarn install



Se il comando yarn non è disponibile, abilitare prima Corepack:

corepack enable

yarn install



Non eseguire il comando yarn install separatamente in ogni directory del provider. Il repository è un'area di lavoro Yarn e deve essere installato dalla sua directory principale.

Passo 2: Creare un'entità di servizio 3CX

Creare le credenziali che l’applicazione esterna utilizzerà per autenticarsi con il centralino telefonico.

• Accedere al web client 3CX e aprire la sezione Admin.
• Andare su Admin >  Integrazioni > API.
• Cliccare su Aggiungi per creare un’entità di servizio.
• Inserire un ID cliente, ad esempio ai-receptionist. Questo diventerà appId dell’applicazione e il numero interno che gli utenti potranno comporre per chiamare l’applicazione.
• Abilitare l’accesso all’API di controllo delle chiamate 3CX per l’applicazione.
• Se lo desideri, assegna un DID se i chiamanti esterni devono poterla raggiungere direttamente.
• Se lo desideri, selezionare gli interni che l’applicazione è autorizzata a monitorare o controllare. Concedere solo l’accesso richiesto dal flusso di lavoro previsto.
• Salvare l’entità di servizio.
• Copiare immediatamente la chiave API o il segreto client generati. Verranno utilizzati come appSecret e verranno visualizzati una sola volta.

Passo 3: Scegliere un provider di IA

Utilizza uno degli esempi inclusi.

Crea la chiave API nella console del provider selezionato e conservala in modo sicuro:

• Chiavi API OpenAI
• Chiavi API Google AI Studio
• Console xAI
• Console DashScope di Alibaba Cloud

Per informazioni sulla disponibilità attuale dei modelli, sulle voci, sulle regioni, sui prezzi e sui limiti di rate, consulta la documentazione del provider selezionato e il file README nella directory degli esempi corrispondente.

Nota sulla regione Qwen: le credenziali e gli endpoint di DashScope sono specifici per regione. Utilizza l’endpoint richiesto per la regione e l’area di lavoro in cui è stata creata la chiave API.

Passo 4: Creare la configurazione del provider

Copia il file config.yaml.example in config.yaml nella directory degli esempi selezionata..

OpenAI

cp examples/openai-realtime/config.yaml.example examples/openai-realtime/config.yaml

Gemini

cp examples/gemini-realtime/config.yaml.example examples/gemini-realtime/config.yaml

xAI

cp examples/xai-realtime/config.yaml.example examples/xai-realtime/config.yaml

Alibaba Qwen

cp examples/alibaba-qwen-realtime/config.yaml.example examples/alibaba-qwen-realtime/config.yaml



In Windows PowerShell, utilizzare Copy-Item al posto di cp.

Aprire il nuovo file config.yaml e inserire i valori comuni di 3CX:

appId: ai-receptionist

appSecret: your-3cx-api-key

pbxBase: https://your-pbx.example.com

companyName: Your Company

agentName: Assistant

initialGreeting: Thank you for calling. How can I help you today?



Mantenere il valore di agentProfile fornito dall’esempio selezionato. OpenAI, Gemini e xAI utilizzano receptionist; Qwen include profili separati per l’inglese e il cinese.

Successivamente, imposta le credenziali per il provider selezionato. Ad esempio, la configurazione di OpenAI contiene:

openaiApiKey: sk-your-openai-api-key



Utilizza il file config.yaml.example fornito dal provider come riferimento ufficiale per le impostazioni relative al modello, alla voce, al rilevamento dell’attività vocale e a quelle specifiche del provider. Per Qwen, mantieni la configurazione dell’URL di base specifica per la regione fornita dal provider.

Sicurezza: Il file config.yaml contiene segreti. Sebbene sia escluso dal file .gitignore fornito, è comunque consigliabile evitare di condividerlo, di sottoporlo a commit o di includerlo nei log di supporto. Per l’ambiente di produzione, utilizzare un gestore di segreti o un metodo di distribuzione basato sull’ambiente.

Passo 5: Avvio dell'applicazione

Eseguire il comando relativo al provider selezionato dalla directory principale del repository.

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen



L'output esatto all'avvio varia a seconda del provider. Un avvio riuscito dovrebbe confermare che:

• L'applicazione si sia autenticata con 3CX.
• L'SDK di controllo delle chiamate e la connessione WebSocket siano attivi.
• L'applicazione si sia connessa all'endpoint MCP di 3CX.
• Gli strumenti MCP abilitati siano stati caricati.
• Il gestore delle chiamate sia stato inizializzato e l'applicazione sia pronta ad accettare chiamate.

Passo 6: Effettuare una chiamata e testare l’applicazione

Effettuare una chiamata interna

Da un interno 3CX registrato, comporre l’ID client del soggetto di servizio configurato come appId.

Ad esempio, se l’ID client è ai-receptionist, comporre ai-receptionist dal web client 3CX, dall’app desktop, dall’app mobile o da un telefono configurato.

Effettuare una chiamata esterna

Se è stato assegnato un DID al Service Principal, chiamare quel numero da un telefono esterno.

Test consigliati

Testare il flusso di lavoro completo prima di personalizzarlo:

• Verificare che l’operatore risponda con il messaggio di benvenuto configurato.
• Chiedere di parlare con un contatto noto della rubrica.
• Verificare che l’operatore effettui la ricerca nella rubrica tramite MCP.
• Verificare che il trasferimento avvenga correttamente.
• Verificare il percorso per gli utenti non disponibili e la segreteria telefonica.
• Interrompere l’agente mentre sta parlando per verificare il comportamento di interruzione della chiamata.
• Terminare la chiamata e verificare che l’applicazione la rilasci correttamente.

Arrestare l’applicazione con Ctrl+C.

Personalizzare l’agente

Le impostazioni di base, come il nome dell’azienda e il nome dell’agente, sono memorizzate nel file config.yaml.

Il comportamento più dettagliato è definito dal profilo YAML nella directory agents dell’esempio selezionato. A seconda dell’esempio del provider, il profilo predefinito è denominato receptionist.yaml, receptionist_en.yaml o receptionist_cn.yaml.

Il profilo controlla aspetti quali:

• Il ruolo e il messaggio di sistema.
• I saluti e le impostazioni relative alla lingua.
• I requisiti di filtraggio delle chiamate.
• I controlli di disponibilità prima del trasferimento.
• Le azioni consentite sulle chiamate.
• Interni bloccati.
• Politiche relative a spam, comportamenti ostili e chiamanti non collaborativi.
• Gli strumenti MCP resi disponibili al modello.

Riavviare l’applicazione dopo aver modificato il file config.yaml o il profilo agente selezionato.

Assicurarsi che le indicazioni vocali e le autorizzazioni degli strumenti siano allineate. Indicare al modello che può eseguire un’azione non garantisce all’applicazione sottostante o al Service Principal l’autorizzazione a eseguirla.

Utilizzo degli strumenti 3CX MCP

All’avvio, gli esempi si connettono all’endpoint 3CX MCP e individuano gli strumenti disponibili per il Service Principal autenticato.

Solo gli strumenti elencati nella lista di autorizzazione mcpTools del profilo dell’agente vengono resi disponibili al modello di IA. Il profilo predefinito dell’addetto alla reception abilita la ricerca nella rubrica:

mcpTools:

  - list_phonebook



Il log di avvio mostra gli strumenti individuati dal server e se ciascuno di essi è abilitato. Per rendere disponibile un altro strumento autorizzato, aggiungere il suo nome esatto a  mcpTools e riavviare l’applicazione.

Limitare l’elenco al minimo indispensabile di strumenti richiesti dal flusso di lavoro. Uno strumento che non è reso disponibile al modello non può essere richiamato dal modello stesso.

Collegare server MCP aggiuntivi

I server MCP opzionali possono essere configurati nella sezione `customMcpServers` del file `config.yaml`. Ciò consente all’applicazione vocale di accedere a strumenti approvati quali calendari, CRM o strumenti per i processi aziendali.

Gli esempi supportano auth.type: bearer o none per facilitare i test. Per una prova rapida senza dover eseguire il proprio server MCP, utilizzare un aggregatore MCP ospitato come Smithery AI o Zapier. Creare un account e incollare l'URL remoto e il token bearer in customMcpServers, quindi abilitare i nomi degli strumenti rilevati in mcpTools.

customMcpServers:

  - name: GoogleCalendar

    url: https://mcp.example.com/your-server

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true



Aggiungi ogni strumento che desideri rendere visibile al profilo dell'agente utilizzando il suo nome esatto:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add



Gli strumenti rilevati dai server MCP personalizzati vengono integrati con gli strumenti MCP di 3CX disponibili, ma è l'elenco dei profili autorizzati a determinare quali strumenti il modello può utilizzare.

Quando si aggiungono server MCP esterni:

• Utilizzare credenziali con il minimo livello di privilegi.
• Rendere accessibili solo gli strumenti necessari.
• Convalidare i parametri degli strumenti lato server.
• Richiedere l'approvazione per operazioni sensibili o irreversibili, ove opportuno.
• Non inserire segreti di produzione a lunga durata direttamente nel controllo del codice sorgente.

Oltre l’esempio della receptionist

La logica della receptionist inclusa illustra la ricerca nella rubrica, il trasferimento di chiamata, la segreteria telefonica e la chiusura della chiamata. La stessa architettura può essere estesa per supportare flussi di lavoro quali:

• Pianificazione degli appuntamenti.
• Ricerca di informazioni sui clienti o sugli account.
• Sondaggi automatizzati.
• Help desk interni IT o delle risorse umane.
• Creazione e aggiornamento dei ticket CRM.
• Servizi relativi allo stato degli ordini o alle informazioni di consegna.
• Interfacce vocali per applicazioni aziendali personalizzate.

L’applicazione rimane responsabile della logica di business, della convalida, della gestione degli errori e della sicurezza dello strumento. 3CX fornisce la connessione della chiamata, lo streaming audio e le funzioni di controllo delle chiamate, mentre il fornitore di IA selezionato gestisce la conversazione in tempo reale.

Lista di controllo per la produzione

Prima di far passare un’applicazione personalizzata dalla fase di test alla produzione:

• Eseguirla come servizio gestito con riavvio automatico e monitoraggio dello stato di salute.
• Proteggere le credenziali API con un gestore di segreti e ruotarle periodicamente.
• Limitare il Service Principal agli interni e alle funzioni necessarie.
• Esaminare le politiche del fornitore di IA relative al trattamento dei dati, alla conservazione e alla disponibilità a livello regionale.
• Informare i chiamanti e ottenere il consenso laddove siano richieste la registrazione, la trascrizione o la divulgazione dei dati da parte dell’IA.
• Monitorare l’utilizzo del fornitore, i limiti di velocità e i costi.
• Aggiungere timeout, gestione dei tentativi e un percorso di fallback non basato sull’IA.
• Testare i percorsi di trasferimento, segreteria telefonica, errore e disconnessione in condizioni di chiamata realistiche.
• Esaminare ogni strumento MCP abilitato e proteggere le azioni sensibili con ulteriori validazioni o approvazioni.

Risoluzione dei problemi

yarn non viene riconosciuto

Assicurati che Node.js 20 o una versione successiva sia installato, quindi abilita Corepack:

corepack enable



Eseguire nuovamente il comando yarn install dalla directory principale del repository.

L'autenticazione PBX restituisce il codice di errore 401 o 403

Verificare che appId, appSecret e pbxBase corrispondano al Service Principal. Accertarsi che l'accesso all'API Call Control sia abilitato e che la licenza e le autorizzazioni 3CX consentano l'operazione richiesta.

L'applicazione si avvia ma non riceve chiamate

Verificare che l'applicazione sia ancora in esecuzione, comporre l'ID client corretto e verificare che il DID sia assegnato al Service Principal durante il test delle chiamate esterne.

Uno strumento MCP appare disabilitato

Copiare il nome esatto dello strumento riportato nel log di avvio nell'elenco mcpTools del profilo, quindi riavviare l'applicazione. Verificare inoltre che il Service Principal sia autorizzato a utilizzare lo strumento.

I trasferimenti o la segreteria telefonica non funzionano

Verificare che la destinazione sia valida e accessibile al Service Principal. Se nel profilo è abilitato lo screening delle chiamate, verificare che i campi di screening richiesti siano stati raccolti prima di tentare il trasferimento.

Il provider di IA rifiuta la connessione

Controllare la chiave API, la fatturazione dell’account, l’accesso al modello, la regione, la quota e la connettività WebSocket. Per Qwen, verificare che la chiave API e l’endpoint

L'audio è in ritardo o l'agente viene interrotto frequentemente

Controllare la latenza di rete e la perdita di pacchetti tra l'host dell'applicazione, 3CX e il provider di IA. Verificare le impostazioni specifiche del provider relative al rilevamento dell'attività vocale e all'audio nel file config.yaml.

Ultimo aggiornamento

Questo documento è stata aggiornato il 17 settembre 2026

https://www.3cx.it/doc/programmable-extensions/