Creazione di un agente vocale OpenAI

Introduzione

L'esempio openaivoiceagent.cs collega una chiamata in entrata su 3CX a una sessione vocale in tempo reale di OpenAI. È in grado di accogliere i chiamanti, rispondere a domande generali, effettuare ricerche tra le voci autorizzate della rubrica 3CX, trasferire le chiamate, proporre la segreteria telefonica o la chat e salvare informazioni utili sul contesto del chiamante quando tale funzione è abilitata.

Lo script include anche uno strumento personalizzato get_department_hours disabilitato, che mostra come registrare una funzione sicura che può essere richiamata dall'IA.

Questo script richiede una licenza 3CX IA, una build del PBX Update 10 e un account API OpenAI.

Creare lo script di chiamata in 3CX

• Accedere alla Console di amministrazione 3CX.
• Andare su Integrazioni > Script di chiamata.
• Selezionare +Aggiungi dallo Store.

• Scegliere openaivoiceagent.cs.

• Inserire un nome dello script in minuscolo e senza spazi, ad esempio openaireception.
• Selezionare la modalità di esecuzione dello script; per un addetto alla reception, assegnare un DID dedicato o instradare le chiamate in entrata appropriate verso lo script.
• Selezionare il reparto a cui appartiene lo script.
• Confermare la selezione per aprire l’editor di codice.

Configurare OpenAI e lo script

Aggiungere i seguenti parametri al PBX:

• OPENAI_API_KEY - la chiave API del proprio progetto OpenAI.
• OPENAI_REALTIME_MODEL - il modello OpenAI Realtime.

Lasciare vuoti i campi ApiKeyOverride e ModelOverride nello script. Quando questi valori sono vuoti, lo script legge automaticamente la chiave API e il modello dai parametri del PBX.

Non inserire la chiave API di OpenAI direttamente nello script, soprattutto se lo script verrà condiviso, esportato o pubblicato. Un valore configurato in ApiKeyOverride o ModelOverride ha la precedenza sul corrispondente parametro del PBX.

Successivamente, controlla queste impostazioni personalizzate nella parte superiore del file openaivoiceagent.cs:

La funzione AddAll() è utile per un test iniziale, ma normalmente dovrebbe essere disabilitata prima della messa in produzione. Impostare AllowAllVisibilityForTesting su falso, quindi configurare solo i numeri, i dipartimenti e i ruoli necessari all'agente.

To enable the sample custom tool, review its static response and uncomment:

RegisterExampleCustomTool();



Prima di utilizzare l'esempio con dati reali dei clienti, sostituirlo con una base di dati attendibile.

Selezionare Salva per compilare. Verificare che l’output dello script indichi che la compilazione è avvenuta con successo prima di assegnare il traffico di produzione.

Come funziona

• Una chiamata in entrata raggiunge il punto di instradamento dello script.
• Lo script cancella e ricostruisce l’elenco di visibilità della directory IA.
• 3CX prepara il canale multimediale.
• Lo script avvia una sessione vocale OpenAI Realtime.
• L’operatore utilizza solo le funzioni integrate di 3CX ed eventuali strumenti personalizzati registrati esplicitamente.
• Un trasferimento riuscito trasferisce il chiamante alla destinazione 3CX selezionata.
• Se la configurazione multimediale o la sessione del provider fallisce, lo script tenta il fallback configurato e, se anche l’instradamento fallisce, riproduce il messaggio di ERRORE.

Test dello script

• Chiamare il DID assegnato e verifica il messaggio di benvenuto e la voce selezionata.
• Cercare un interno autorizzato per nome e numero.
• Verificare che gli interni nascosti non possano essere cercati o selezionati.
• Testare una corrispondenza ambigua nella directory.
• Verificare il comportamento del trasferimento, della segreteria telefonica per utenti non disponibili e dei messaggi di chat.
• Utilizzare una chiave del provider non valida in un ambiente di test e verificare l’instradamento di fallback.
• Terminare la conversazione in modo naturale e verificare la pulizia della sessione.

Risoluzione dei problemi

• La sessione del provider non va a buon fine: Verificare OPENAI_API_KEY, il modello in tempo reale supportato, l'accesso alla rete, la licenza e la build del PBX di destinazione.
• L'agente non riesce a trovare un utente: controllare AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments e VisibleRoles.
• Sono visibili oggetti errati: Chiamare Clear() prima di aggiungere l’elenco di visibilità di produzione ed evitare di utilizzare AddAll().
• Il fallback non funziona: Verificare che la destinazione esista e sia raggiungibile dal reparto assegnato.
• Non viene riprodotto alcun messaggio di errore: Verificare che ERROR sia presente nel set di messaggi attivo.

Per saperne di più

• Creazione di uno script di elaborazione delle chiamate
• Esempio di script di elaborazione delle chiamate per PIN
• Manuale di amministrazione 3CX

Ultimo aggiornamento

Questo documento è stato aggiornato il 30 luglio 2026

https://www.3cx.it/doc/gemini-voice-agent/