Call flow Script: Creazione di un agente Grok xAI

Introduzione

L'esempio grokvoiceagent.cs collega una chiamata in entrata 3CX a una sessione vocale in tempo reale di xAI Grok. L'agente è in grado di rispondere ai chiamanti, effettuare ricerche nella rubrica aziendale approvata, trasferire le chiamate, offrire la segreteria telefonica o la chat e, se configurato, salvare il contesto del chiamante.

L'esempio include uno strumento personalizzato get_department_hours disabilitato che illustra come registrare una funzione sicura richiamabile dall'IA.

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

Creare lo script di chiamata in 3CX

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

• Scegliere grokvoiceagent.cs.

• Inserire un nome dello script in minuscolo e senza spazi, ad esempio grokreception.
• Scegliere come verrà eseguito lo script e assegna il DID, il percorso del trunk o la destinazione interna richiesti.
• Assegnare lo script a un reparto.
• Passare all’editor di codice.

Configura xAI e lo script

Aggiungi i seguenti parametri protetti al centralino:

• GROK_API_KEY - la chiave API del tuo account xAI.
• GROK_REALTIME_MODEL - il modello vocale Grok Realtime.

Lascia vuoti i campiApiKeyOverride 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 Grok 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 e dovrebbe essere utilizzato normalmente solo per test temporanei.

Successivamente, controlla queste impostazioni relative ai clienti nella parte superiore dello script:

Prima di passare alla produzione, imposta  AllowAllVisibilityForTesting su falso ed esponi solo gli oggetti di directory necessari.

Per attivare l’esempio di strumento opzionale, esaminarne l’handler e rimuovere il commento:

RegisterExampleCustomTool();



Seleziona Salva e verificare che la compilazione sia andata a buon fine nell’output dello script.

Come funziona

• Il chiamante raggiunge lo script.
• Lo script crea un elenco di visibilità della directory con restrizioni.
• 3CX prepara il canale multimediale e avvia la sessione vocale in tempo reale di Grok.
• L’agente conversa con il chiamante e richiama le funzioni 3CX approvate.
• I trasferimenti vengono eseguiti tramite strumenti anziché tramite promesse conversazionali.
• Un errore del provider o dei media reindirizza il chiamante al fallback configurato.

Test dello script

• Verificare il comportamento vocale e multilingue di Grok selezionato.
• Cercare gli interni consentiti e quelli nascosti.
• Verificare che l’agente esegua un trasferimento dopo la conferma del chiamante.
• Testare la segreteria telefonica e la chat quando un utente non è disponibile.
• Salutare e verificare che la sessione si chiuda normalmente.

Risoluzione dei problemi

• La sessione fallisce immediatamente: Verificare GROK_API_KEY, il modello supportato, la licenza, la build del centralino e la connettività del provider in uscita.
• Il trasferimento viene annunciato ma non eseguito: Verificare che le istruzioni personalizzate richiedano ancora lo strumento di connessione e non siano state sovrascritte.
• La ricerca nella rubrica restituisce troppi risultati: disabilitare AddAll() e limitare la visibilità.
• Il fallback fallisce: Verificare la destinazione e le autorizzazioni del dipartimento.
• Manca il prompt: Verificare che ERROR sia presente nel set di prompt 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 31 luglio 2026

https://www.3cx.com/docs/grok-ai-voice-agent/