KI-Provider für programmierbare 3CX-Nebenstellen

Einführung

Programmierbare 3CX-Nebenstellen ermöglichen Entwicklern das Erstellen von KI-Agenten, die Live-Anrufe über das 3CX-Telefonanlage bearbeiten.

3CX Agentic Call Control ist eine Sammlung fertiger Codebeispiele zur Erstellung dieser KI-Agenten. Jedes Beispiel verbindet eine programmierbare Nebenstelle mit einem Echtzeit-KI-Anbieter wie OpenAI, xAI, Gemini oder Qwen und stellt dem Agenten die relevanten 3CX-Anrufsteuerungsfunktionen zur Verfügung.

Dieser Leitfaden zeigt, wie Sie OpenAI, xAI, Gemini oder Qwen auswählen, das passende Beispiel mit Ihren 3CX- und Anbieter-Zugangsdaten konfigurieren, starten und einen Testanruf tätigen.

Bevor Sie beginnen

Laden Sie den Quellcode von 3CX Agentic Call Control herunter und entpacken Sie ihn. Alle vier Beispiele sind im selben Paket enthalten.

Wählen Sie OpenAI, xAI, Google Gemini oder Alibaba Cloud Qwen aus und verwenden Sie dann den Beispielordner und die Konfigurationswerte für diesen Anbieter.

  • Ein 3CX-Administrator mit Zugriff auf Admin > Integrationen > API, der einen Service Principal erstellen kann.
  • Node.js 20+ installiert. Yarn 4 ist im Repository enthalten.
  • Ein API-Schlüssel mit Zugriff auf den Echtzeitdienst des von Ihnen gewählten KI-Anbieters.
  • Eine funktionierende 3CX-Nebenstelle, z. B. der Webclient, die mobile App oder ein Tischtelefon, um einen Testanruf an den KI-Agenten zu tätigen.

Beispiele abrufen

Wechseln Sie nach dem Herunterladen des Quellcodes von 3CX Agentic Call Control in den Hauptordner; dieser enthält package.json, examples und packages.

Im Ordner "examples" finden Sie den entsprechenden anbieterspezifischen Code für die Agenten-Call-Control:

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

In jedem der Beispielordner müssen Sie config.yaml.example kopieren und die Kopie in config.yaml umbenennen. Lassen Sie config.yaml.example unverändert, damit Sie bei Bedarf zu den ursprünglichen Beispieleinstellungen zurückkehren können.

Die Datei config.yaml enthält die Telefonanlagen-Verbindungs- und Anbietereinstellungen, die für die Ausführung des Codes der programmierbaren Nebenstelle erforderlich sind.

Erstellen eines 3CX Service Principal

Öffnen Sie in der Telefonanlage Admin > Integrationen > API und wählen Sie Service Principal hinzufügen.

  1. Geben Sie eine Client-ID ein, z. B.: "assistant".

Erstellen eines 3CX Service Principal

  1. Aktivieren Sie "Zugriff auf die 3CX Call Control API für diese Anwendung aktivieren".
  2. Wenn Sie systemweite Kontaktsuch- und Präsenzprüfungsfunktionen für den Agenten wünschen, müssen Sie auch Folgendes aktivieren: "Zugriff auf die 3CX Konfigurations-API (XAPI) für diese Anwendung aktivieren". Stellen Sie Abteilung & Rolle entsprechend den gewünschten Funktionen des Agenten ein.

Erstellen eines 3CX Service Principal

  1. Speichern Sie den 3CX API-Schlüssel an einem sicheren Ort.

Wählen Sie einen Provider und konfigurieren Sie config.yaml

OpenAI

  • Geben Sie in config.yaml Folgendes ein:
  • appId: Client-ID aus der Telefonanlage Admin > Integrationen > API > Client ID
  • appSecret: Service Principal API-Schlüssel der Telefonanlage aus Admin > Integrationen > API > API-Schlüssel generieren
  • pbxBase: Adresse der Telefonanlage
  • openaiApiKey: OpenAI API-Schlüssel aus OpenAI API Keys

OpenAI

