Call Flow Script: Creazione di un agente vocale

Introduzione

L'esempio geminivoiceagent.cs collega una chiamata in entrata 3CX a Google Gemini Live. L'agente può salutare i chiamanti, utilizzare gli oggetti della rubrica autorizzati, instradare le chiamate, offrire la segreteria telefonica o la chat e, se configurato, salvare informazioni utili sul contesto del chiamante.

Lo script include 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 Gemini.

Creare lo script di chiamata in 3CX

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

• Scegliere geminivoiceagent.cs.

• Inserire un nome in minuscolo senza spazi, ad esempio geminireception.
• Selezionare la modalità di esecuzione dello script e assegnare il DID, il percorso del trunk o la destinazione interna richiesti.
• Selezionare il reparto di appartenenza.
• Passare all’editor di codice.

Configurazione di Gemini e dello script

Aggiungi i seguenti parametri protetti al PBX:

• GEMINI_API_KEY - la chiave API del tuo progetto Google AI.
• GEMINI_REALTIME_MODEL - il modello Gemini Realtime.

Lascia 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 Gemini direttamente nello script, specialmente se lo script verrà condiviso, esportato o pubblicato. Un valore configurato in ApiKeyOverride o ModelOverride ha la precedenza sul corrispondente parametro del PBX.

In seguito, controlla queste impostazioni utente nella parte superiore dello script:

Impostare AllowAllVisibilityForTesting su false prima della messa in produzione e configurare l'elenco di visibilità più ristretto possibile.

Per abilitare l'esempio di funzione opzionale, esaminarne i dati e rimuovere il commento da:

RegisterExampleCustomTool();



Selezionare “Salva” e verificare che la compilazione sia andata a buon fine.

Come funziona

1. Una chiamata in entrata raggiunge il punto di instradamento dello script.
2. Lo script azzera e ricostruisce la visibilità consentita della rubrica 3CX in Gemini.
3. 3CX prepara il canale multimediale.
4. Lo script avvia la sessione vocale Gemini Live con le istruzioni configurate, la voce, il nome dell’agente, la chiave API e il modello.
5. Gli strumenti approvati eseguono azioni relative alla rubrica, al trasferimento, alla segreteria telefonica, alla chat e al contesto.
6. Gli errori vengono instradati al fallback configurato e, se l’instradamento non è disponibile, viene utilizzato il messaggio di errore.

Test dello script

• Verificare il comportamento della voce Gemini selezionata e la lingua del chiamante.
• Cercare gli oggetti della rubrica autorizzati.
• Verificare che le destinazioni nascoste non possano essere selezionate.
• Testare la conferma del trasferimento, la segreteria telefonica e la chat.
• Testare un saluto naturale.
• Simulare un errore del provider e confermare l’instradamento di fallback.

Risoluzione dei problemi

• La sessione Gemini fallisce: Verificare la chiave API di Gemini, il modello live supportato, la licenza, la build del PBX e la connettività in uscita.
• Una voce viene rifiutata: Utilizzare una voce supportata dal modello Gemini configurato.
• Mancano i risultati della rubrica: Controllare la visibilità di numero, reparto e ruolo.
• Sono esposti troppi oggetti: Disabilitare AddAll().
• Il routing di fallback o il messaggio di errore non funzionano: Verificare la destinazione e il messaggio di errore attivo.

Per saperne di più

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

Ultimo aggiornamento

Questo documento è stato aggiornato il 30 luglio 2026

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