Aplicación de Voz IA con Extensiones Programables

Conecta una aplicación de voz con IA hospedada externamente a 3CX mediante la API de Control de Llamadas, el SDK de Control de Llamadas y un proveedor de IA en tiempo real compatible.

Introducción

Las Extensiones Programables de 3CX permiten que una aplicación hospedada externamente se conecte al PBX y funcione como una extensión nativa. La aplicación puede recibir llamadas, transmitir audio en ambas direcciones y controlar el enrutamiento de llamadas a través de la API de Control de Llamadas de 3CX.

Los ejemplos de Control de Llamadas de Agente ofrecen aplicaciones de Node.js que funcionan para:

  • OpenAI en Tiempo Real.
  • Google Gemini Live.
  • Agente de Voz xAI Grok.
  • Alibaba Cloud Qwen Omni en Tiempo Real.

Cada ejemplo utiliza una sola sesión de audio bidireccional en tiempo real. El reconocimiento de voz, el razonamiento y la generación de voz corren a cargo del proveedor de IA seleccionado, mientras que 3CX sigue encargándose de la telefonía, el enrutamiento de llamadas, las extensiones, las troncales SIP y los números DID.

Los ejemplos se conectan a través de las APIs publicadas de 3CX y no requieren modificaciones en el código fuente del PBX. Además, se conectan al punto final del MCP de 3CX para que la aplicación de voz pueda utilizar herramientas autorizadas del PBX, como la búsqueda en la agenda telefónica. Se pueden agregar servidores MCP externos opcionales para calendarios, CRM y otros sistemas empresariales.

¿Qué opción debo usar?

Esta guía aborda las Extensiones Programables, en las que la aplicación se ejecuta fuera de 3CX, en una infraestructura que usted administra. Si busca una solución lista para configurar, utilice los Agentes IA integrados de 3CX. Para aplicaciones personalizadas que se ejecutan directamente en el Servidor 3CX, utilice los Scripts de Llamadas IA.

Lo que Usted Construirá

Al finalizar esta guía, dispondrá de una aplicación de voz con IA externa que podrá:

  • Recibir llamadas internas a través de su ID de Cliente de 3CX.
  • Recibir llamadas externas a través de un número DID asignado.
  • Realizar una conversación de voz en tiempo real utilizando el proveedor de IA que haya seleccionado.
  • Buscar en la agenda de 3CX a través de MCP.
  • Transferir una llamada, enviarla al buzón de voz o finalizarla a través del Control de Llamadas de 3CX.
  • Conectarse a servidores MCP adicionales y hacer que las herramientas seleccionadas estén disponibles en el modelo.

El perfil de agente incluido implementa un flujo básico de recepción. Está pensado como punto de partida y se puede ampliar para la programación de citas, información al cliente, encuestas, servicios de asistencia interna y otros flujos de trabajo.

Antes de Empezar

Necesita:

  • Un sistema 3CX V20 Update 10 con acceso a la API de Control de Llamadas.
  • Acceso de administrador para crear una API de Servicio Principal.
  • Node.js 20 o una versión posterior en la computadora o el servidor que hospedará la aplicación.
  • La versión de Yarn incluida en el repositorio.
  • Una clave de API y una cuota disponible para al menos un proveedor de IA compatible.
  • Acceso de red desde el servidor que hospeda la aplicación al FQDN HTTPS de 3CX y a los puntos finales WebSocket del proveedor seleccionado.

Paso 1: Descargar los Ejemplos

Clone o descargue el repositorio de Agentic Call Control: Abra el repositorio de Agentic Call Control.

Desde una terminal, cambie a la raíz del repositorio e instale todas las dependencias del espacio de trabajo:

yarn install

Si el comando yarn no está disponible, habilite primero Corepack:

corepack enable

yarn install

No ejecute yarn install or separado en cada directorio de proveedor. El repositorio es un espacio de trabajo de Yarn y debe instalarse desde su raíz.

Paso 2: Crear un Servicio Principal de 3CX

