Fornitori di IA per le estensioni programmabili

Introduzione

Le estensioni programmabili 3CX consentono agli sviluppatori di creare agenti IA in grado di gestire chiamate in tempo reale tramite il sistema telefonico 3CX.

3CX Agentic Call Control è una raccolta di esempi di codice già pronti per la creazione di tali agenti IA. Ciascun esempio collega un’estensione programmabile a un provider di IA in tempo reale, come OpenAI, xAI, Gemini o Qwen, e mette a disposizione dell’agente le relative funzioni di controllo delle chiamate di 3CX.

Questa guida illustra come scegliere tra OpenAI, xAI, Gemini o Qwen, configurare l’esempio corrispondente con le credenziali del proprio 3CX e del provider, avviarlo ed effettuare una chiamata di prova.

Prima di iniziare

Scarica ed estrai il codice sorgente di 3CX Agentic Call Control. Tutti e quattro gli esempi sono inclusi nello stesso pacchetto.

Scegli OpenAI, xAI, Google Gemini o Alibaba Cloud Qwen, quindi utilizza la cartella degli esempi e i valori di configurazione relativi a quel provider.

  • Un amministratore 3CX con accesso a Admin > Integrazioni > API in grado di creare un Service Principal.
  • Node.js 20+ installato. Yarn 4 è incluso nel repository.
  • Una chiave API con accesso al servizio in tempo reale per il provider di IA scelto.
  • Un’estensione 3CX funzionante, come il Web Client, l’app mobile o il telefono fisso, per effettuare una chiamata di prova all’agente IA.

Scaricare gli esempi

Dopo aver scaricato il codice sorgente di 3CX Agentic Call Control, accedere alla cartella principale; questa contiene i file package.json, examples, examples e packages.

Nella cartella examples troverai il codice di controllo delle chiamate agentico specifico per il provider di riferimento:

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

All'interno di ciascuna delle cartelle di esempio troverai il file config.yaml.example che dovrai copiare e rinominare in config.yaml. Lascia inalterato il file config.yaml.example in modo da poter tornare alle impostazioni originali dell'esempio, se necessario.

Il file config.yaml ontiene le impostazioni di connessione al centralino e del provider che consentono il funzionamento del codice dell'estensione programmabile.

Creare un entità di servizio 3CX

Nel centralino, aprire Admin > Integrazioni > API e selezionare Aggiungi un’entità di servizio.

  1. Inserire un ID cliente, ad esempio: “assistant”.

Create a 3CX Service Principal

  1. Abilitare l’opzione Abilita l’accesso all’API di controllo delle chiamate 3CX per questa applicazione.
  2. Se desideri che l’agente disponga di funzionalità di ricerca dei contatti e verifica della presenza a livello di sistema, dovrai anche abilitare: Abilita l’accesso all’API di configurazione 3CX (XAPI) per questa applicazione. Imposta il dipartimento e il ruolo in base alle funzionalità che desideri assegnare all’agente.

Add API Key

  1. Salvare la chiave API 3CX in un luogo sicuro.

Scegliere un provider e configurare il file config.yaml

OpenAI

  • Nel file config.yaml, inserire:
  • appId: ID cliente da Integrazioni Centralino > API > ID cliente
  • appSecret: Chiave API del servizio principale PBX da Integrazioni > API > Genera chiave API
  • pbxBase: Indirizzo del centralino
  • openaiApiKey: Chiave API OpenAI da Chiavi API OpenAI

OpenAI Configuration Example

Installare le dipendenze e avvia l'esempio di OpenAI:

yarn install

yarn start:openai

Un log di avvio di OpenAI ben riuscito include:

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

  • Nel file config.yaml, inserire:
  • appId: Client ID da Integrazioni Centralino > API > Client ID 
  • appSecret: Chiave API del soggetto di servizio PBX da Integrazioni > API > Genera chiave API
  • pbxBase: Indirizzo centralino
  • xaiApiKey: Chiave API xAI da https://console.x.ai

xAI Configuration Example

Installare le dipendenze e avviare l'esempio xAI:

yarn install

yarn start:xai

Un log di avvio corretto di xAI include:

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

  • Nel file config.yaml, inserire:
  • appId: Client ID dalla sezione Integrazioni Centralino > API > Client ID
  • appSecret: Chiave API del soggetto di servizio PBX dalla sezione Integrazioni > API > Genera chiave API
  • pbxBase: Indirizzo centralino
  • geminiApiKey: Chiave API di Google AI Studio da Google AI Studio

Gemini Configuration Example

Installare le librerie e avviare l'esempio Gemini:

yarn install

yarn start:gemini

Un log di avvio di Gemini riuscito include:

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

  • Nel file config.yaml, inserire:
  • appId: Client ID da Integrazioni Centralino > API > Client ID
  • appSecret: Chiave API del soggetto di servizio PBX da Integrazioni > API > Genera chiave API
  • pbxBase: Indirizzo del centralino
  • dashscopeApiKey: Chiave API di Alibaba Cloud DashScope disponibile in Chiave API di Alibaba Cloud DashScope
  • dashscopeBaseUrl: Utilizzare https://dashscope-intl.aliyuncs.com per una chiave internazionale/di Singapore, oppure https://dashscope.aliyuncs.com per una chiave della Cina continentale.

Qwen Configuration Example

Installare le dipendenze e avviare l'esempio di Qwen:

yarn install

yarn start:alibaba-qwen

Un log di avvio corretto di Qwen include:

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)

Testare l’agente

Utilizzare un’estensione di prova. Per testare il trasferimento, utilizzare una seconda estensione interna di prova. Dalla cartella principale “3CX Agentic Call Control”, eseguire il comando relativo al provider configurato:

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

Attendere che il terminale mostri la connessione al centralino e lo stato “pronto”.

  1. Chiamare l’ID client del Service Principal (appId) dall’estensione di prova. Ad esempio, componi letteralmente l’ID client “assistant” per collegarti all’agente.
  2. Verificare che l’agente risponda, riproduca il proprio messaggio di benvenuto e ti risponda.
  3. Provare a effettuare una ricerca di un’estensione o chiedigli di terminare la chiamata per te.
  4. Controllare l’output del terminale per verificare la presenza di errori.

Personalizza l’agente

Utilizzare il file config.yaml per modificare il messaggio di benvenuto e le impostazioni specifiche del provider. Per modificare il comportamento predefinito, modificare il file agents/receptionist.yaml oppure aggiungere un altro profilo nella directory agents/. Se si aggiunge customMcpServers, elencare i nomi esatti degli strumenti sotto mcpTools in quel profilo agente. Riavviare l’agente dopo ogni modifica alla configurazione ed effettua un’altra chiamata di prova.

Per saperne di più

Ultimo aggiornamento
Questo documento è stato aggiornato il 28 agosto 2026
https://www.3cx.it/doc/agentic-call-control-ai-providers/