Installieren Sie die Abhängigkeiten und starten Sie das OpenAI-Beispiel:

yarn install

yarn start:openai

Ein erfolgreiches OpenAI-Startprotokoll enthält:

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

  • Geben Sie in config.yaml Folgendes ein:
  • appId: Client-ID aus der Telefonanlage Admin > Integrationen > API > Client ID
  • appSecret: Service Principal API-Schlüssel der Telefonanlage aus Admin > Integrationen > API > API-Schlüssel generieren
  • pbxBase: Adresse der Telefonanlage
  • xaiApiKey: xAI API-Schlüssel aus console.x.ai

xAI

Installieren Sie die Abhängigkeiten und starten Sie das xAI-Beispiel:

yarn install

yarn start:xai

Ein erfolgreiches xAI-Startprotokoll enthält:

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

  • Geben Sie in config.yaml Folgendes ein:
  • appId: Client-ID aus der Telefonanlage Admin > Integrationen > API > Client ID
  • appSecret: Service Principal API-Schlüssel der Telefonanlage aus Admin > Integrationen > API > API-Schlüssel generieren
  • pbxBase: Adresse der Telefonanlage
  • geminiApiKey: Google AI Studio API-Schlüssel aus Google AI Studio

Gemini

Installieren Sie die Abhängigkeiten und starten Sie das Gemini-Beispiel:

yarn install

yarn start:gemini

Ein erfolgreiches Gemini-Startprotokoll enthält:

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

  • Geben Sie in config.yaml Folgendes ein:
  • appId: Client-ID aus der Telefonanlage Admin > Integrationen > API > Client ID
  • appSecret: Service Principal API-Schlüssel der Telefonanlage aus Admin > Integrationen > API > API-Schlüssel generieren
  • pbxBase: Adresse der Telefonanlage
  • dashscopeApiKey: Alibaba Cloud DashScope API-Schlüssel aus Alibaba Cloud DashScope API key
  • dashscopeBaseUrl: Verwenden Sie https://dashscope-intl.aliyuncs.com für einen internationalen/Singapur-Schlüssel oder https://dashscope.aliyuncs.com für einen Schlüssel für Festlandchina.

Qwen

Installieren Sie die Abhängigkeiten und starten Sie das Qwen-Beispiel:

yarn install

yarn start:alibaba-qwen

Ein erfolgreiches Qwen-Startprotokoll enthält:

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

Testen des Agenten

Verwenden Sie eine Test-Nebenstelle. Für Weiterleitungstests verwenden Sie eine zweite interne Test-Nebenstelle. Führen Sie im Hauptordner von 3CX Agentic Call Control den Befehl für den von Ihnen konfigurierten Anbieter aus:

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

Warten Sie, bis das Terminal die Telefonanlagen-Verbindung und den Bereitschaftszustand anzeigt.

  1. Rufen Sie die Service Principal Client-ID (appId) von der Test-Nebenstelle an. Wählen Sie z. B. die wörtliche Client-ID "assistant", um sich mit dem Agenten zu verbinden.
  2. Bestätigen Sie, dass der Agent antwortet, seine Begrüßung abspielt und auf Sie reagiert.
  3. Testen Sie eine Nebenstellensuche oder bitten Sie ihn, den Anruf für Sie zu beenden.
  4. Überprüfen Sie die Terminalausgabe auf Fehler.

Anpassen des Agenten

Verwenden Sie config.yaml, um die Begrüßung und anbieterspezifische Einstellungen zu ändern. Um das Standardverhalten zu ändern, bearbeiten Sie agents/receptionist.yaml oder fügen Sie ein weiteres Profil in agents/ hinzu. Wenn Sie customMcpServers hinzufügen, listen Sie die genauen Werkzeugnamen unter mcpTools in diesem Agentenprofil auf. Starten Sie den Agenten nach jeder Konfigurationsänderung neu und tätigen Sie einen weiteren Testanruf.

Siehe auch

Letztes Update
Dieses Dokument wurde zuletzt am 21. September 2026 aktualisiert
https://www.3cx.de/docs/agentic-call-control-ai-providers/