Genere las credenciales que utilizará la aplicación externa para autenticarse con el PBX.

  • Inicie sesión en el Cliente Web de 3CX y abra la sección de Admin.
  • Vaya a Integraciones > API.
  • Haga clic en Agregar para crear el Servicio Principal.
  • Introduzca un ID de Cliente, por ejemplo, ai-receptionist. Este se convertirá en el appId de la aplicación y en el número interno que los usuarios pueden marcar para llamar a la aplicación.
  • Habilite el acceso a la API de Control de Llamadas de 3CX para la aplicación.
  • Si es necesario que las personas que llaman desde fuera puedan comunicarse directamente con él, asigne un número DID de manera opcional.
  • Si lo desea, seleccione las extensiones que la aplicación tiene permiso para monitorizar o controlar. Otorgue únicamente el acceso necesario para el flujo de trabajo previsto.
  • Guarde el Servicio Principal.
  • Copia de inmediato la clave de API o el Cliente Secreto generado. Se utiliza como appSecret y solo se mostrará una vez.

Paso 3: Elija un Proveedor IA

Utilice uno de los ejemplos incluidos.

Proveedor

Directorio de ejemplo

Credenciales del proveedor

Comando de arranque

OpenAI Realtime

examples/openai-realtime

openaiApiKey

yarn start:openai

Google Gemini Live

examples/gemini-realtime

geminiApiKey

yarn start:gemini

xAI Grok Voice Agent

examples/xai-realtime

xaiApiKey

yarn start:xai

Alibaba Qwen Omni Realtime

examples/alibaba-qwen-realtime

dashscopeApiKey

yarn start:alibaba-qwen

Genere la clave API en la consola del proveedor seleccionado y guárdela de manera segura:

Para conocer la disponibilidad actual de los modelos, las voces, las regiones, los precios y los límites de tarifas, consulte la documentación del proveedor seleccionado y el archivo README en el directorio de ejemplos correspondiente.

Nota sobre la región de Qwen: Las credenciales y los puntos de conexión de DashScope son específicos de cada región. Utilice el punto de conexión correspondiente a la región y al espacio de trabajo en los que se creó la clave API.

Paso 4: Crear la Configuración del Proveedor

Copie config.yaml.example en config.yaml en el directorio de ejemplo seleccionado.

OpenAI

cp examples/openai-realtime/config.yaml.example examples/openai-realtime/config.yaml

Gemini

cp examples/gemini-realtime/config.yaml.example examples/gemini-realtime/config.yaml

xAI

cp examples/xai-realtime/config.yaml.example examples/xai-realtime/config.yaml

Alibaba Qwen

cp examples/alibaba-qwen-realtime/config.yaml.example examples/alibaba-qwen-realtime/config.yaml

En Windows PowerShell, utilice Copy-Item en lugar de cp.

Abra el nuevo archivo config.yaml e ingrese los valores comunes de 3CX:

appId: ai-receptionist

appSecret: your-3cx-api-key

pbxBase: https://your-pbx.example.com

companyName: Your Company

agentName: Assistant

initialGreeting: Thank you for calling. How can I help you today?

Mantenga el valor de agentProfile que proporciona el ejemplo seleccionado. OpenAI, Gemini y xAI utilizan receptionist; Qwen incluye perfiles separados en Inglés y Chino.

A continuación, configure las credenciales para el proveedor seleccionado. Por ejemplo, la configuración de OpenAI contiene:

openaiApiKey: sk-your-openai-api-key

Utilice el archivo config.yaml.example proporcionado por el proveedor como referencia oficial para la configuración del modelo, la voz, la detección de actividad de voz y los ajustes específicos del proveedor. En el caso de Qwen, mantenga la configuración de la URL base específica de la región proporcionada por el proveedor.

Seguridad: El archivo config.yaml contiene secretos. Aunque está excluido por el archivo .gitignore proporcionado, no debe compartirlo, subirlo al control de versiones ni incluirlo en los registros de soporte técnico. Utilice un administrador de secretos o un método de implementación basado en el entorno para la producción.

Paso 5: Iniciar la Aplicación

Ejecute el comando correspondiente al proveedor seleccionado desde la raíz del repositorio.

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen

La salida exacta al iniciar varía según el proveedor. Un inicio exitoso debería confirmar que:

  • La aplicación se autenticó con 3CX.
  • El SDK de Control de Llamadas y la conexión WebSocket están activos.
  • La aplicación se conectó al terminal 3CX MCP.
  • Se cargaron las herramientas de MCP habilitadas.
  • El controlador de llamadas se ha iniciado y la aplicación está lista para recibir llamadas.

