Proveedores IA - Extensiones Programables de 3CX

Introducción

Las Extensiones Programables de 3CX permiten a los desarrolladores crear agentes IA que atienden llamadas en vivo a través del Sistema Telefónico 3CX.

El Control de Llamadas de Agente 3CX es un conjunto de ejemplos de código listos para usar que permiten desarrollar esos agentes IA. Cada ejemplo conecta una Extensión Programable con un proveedor IA en tiempo real, como OpenAI, xAI, Gemini o Qwen, y pone a disposición del agente las funciones de control de llamadas pertinentes de 3CX.

Esta guía explica cómo elegir entre OpenAI, xAI, Gemini o Qwen, configurar el ejemplo correspondiente con sus credenciales de 3CX y de su proveedor, iniciarlo y realizar una llamada de prueba.

Antes de Comenzar

Descargue y descomprima el código fuente de Control de Llamada de Agente de 3CX. Los cuatro ejemplos se incluyen en el mismo paquete.

Elija OpenAI, xAI, Google Gemini o Alibaba Cloud Qwen, y luego utilice la carpeta de ejemplos y los valores de configuración correspondientes a ese proveedor.

  • Un administrador de 3CX con acceso a Admin > Integraciones > API que pueda crear un Servicio Principal.
  • Node.js 20+ instalado. Yarn 4 viene incluido en el repositorio.
  • Una clave API con acceso al servicio en tiempo real del proveedor IA que elija.
  • Una extensión de 3CX que funcione, como el Cliente Web, la aplicación móvil o un teléfono de escritorio, para realizar una llamada de prueba al agente IA.

Consulte los Ejemplos

Después de descargar el código fuente de Control de Llamadas de Agente 3CX, vaya a la carpeta principal; esta contiene el archivo package.json, examples y packages.

En la carpeta de ejemplos ('examples') encontrará el código de control de llamadas de agente específico del proveedor correspondiente:

  • examples/openai-realtime
  • examples/xai-realtime
  • examples/gemini-realtime
  • examples/alibaba-qwen-realtime

Dentro de cada una de las carpetas de ejemplo, encontrará el archivo config.yaml.example, el cual deberá copiar y renombrar como config.yaml. Mantenga el archivo config.yaml.example sin cambios para poder volver a la configuración original del ejemplo si es necesario.

El archivo config.yaml contiene la configuración de la conexión al PBX y del proveedor, lo cual permite que el código de la extensión programable funcione.

Crear un Servicio Principal de 3CX

En el PBX, abra Admin > Integraciones > API y seleccione Agregar un Servicio Principal.

  1. Introduzca un ID de cliente, por ejemplo: "asistente".

Crear Servicio Principal en 3CX

  1. Active "Habilitar acceso a la API de Control de Llamadas 3CX para esta aplicación".
  2. Si desea que el agente cuente con funciones de búsqueda de contactos y verificación de presencia en todo el sistema, también deberá habilitar la opción: "Habilitar el acceso a la API de Configuración 3CX (XAPI) para esta aplicación". Configure el departamento y el rol según las capacidades que desee que tenga el agente.

Agregar Clave API

  1. Guarde la clave API de 3CX en un lugar seguro.

Seleccionar un Proveedor y Configurar el Archivo config.yaml

OpenAI

  • En config.yaml, ingrese:
  • appId: ID de cliente del PBX desde Integraciones > API > ID de Cliente.
  • appSecret: Clave de API del Servicio Principal PBX desde Integraciones > API > Generar Clave API.
  • pbxBase: Dirección del PBX.
  • openaiApiKey: Clave API de OpenAI desde Claves API de OpenAI.

Ejemplo de Configuración OpenAI

Instale las dependencias e inicie el ejemplo de OpenAI:

yarn install

yarn start:openai

Un registro exitoso de OpenAI incluye:

openai-realtime starting

   3CX PBX: https://your-pbx.3cx.eu:5001

   OpenAI model: <configured model>

   OpenAI voice: <configured voice>

   Agent profile: receptionist (role: receptionist)

   SDK connected (auth + WebSocket + state)

[MCP] connected to https://your-pbx.3cx.eu:5001/mcp

   MCP tools (1/8):

     ✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

     ✗ get_server_time: Get the current server time in UTC and local timezone.

     ✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

     ✗ find_extension: Find a contact by exact extension number

     ✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

     ✗ find_by_email: Find a contact by email address

     ✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

     ✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

[CallStore] initialized (OpenAI Realtime mode)

All systems ready (OpenAI Realtime mode)

xAI

  • En config.yaml, ingrese:
  • appId: ID de cliente del PBX desde Integraciones > API > ID de Cliente.
  • appSecret: Clave de API del Servicio Principal PBX desde Integraciones > API > Generar Clave API.
  • pbxBase: Dirección del PBX.
  • xaiApiKey: Clave API de xAI desde console.x.ai.

Ejemplo de Configuración xAI

Instale las dependencias e inicie el ejemplo de xAI:

yarn install

yarn start:xai

