KI-Provider für programmierbare 3CX-Nebenstellen
Einführung
Mit programmierbaren 3CX-Nebenstellen können Entwickler KI-Agenten erstellen, die Live-Anrufe über das 3CX-Telefonsystem bearbeiten.
3CX Agentic Call Control ist eine Sammlung vorgefertigter Codebeispiele für den Aufbau dieser KI-Agenten. Jedes Beispiel verbindet eine programmierbare Nebenstelle mit einem Echtzeit-KI-Provider wie OpenAI, xAI, Gemini oder Qwen und stellt dem Agenten die relevanten 3CX-Anrufsteuerungsfunktionen zur Verfügung.
Diese Anleitung zeigt, wie Sie OpenAI, xAI, Gemini oder Qwen auswählen, das entsprechende Beispiel mit Ihren 3CX- und Provider-Anmeldedaten konfigurieren, es starten und einen Testanruf tätigen.
Bevor Sie beginnen
Laden Sie den 3CX Agentic Call Control Quellcode herunter und extrahieren Sie ihn. Alle vier Beispiele sind im selben Paket enthalten.
Wählen Sie OpenAI, xAI, Google Gemini oder Alibaba Cloud Qwen und verwenden Sie dann den Beispielordner und die Konfigurationswerte für diesen Provider.
- 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-Providers.
- 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
Gehen Sie nach dem Herunterladen des 3CX Agentic Call Control Quellcodes in den Hauptordner; dieser enthält package.json, examples und packages.
Im Ordner "examples" finden Sie den entsprechenden Providerspezifischen Agentic Call Control Code:
- examples/openai-realtime
- examples/xai-realtime
- examples/gemini-realtime
- examples/alibaba-qwen-realtime
In jedem der Beispielordner müssen Sie config.yaml.example finden, 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 PBX-Verbindungs- und Providereinstellungen, die die Funktion des programmierbaren Nebenstellencodes ermöglichen.
Erstellen eines 3CX Service Principal
Öffnen Sie in der Telefonanlage Admin > Integrationen > API und wählen Sie Service Principal hinzufügen.
- Geben Sie eine Client-ID ein, z. B.: „assistant“.
- Aktivieren Sie "Zugriff auf die 3CX Call Control API für diese Anwendung erlauben".
- Wenn Sie systemweite Kontaktsuche und Präsenzprüfung für den Agenten wünschen, müssen Sie außerdem Folgendes aktivieren: „Zugriff auf die 3CX Konfigurations-API (XAPI) für diese Anwendung erlauben. Stellen Sie Abteilung und Rolle entsprechend den gewünschten Fähigkeiten des Agenten ein.
- 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 Integrationen > API > Client-ID
- appSecret: Service Principal PBX API-Schlüssel aus Integrationen > API > API-Schlüssel generieren
- pbxBase: PBX-Adresse
- openaiApiKey: OpenAI API-Schlüssel von OpenAI API-Keys
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 Werkzeuge (1/8):
✗ list_peers: Listet interne Nummern jeglicher Art auf (Nebenstellen, Warteschleifen, Rufgruppen, IVRs usw.). Unterstützt das Filtern nach Name, Nummer oder Typ.
✗ get_server_time: Ruft die aktuelle Serverzeit in UTC und lokaler Zeitzone ab.
✗ get_edit_url: Ruft einen anklickbaren Link ab, um eine DN (Nebenstelle, Warteschleife, Rufgruppe, IVR, Trunk usw.) im Editor der Verwaltungskonsole zu öffnen.
✗ find_extension: Findet einen Kontakt anhand der exakten Nebenstellennummer
✗ control_participant: Steuert einen aktiven Anrufteilnehmer: Trennen, Antworten, Umleiten, Routeto oder Transferto.
✗ find_by_email: Findet einen Kontakt anhand der E-Mail-Adresse
✗ list_crm_contacts: Sucht nach Kontakten im CRM-System (Customer Relationship Management)
✓ list_phonebook: Sucht nach Kontakten im Telefonbuch nach Name, Nummer, E-Mail oder Unternehmen
[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 Integrationen > API > Client-ID
- appSecret: Service Principal PBX API-Schlüssel aus Integrationen > API > API-Schlüssel generieren
- pbxBase: PBX-Adresse
- xaiApiKey: xAI API-Schlüssel von console.x.ai
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 Werkzeuge (1/8):
✓ list_phonebook: Sucht nach Kontakten im Telefonbuch nach Name, Nummer, E-Mail oder Unternehmen
✗ control_participant: Steuert einen aktiven Anrufteilnehmer: Trennen, Antworten, Umleiten, Routeto oder Transferto.
✗ list_peers: Listet interne Nummern jeglicher Art auf (Nebenstellen, Warteschleifen, Rufgruppen, IVRs usw.). Unterstützt das Filtern nach Name, Nummer oder Typ.
✗ get_server_time: Ruft die aktuelle Serverzeit in UTC und lokaler Zeitzone ab.
✗ find_by_email: Findet einen Kontakt anhand der E-Mail-Adresse
✗ list_crm_contacts: Sucht nach Kontakten im CRM-System (Customer Relationship Management)
✗ get_edit_url: Ruft einen anklickbaren Link ab, um eine DN (Nebenstelle, Warteschleife, Rufgruppe, IVR, Trunk usw.) im Editor der Verwaltungskonsole zu öffnen.
✗ find_extension: Findet einen Kontakt anhand der exakten Nebenstellennummer
[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 Integrationen > API > Client-ID
- appSecret: Service Principal PBX API-Schlüssel aus Integrationen > API > API-Schlüssel generieren
- pbxBase: PBX-Adresse
- geminiApiKey: Google AI Studio API-Schlüssel von Google AI Studio
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 Werkzeuge (1/8):
✓ list_phonebook: Sucht nach Kontakten im Telefonbuch nach Name, Nummer, E-Mail oder Unternehmen
✗ control_participant: Steuert einen aktiven Anrufteilnehmer: Trennen, Antworten, Umleiten, Routeto oder Transferto.
✗ list_peers: Listet interne Nummern jeglicher Art auf (Nebenstellen, Warteschleifen, Rufgruppen, IVRs usw.). Unterstützt das Filtern nach Name, Nummer oder Typ.
✗ get_server_time: Ruft die aktuelle Serverzeit in UTC und lokaler Zeitzone ab.
✗ find_by_email: Findet einen Kontakt anhand der E-Mail-Adresse
✗ list_crm_contacts: Sucht nach Kontakten im CRM-System (Customer Relationship Management)
✗ get_edit_url: Ruft einen anklickbaren Link ab, um eine DN (Nebenstelle, Warteschleife, Rufgruppe, IVR, Trunk usw.) im Editor der Verwaltungskonsole zu öffnen.
✗ find_extension: Findet einen Kontakt anhand der exakten Nebenstellennummer
[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 Integrationen > API > Client-ID
- appSecret: Service Principal PBX API-Schlüssel aus Integrationen > API > API-Schlüssel generieren
- pbxBase: PBX-Adresse
- dashscopeApiKey: Alibaba Cloud DashScope API-Schlüssel von 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.
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 Werkzeuge (1/8):
✓ list_phonebook: Sucht nach Kontakten im Telefonbuch nach Name, Nummer, E-Mail oder Unternehmen
✗ control_participant: Steuert einen aktiven Anrufteilnehmer: Trennen, Antworten, Umleiten, Routeto oder Transferto.
✗ list_peers: Listet interne Nummern jeglicher Art auf (Nebenstellen, Warteschleifen, Rufgruppen, IVRs usw.). Unterstützt das Filtern nach Name, Nummer oder Typ.
✗ get_server_time: Ruft die aktuelle Serverzeit in UTC und lokaler Zeitzone ab.
✗ find_by_email: Findet einen Kontakt anhand der E-Mail-Adresse
✗ list_crm_contacts: Sucht nach Kontakten im CRM-System (Customer Relationship Management)
✗ get_edit_url: Ruft einen anklickbaren Link ab, um eine DN (Nebenstelle, Warteschleife, Rufgruppe, IVR, Trunk usw.) im Editor der Verwaltungskonsole zu öffnen.
✗ find_extension: Findet einen Kontakt anhand der exakten Nebenstellennummer
[CallStore] initialized (Qwen Omni realtime)
All systems ready (Qwen realtime mode)
Testen des Agenten
Verwenden Sie eine Testnebenstelle. Verwenden Sie für Transfertests eine zweite interne Testnebenstelle. Führen Sie im Hauptordner von 3CX Agentic Call Control den Befehl für den von Ihnen konfigurierten Provider aus:
- OpenAI: yarn start:openai
- xAI: yarn start:xai
- Gemini: yarn start:gemini
- Qwen: yarn start:alibaba-qwen
Warten Sie, bis das Terminal die PBX-Verbindung und den Bereitschaftszustand anzeigt.
- Rufen Sie die Service Principal Client-ID (appId) von der Testnebenstelle aus an. Wählen Sie z. B. die wörtliche Client-ID „assistant“, um sich mit dem Agenten zu verbinden.
- Bestätigen Sie, dass der Agent antwortet, seine Begrüßung abspielt und auf Sie reagiert.
- Testen Sie eine Nebenstellensuche oder bitten Sie ihn, das Gespräch für Sie zu beenden.
- Überprüfen Sie die Terminalausgabe auf Fehler.
Anpassen des Agenten
Verwenden Sie config.yaml, um die Begrüßung und Providerspezifische 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
- 3CX Agentic Call Control
- 3CX Call Control API
- 3CX Konfigurations-API
- Call Control API Endpunkt-Spezifikation
Letztes Update
Dieses Dokument wurde zuletzt am 1. September 2026 aktualisiert
https://www.3cx.de/docs/agentic-call-control-ai-providers/
Copyright © 2025