Paso 6: Llamar y Probar la Aplicación

Realizar una Llamada Interna

Desde una extensión 3CX registrada, marque el ID de Cliente Principal del Servicio configurado como appId.

Por ejemplo, si el ID de Cliente es ai-receptionist, marque ai-receptionist desde el Cliente Web de 3CX, la aplicación de escritorio, la aplicación móvil o un teléfono aprovisionado.

Realizar una Llamada Externa

Si le asignó un DID al Servicio Principal, llame a ese número desde un teléfono externo.

Pruebas Recomendadas

Compruebe el flujo de trabajo completo antes de personalizarlo:

  • Verifique que el agente responda con el saludo configurado.
  • Solicite hablar con un contacto que aparezca en la agenda.
  • Confirme que el agente busque en la agenda a través de MCP.
  • Pruebe una transferencia exitosa.
  • Pruebe la ruta de usuario no disponible y la ruta del buzón de voz.
  • Interrumpa al agente mientras está hablando para verificar cómo reacciona ante una interrupción.
  • Finalice la llamada y verifique que la aplicación libere la llamada correctamente.

Detenga la aplicación con Ctrl+C.

Personalizar al Agente

Los ajustes básicos, como el nombre de la empresa y el nombre del agente, se guardan en el archivo config.yaml.

El comportamiento más detallado se define mediante el perfil YAML que se encuentra en el directorio agents del ejemplo seleccionado. Dependiendo del ejemplo del proveedor, el perfil predeterminado se llama receptionist.yaml, receptionist_en.yaml o receptionist_cn.yaml.

El perfil controla aspectos como:

  • El rol y el prompt del sistema.
  • Saludos y comportamiento lingüístico.
  • Requisitos para el filtrado de llamadas.
  • Verificación de disponibilidad antes de la transferencia.
  • Acciones permitidas en las llamadas.
  • Extensiones bloqueadas.
  • El spam, la hostilidad y las políticas que no fomentan la colaboración con quienes llaman.
  • Las herramientas de MCP a las que tiene acceso el modelo.

Reinicie la aplicación después de modificar el archivo config.yaml o el perfil de agente seleccionado.

Mantenga alineados los comandos y los permisos de las herramientas. El hecho de indicarle al modelo que puede realizar una acción no otorga a la aplicación subyacente ni al Servicio Principal el permiso para llevarla a cabo.

Utilizar las Herramientas de 3CX MCP

Al iniciarse, los ejemplos se conectan al punto final de 3CX MCP e identifican las herramientas disponibles para el Servicio Principal autenticado.

Solo las herramientas que figuran en la lista de herramientas permitidas mcpTools del perfil del agente están disponibles para el modelo de IA. El perfil predeterminado de recepcionista habilita la búsqueda en la agenda telefónica:

mcpTools:

  - list_phonebook

El registro de inicio muestra las herramientas detectadas en el servidor e indica si cada una de ellas está habilitada. Para habilitar otra herramienta autorizada, agregue su nombre exacto a mcpTools y reinicie la aplicación.

Limite la lista al conjunto más reducido de herramientas que requiera el flujo de trabajo. El modelo no puede invocar una herramienta que no esté expuesta para el modelo.

Conectar Servidores MCP Adicionales

Los servidores MCP opcionales se pueden configurar en la sección customMcpServers del archivo config.yaml. Esto permite que la aplicación de voz tenga acceso a herramientas aprobadas de calendario, CRM o procesos de negocios.

Los ejemplos auth.type: bearer o auth.type: none para facilitar las pruebas. Para una prueba rápida sin necesidad de ejecutar su propio servidor MCP, utilice un conector alojado como Smithery: pegue la URL remota y el token de portador en customMcpServers, y luego habilite los nombres de las herramientas detectadas en mcpTools.

customMcpServers:

  - name: GoogleCalendar

    url: https://mcp.example.com/your-server

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true

Agregue cada herramienta que desee incluir en el perfil del agente utilizando su nombre exacto:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add

Las herramientas detectadas en los servidores MCP personalizados se combinan con las herramientas disponibles de 3CX MCP, pero la lista de herramientas permitidas del perfil sigue determinando qué herramientas puede utilizar el modelo.

