Agente de Voz en Tiempo Real de Gemini

Introducción

El ejemplo geminivoiceagent.cs conecta una llamada entrante de 3CX con Google Gemini Live. El agente puede saludar a las personas que llaman, utilizar los objetos del directorio autorizados, desviar llamadas, ofrecer el buzón de voz o el chat y, si está configurado, guardar información útil sobre la persona que llama.

El script incluye una herramienta personalizada get_department_hours desactivada que muestra cómo registrar una función segura que pueda ser llamada por la IA.

Este script requiere una licencia de 3CX Edición AI, una versión de PBX con el Update 10 y una cuenta API de Gemini.

Crear el Script de Llamada en 3CX

• Inicie sesión en la Consola de Administración de 3CX.
• Vaya a Integraciones > Scripts de Llamadas.
• Seleccione +Agregar desde la Tienda.

• Elija geminivoiceagent.cs.

• Introduzca el nombre del script en minúsculas y sin espacios; por ejemplo, geminireception.
• Seleccione cómo se ejecutará el script y asigne el DID, la ruta de troncal o el destino interno requeridos.
• Select the owning department.
• Continúe con el editor de código.

Configurar Gemini y el Script

Agregue los siguientes parámetros protegidos al PBX:

• GEMINI_API_KEY - la clave API de su proyecto de Google AI.
• GEMINI_REALTIME_MODEL - el modelo Gemini en Tiempo Real.

Deje ApiKeyOverride y ModelOverride en blanco en el script. Cuando estos valores están en blanco, el script lee automáticamente la clave API y el modelo de los parámetros del PBX.

Do not enter the Gemini API key directly in the script, especially if the script will be shared, exported or published. A value configured in ApiKeyOverride or ModelOverride takes precedence over the corresponding PBX parameter.

A continuación, revise la configuración de cliente que se encuentra cerca de la parte superior del script:

Establezca AllowAllVisibilityForTesting en false antes de pasar a producción y configure la lista de visibilidad más reducida que sea posible.

Para habilitar la función opcional example, revise sus datos y elimine el comentario:

RegisterExampleCustomTool();



Seleccione 'Guardar' y compruebe que la compilación se haya realizado correctamente.

Cómo Funciona

1. Una llamada entrante llega al punto de enrutamiento del script.
2. El script borra y vuelve a configurar la visibilidad permitida del directorio 3CX en Gemini.
3. 3CX prepara el canal de medios.
4. El script inicia la sesión de voz de Gemini Live con las instrucciones, la voz, el nombre del agente, la clave API y el modelo configurados.
5. Las herramientas aprobadas permiten realizar acciones relacionadas con directorios, transferencias, buzones de voz, chat y contexto.
6. Las fallas se redirigen al sistema de respaldo configurado y, si el enrutamiento no está disponible, se utiliza el mensaje de ERROR.

Probar el Script

• Verifica el comportamiento de la voz de Gemini seleccionada y el idioma del llamante.
• Buscar objetos de directorio permitidos.
• Verifica que no se puedan seleccionar los destinos ocultos.
• Prueba la confirmación de transferencia, el buzón de voz y el chat.
• Prueba una despedida natural.
• Simula una falla del proveedor y confirma el enrutamiento de respaldo.

Solución de Problemas

• La sesión de Gemini falla: Confirma la clave API de Gemini, el modelo activo compatible, la licencia, la versión del PBX y la conectividad de salida.
• Una voz es rechazada: Utiliza una voz compatible con el modelo Gemini configurado.
• Faltan los resultados del directorio: Verifica el número, el departamento y la visibilidad del rol.
• Hay demasiados objetos expuestos: Desactiva AddAll().
• Fallo del plan alternativo o del mensaje de solicitud: Verifica el destino y el mensaje de ERROR activo.

Ver También

• Crear un Script de Procesamiento de Llamadas.
• Ejemplo de Script para el Procesamiento de Llamadas por PIN.
• Manual del Administrador 3CX.

Última Actualización

Este documento se actualizó por última vez el 30 de Julio de 2026

https://www.3cx.es/docs/gemini-voice-agent/