Agente de Voz en Tiempo Real de OpenAI

Introducción

El ejemplo openaivoiceagent.cs conecta una llamada entrante de 3CX a una sesión de voz en Tiempo Real de OpenAI. Puede dar la bienvenida a las personas que llaman, responder preguntas generales, buscar en las entradas permitidas del directorio de 3CX, transferir llamadas, ofrecer el buzón de voz o el chat, y guardar información útil sobre la persona que llama cuando esa función está habilitada.

El script también incluye una herramienta personalizada desactivada llamada get_department_hours 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 OpenAI.

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 openaivoiceagent.cs.

• Introduzca el nombre del script en minúsculas y sin espacios; por ejemplo, openaireception.
• Seleccione cómo se ejecutará el script; en el caso de una recepcionista, asigne un número DID exclusivo o desvíe las llamadas entrantes por la troncal correspondiente al script.
• Seleccione el departamento al que pertenece el script.
• Confirme la selección para abrir el editor de código.

Configurar OpenAI y el Script

Agregue los siguientes parámetros al PBX:

• OPENAI_API_KEY - la clave API de su proyecto de OpenAI.
• OPENAI_REALTIME_MODEL - el modelo OpenAI 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.

No introduzca la clave API de OpenAI directamente en el script, especialmente si este se va a compartir, exportar o publicar. Un valor configurado en ApiKeyOverride o ModelOverride tiene prioridad sobre el parámetro correspondiente de PBX.

A continuación, revise esta configuración de cliente que se encuentra cerca de la parte superior del archivo openaivoiceagent.cs:

La función AddAll() es útil para una prueba inicial, pero normalmente debe desactivarse antes de pasar a producción. Establezca AllowAllVisibilityForTesting en false y, a continuación, configure únicamente los números, los departamentos y los roles que el agente necesite.

Para habilitar la herramienta personalizada de ejemplo, revise su respuesta estática y elimine el comentario de:

RegisterExampleCustomTool();



Sustituya el ejemplo por una fuente de datos confiable antes de utilizarlo con información real de clientes.

Selecciona Guardar para compilar. Confirme que el reporte de salida del script indique que la compilación se realizó correctamente antes de asignar el tráfico de producción.

Cómo Funciona

• Una llamada entrante llega al punto de enrutamiento del script.
• El script borra y vuelve a crear la lista de visibilidad del directorio de IA.
• 3CX prepara el canal de medios.
• El script inicia una sesión de voz en Tiempo Real de OpenAI.
• El agente utiliza únicamente las funciones integradas de 3CX y cualquier herramienta personalizada que se haya registrado explícitamente.
• Una transferencia exitosa conecta a la persona que llama con el destino 3CX seleccionado.
• Si falla la configuración de la media o la sesión del proveedor, el script intenta la alternativa configurada y, si el enrutamiento también falla, reproduce el mensaje de ERROR.

Probar el Script

• Llama al número DID asignado y confirma el mensaje de bienvenida y la voz seleccionada.
• Busca una extensión autorizada por nombre y número.
• Confirma que las extensiones ocultas no se puedan buscar ni seleccionar.
• Comprueba una coincidencia ambigua de directorios.
• Comportamiento de las transferencias de prueba, el buzón de voz para usuarios no disponibles y los mensajes de chat.
• Utiliza una clave de proveedor no válida en un entorno de prueba y verifica el enrutamiento de respaldo.
• Termina la conversación de manera natural y confirma la limpieza de la sesión.

Solución de Problemas

• La sesión del proveedor falla: Verifica OPENAI_API_KEY, el modelo en tiempo real compatible, el acceso a la red, las licencias y la versión del PBX de destino.
• El agente no puede encontrar a un usuario: Comprueba AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments, y VisibleRoles.
• Se ven los objetos equivocados: Llama a Clear() antes de agregar la lista de visibilidad de producción y evita usar AddAll().
• La opción alternativa no funciona: Confirma que el destino exista y que se pueda llegar a él desde el departamento asignado.
• No se escucha ningún mensaje de error: Confirma que ERROR exista en el conjunto de mensajes 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/open-ai-voice-agent/