Al agregar servidores MCP externos:

  • Utilice credenciales con el mínimo de privilegios.
  • Ponga a la vista solo las herramientas necesarias.
  • Valide los parámetros de la herramienta del lado del servidor.
  • Solicite autorización para operaciones delicadas o irreversibles cuando sea necesario.
  • No coloque secretos de producción de larga duración directamente en el control de código fuente.

Más Allá del Ejemplo de la Recepcionista

La lógica de recepcionista incluida muestra cómo realizar búsquedas en la agenda, transferir llamadas, utilizar el buzón de voz y finalizar llamadas. La misma arquitectura se puede ampliar para admitir flujos de trabajo tales como:

  • Programación de citas.
  • Búsqueda de información sobre clientes o cuentas.
  • Encuestas automatizadas.
  • Servicios de asistencia interna de TI o de Recursos Humanos.
  • Creación y actualizaciones de tickets en el CRM.
  • Servicios de estado de pedidos o de información sobre entregas.
  • Interfaces de voz para aplicaciones empresariales personalizadas.

La aplicación sigue siendo responsable de la lógica de negocio, la validación, el manejo de errores y la seguridad de la herramienta. 3CX proporciona la conexión de llamadas, la transmisión de audio y las funciones de control de llamadas, mientras que el proveedor de IA seleccionado se encarga de la conversación en tiempo real.

Lista de Verificación de Producción

Antes de avanzar con una aplicación personalizada más allá de la etapa de pruebas:

  • Ejecútelo como un servicio administrado con reinicio automático y monitoreo de estado.
  • Proteja las credenciales de la API con un administrador de secretos y renuévelas periódicamente.
  • Limite el Servicio Principal a las extensiones y funciones necesarias.
  • Revise las políticas del proveedor de IA en materia de procesamiento de datos, retención y disponibilidad regional.
  • Informe a las personas que llaman y obtenga su consentimiento cuando sea necesario realizar grabaciones, transcripciones o divulgar información generada por IA.
  • Realice un seguimiento del uso de los proveedores, los límites de tarifa y los costos.
  • Agregue tiempos de espera, manejo de reintentos y una ruta alternativa que no dependa de la IA.
  • Pruebe las rutas de transferencia, de buzón de voz, de error y de desconexión en condiciones de llamada realistas.
  • Revise todas las herramientas de MCP habilitadas y proteja las acciones confidenciales con validaciones o aprobaciones adicionales.

Solución de Problemas

yarn No se Reconoce

Asegúrese de que tenga instalado Node.js 20 o una versión posterior y, a continuación, habilite Corepack:

corepack enable

Vuelva a ejecutar yarn install desde la raíz del repositorio.

La Autenticación del PBX Devuelve un Código 401 o 403

Compruebe que appId, appSecret y pbxBase coincidan con el entidad de servicio. Confirme que el acceso a la API de Control de Llamadas esté habilitado y que la licencia y los permisos de 3CX permitan la operación solicitada.

La Aplicación se Inicia, pero No Recibe Llamadas

Confirme que la aplicación siga en ejecución, marque el ID de cliente correcto y verifique que el DID esté asignado al Servicio Principal al realizar pruebas de llamadas externas.

Una Herramienta de MCP Aparece Desactivada

Copie el nombre exacto de la herramienta que aparece en el registro de inicio en la lista mcpTools del perfil y, a continuación, reinicie la aplicación. Además, verifique que el Servicio Principal esté autorizado para utilizar la herramienta.

Fallo en las Transferencias o en el Buzón de Voz

Verifique que el destino sea válido y accesible para el Servicio Principal. Si el filtrado de llamadas está habilitado en el perfil, confirme que se hayan recopilado los campos de filtrado requeridos antes de intentar la transferencia.

El Proveedor de IA Rechaza la Conexión

Verifique la clave API, la facturación de la cuenta, el acceso al modelo, la región, la cuota y la conectividad del WebSocket. En el caso de Qwen, confirme que la clave API y el punto final pertenezcan a la misma región y al mismo espacio de trabajo.

El Audio se Retrasa o el Agente Sufre Interrupciones Frecuentes

Verifique la latencia de la red y la pérdida de paquetes entre el servidor de la aplicación, 3CX y el proveedor de IA. Revise la configuración específica del proveedor para la detección de actividad de voz y el audio en el archivo config.yaml.

Última Actualización

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

https://www.3cx.es/docs/programmable-extensions/