Un registro exitoso de xAI incluye:

xai-realtime starting

   3CX PBX: https://your-pbx.3cx.eu:5001

   Agent profile: receptionist (role: receptionist)

   xAI Voice: tara

   SDK connected (auth + WebSocket + state)

[MCP] connected to https://your-pbx.3cx.eu:5001/mcp

   MCP tools (1/8):

     ✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

     ✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

     ✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

     ✗ get_server_time: Get the current server time in UTC and local timezone.

     ✗ find_by_email: Find a contact by email address

     ✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

     ✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

     ✗ find_extension: Find a contact by exact extension number

[CallStore] initialized (xAI realtime mode)

All systems ready (xAI realtime mode)

Gemini

  • En config.yaml, ingrese:
  • appId: ID de cliente del PBX desde Integraciones > API > ID de Cliente.
  • appSecret: Clave de API del Servicio Principal PBX desde Integraciones > API > Generar Clave API.
  • pbxBase: Dirección del PBX.
  • geminiApiKey: Clave API de Google AI Studio de Google AI Studio.

Ejemplo de Configuración Gemini

Instale las dependencias e inicie el ejemplo de Gemini:

yarn install

yarn start:gemini

Un registro exitoso de Gemini incluye:

agentic-call-control starting

   3CX PBX: https://your-pbx.3cx.eu:5001

   Gemini Voice: Kore

   Agent profile: receptionist (role: receptionist)

   SDK connected (auth + WebSocket + state)

[MCP] connected to https://your-pbx.3cx.eu:5001/mcp

     MCP tools (1/8):

     ✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

     ✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

     ✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

     ✗ get_server_time: Get the current server time in UTC and local timezone.

     ✗ find_by_email: Find a contact by email address

     ✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

     ✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

     ✗ find_extension: Find a contact by exact extension number

[CallStore] initialized (Gemini Live mode)

All systems ready (Gemini Live mode)

Qwen

  • En config.yaml, ingrese:
  • appId: ID de cliente del PBX desde Integraciones > API > ID de Cliente.
  • appSecret: Clave de API del Servicio Principal PBX desde Integraciones > API > Generar Clave API.
  • pbxBase: Dirección del PBX.
  • dashscopeApiKey: Clave API de Alibaba Cloud DashScope desde la clave API Alibaba Cloud DashScope.
  • dashscopeBaseUrl: Utilice https://dashscope-intl.aliyuncs.com para obtener una clave internacional o de Singapur, o https://dashscope.aliyuncs.com para obtener una clave de China continental.

Ejemplo de Configuración Qwen

Instale las dependencias e inicie el ejemplo de Qwen:

yarn install

yarn start:alibaba-qwen

Un registro exitoso de Qwen incluye:

alibaba-qwen-realtime starting

   3CX PBX: https://your-pbx.3cx.eu:5001

   DashScope: https://dashscope-intl.aliyuncs.com

   Model: qwen3.5-omni-plus-realtime

   Voice: Tina

   Agent profile: receptionist_en (role: receptionist)

   SDK connected (auth + WebSocket + state)

[McpManager] connected to https://your-pbx.3cx.eu:5001/mcp

   MCP tools (1/8):

     ✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

     ✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

     ✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

     ✗ get_server_time: Get the current server time in UTC and local timezone.

     ✗ find_by_email: Find a contact by email address

     ✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

     ✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

     ✗ find_extension: Find a contact by exact extension number

[CallStore] initialized (Qwen Omni realtime)

All systems ready (Qwen realtime mode)

Probar el Agente

Utilice una extensión de prueba. Para realizar pruebas de transferencia, utilice una segunda extensión interna de prueba. Desde la carpeta principal Control de Llamada de Agente 3CX, ejecute el comando correspondiente al proveedor que haya configurado:

  • OpenAI: yarn start:openai
  • xAI: yarn start:xai
  • Gemini: yarn start:gemini
  • Qwen: yarn start:alibaba-qwen

Espere a que el terminal muestre la conexión al PBX y el estado de listo.

  1. Llame al ID de Cliente del Servicio Principal (appId) desde la extensión de prueba. Por ejemplo, marque el ID de Cliente “assistant” tal como aparece para conectarse con el agente.
  2. Verifique que el agente conteste, reproduzca su mensaje de bienvenida y le responda.
  3. Pruebe la búsqueda de una extensión o solicite que se cancele la llamada por usted.
  4. Revise la salida de la terminal para ver si hay errores.

Personalizar el Agente

Utilice config.yaml para modificar el saludo y la configuración específica del proveedor. Para cambiar el comportamiento predeterminado, edite el archivo agents/receptionist.yaml o agregue otro perfil en la carpeta agents/. Si agrega customMcpServers, enumere los nombres exactos de las herramientas en la sección mcpTools de ese perfil de agente. Reinicie el agente después de cada cambio de configuración y realice otra llamada de prueba.

Ver También

Última Actualización

Este documento se actualizó por última vez el 28 de Agosto de 2026
https://www.3cx.es/docs/agentic-call-control-ai-providers/