Erstellen Sie Ihre eigene KI-Sprachanwendung mit programmierbaren 3CX-Nebenstellen

Verbinden Sie eine extern gehostete KI-Sprachanwendung mit 3CX mithilfe der Call Control API, des Call Control SDK und eines unterstützten Echtzeit-KI-Anbieters.

Einführung

3CX Programmable Extensions ermöglichen es einer extern gehosteten Anwendung, sich mit der Telefonanlage zu verbinden und wie eine native Nebenstelle zu funktionieren. Die Anwendung kann Anrufe empfangen, Audio in beide Richtungen streamen und die Anrufweiterleitung über die 3CX Call Control API steuern.

Die Agentic AI Call Control-Beispiele bieten funktionierende Node.js-Anwendungen für:

• OpenAI Realtime
• Google Gemini Live
• xAI Grok Voice Agent
• Alibaba Cloud Qwen Omni Realtime

Jedes Beispiel nutzt eine einzelne bidirektionale Echtzeit-Audiositzung. Spracherkennung, logisches Denken und Sprachgenerierung werden vom ausgewählten KI-Anbieter übernommen, während 3CX weiterhin Telefonie, Anrufweiterleitung, Nebenstellen, SIP-Trunks und DIDs bereitstellt.

Die Beispiele nutzen veröffentlichte 3CX-APIs und erfordern keine Änderungen am PBX-Quellcode. Sie stellen außerdem eine Verbindung zum 3CX-MCP-Endpunkt her, sodass die Sprachanwendung autorisierte PBX-Tools wie die Telefonbuchsuche verwenden kann. Optional können externe MCP-Server für Kalender, CRM-Systeme und andere Geschäftssysteme hinzugefügt werden.

Welche Option soll ich wählen?

Dieser Leitfaden behandelt programmierbare Nebenstellen, bei denen die Anwendung außerhalb von 3CX auf einer von Ihnen verwalteten Infrastruktur ausgeführt wird. Für eine sofort konfigurierbare Lösung verwenden Sie die integrierten 3CX KI-Agenten. Für benutzerdefinierte Anwendungen, die direkt auf dem 3CX-Server ausgeführt werden, verwenden Sie KI-Aufrufskripte.

Was Sie bauen werden

Am Ende dieser Anleitung verfügen Sie über eine externe KI-Sprachanwendung, die Folgendes kann:

• Empfangen Sie interne Anrufe über Ihre 3CX-Client-ID.
• Empfangen Sie externe Anrufe über eine zugewiesene Rufnummer.
• Führen Sie Sprachgespräche in Echtzeit mit Ihrem ausgewählten KI-Anbieter.
• Durchsuchen Sie das 3CX-Telefonbuch über MCP.
• Leiten Sie Anrufe weiter, senden Sie sie an die Mailbox oder beenden Sie sie über die 3CX-Anrufsteuerung.
• Verbinden Sie sich mit weiteren MCP-Servern und stellen Sie ausgewählte Tools dem Modell zur Verfügung.

Das bereitgestellte Agentenprofil implementiert einen grundlegenden Empfangsablauf. Es dient als Ausgangspunkt und kann für Terminbuchungen, Kundeninformationen, Umfragen, interne Helpdesks und andere Arbeitsabläufe erweitert werden.

Bevor Sie beginnen

Sie benötigen:

• Ein 3CX V20 Update 10-System mit Zugriff auf die Call Control API.
• Administratorzugriff zum Erstellen eines API-Dienstprinzipals.
• Node.js 20 oder höher auf dem Computer oder Server, auf dem die Anwendung gehostet wird.
• Die im Repository enthaltene Yarn-Version.
• Ein API-Schlüssel und verfügbares Kontingent für mindestens einen unterstützten KI-Anbieter.
• Netzwerkzugriff vom Anwendungshost auf den 3CX HTTPS FQDN und die WebSocket-Endpunkte des ausgewählten Anbieters.

Schritt 1: Beispiele herunterladen

Klonen oder laden Sie das Agentic Call Control-Repository herunter: Öffnen Sie das Agentic Call Control-Repository

Wechseln Sie im Terminal in das Stammverzeichnis des Repositorys und installieren Sie alle Workspace-Abhängigkeiten:

yarn install



Falls der yarn-Befehl nicht verfügbar ist, aktivieren Sie zuerst Corepack:

corepack enable

yarn install



Führen Sie yarn install nicht separat in jedem Provider-Verzeichnis aus. Das Repository ist ein Yarn-Workspace und sollte vom Stammverzeichnis aus installiert werden.

Schritt 2: Erstellen Sie einen 3CX-Dienstprinzipal

Erstellen Sie die Anmeldeinformationen, die die externe Anwendung zur Authentifizierung an der Telefonanlage verwenden wird.

• Melden Sie sich im 3CX Web Client an und öffnen Sie die Administration.
• Gehen Sie zu Integrationen > API.
• Klicken Sie auf Hinzufügen, um einen Dienstprinzipal zu erstellen.
• Geben Sie eine Client-ID ein, z. B. ai-receptionist. Diese wird zur App-ID der Anwendung und zur internen Rufnummer, die Benutzer wählen können, um die Anwendung zu erreichen.
• Aktivieren Sie den API-Zugriff für 3CX Call Control für die Anwendung.
• Optional können Sie eine Durchwahlnummer (DID) zuweisen, falls externe Anrufer die Anwendung direkt erreichen müssen.
• Optional können Sie die Nebenstellen auswählen, die die Anwendung überwachen oder steuern darf. Gewähren Sie nur die für den gewünschten Workflow erforderlichen Zugriffsrechte.
• Speichern Sie den Dienstprinzipal.
• Kopieren Sie den generierten API-Schlüssel bzw. das Client-Geheimnis sofort. Es wird als App-Geheimnis verwendet und nur einmal angezeigt.

Schritt 3: Wählen Sie einen KI-Provider

Verwenden Sie eines der beigefügten Beispiele.

Erstellen Sie den API-Schlüssel in der Konsole des ausgewählten Anbieters und bewahren Sie ihn sicher auf:

• OpenAI API keys
• Google AI Studio API keys
• xAI Console
• Alibaba Cloud DashScope Console

Informationen zur aktuellen Modellverfügbarkeit, zu Sprachoptionen, Regionen, Preisen und Ratenbegrenzungen finden Sie in der Dokumentation des jeweiligen Anbieters und in der README-Datei im entsprechenden Beispielverzeichnis.

Qwe-Regionsnotiz: Die Anmeldeinformationen und Endpunkte von DashScope sind regionsspezifisch. Verwenden Sie den Endpunkt, der für die Region und den Arbeitsbereich erforderlich ist, in dem der API-Schlüssel erstellt wurde.

Schritt 4: Anbieterkonfiguration erstellen

Kopieren Sie die Datei config.yaml.example in die Datei config.yaml im ausgewählten Beispielverzeichnis.

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



Unter Windows PowerShell verwenden Sie Copy-Item anstelle von cp.

Öffnen Sie die neue config.yaml-Datei und geben Sie die allgemeinen 3CX-Werte ein:

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



Behalten Sie den vom ausgewählten Beispiel bereitgestellten Wert für agentProfile bei. OpenAI, Gemini und xAI verwenden receptionist; Qwen enthält separate Profile für Englisch und Chinesisch.

Als Nächstes legen Sie die Anmeldeinformationen für den ausgewählten Anbieter fest. Die OpenAI-Konfiguration enthält beispielsweise Folgendes:

openaiApiKey: sk-your-openai-api-key



Verwenden Sie die vom Anbieter bereitgestellte Datei config.yaml.example als maßgebliche Quelle für Modell-, Sprach-, Sprachaktivitätserkennungs- und anbieterspezifische Einstellungen. Behalten Sie für Qwen die regionsspezifische Basis-URL-Konfiguration des Anbieters bei.

Sicherheitshinweis: Die Datei config.yaml enthält Geheimnisse. Sie ist zwar in der bereitgestellten .gitignore-Datei ausgeschlossen, dennoch sollten Sie vermeiden, sie weiterzugeben, in Commits zu speichern oder in Support-Logs aufzunehmen. Verwenden Sie für den Produktivbetrieb einen Geheimnismanager oder eine umgebungsbasierte Bereitstellungsmethode.

Schritt 5: Starten Sie die Anwendung

Führen Sie den Befehl für den ausgewählten Provider im Stammverzeichnis des Repositorys aus.

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen



Die genaue Ausgabe beim Start variiert je nach Anbieter. Ein erfolgreicher Start sollte Folgendes bestätigen:

• Die Anwendung wurde bei 3CX authentifiziert.
• Das Call Control SDK und die WebSocket-Verbindung sind aktiv.
• Die Anwendung hat sich mit dem 3CX MCP-Endpunkt verbunden.
• Die aktivierten MCP-Tools wurden geladen.
• Der Anrufhandler ist initialisiert und die Anwendung ist bereit, Anrufe entgegenzunehmen.

Schritt 6: Anwendung anrufen und testen

Einen internen Anruf tätigen

Wählen Sie von einer registrierten 3CX-Nebenstelle die als appId konfigurierte Service Principal Client ID.

Wenn die Client-ID beispielsweise ai-receptionist lautet, wählen Sie ai-receptionist über den 3CX Web Client, die Desktop-App, die mobile App oder ein bereitgestelltes Telefon.

Einen externen Anruf tätigen

Wenn Sie dem Dienstprinzipal eine DID zugewiesen haben, rufen Sie diese Nummer von einem externen Telefon aus an.

Empfohlene Tests

Testen Sie den gesamten Workflow, bevor Sie ihn anpassen:

• Vergewissern Sie sich, dass der Agent mit der konfigurierten Begrüßung antwortet.
• Bitten Sie darum, mit einem bekannten Kontakt aus dem Telefonbuch zu sprechen.
• Prüfen Sie, ob der Agent das Telefonbuch über MCP durchsucht.
• Testen Sie eine erfolgreiche Weiterleitung.
• Testen Sie die Weiterleitung an nicht erreichbare Teilnehmer und die Mailbox.
• Unterbrechen Sie den Agenten während des Gesprächs, um sein Verhalten beim Einschalten zu überprüfen.
• Beenden Sie den Anruf und vergewissern Sie sich, dass die Anwendung die Verbindung korrekt trennt.

Beenden Sie die Anwendung mit Strg+C.

Agenten anpassen

Grundlegende Einstellungen wie Firmenname und Agentenname werden in der Datei config.yaml gespeichert.

Das detailliertere Verhalten wird durch das YAML-Profil im Agentenverzeichnis des ausgewählten Beispiels definiert. Je nach Anbieterbeispiel heißt das Standardprofil receptionist.yaml, receptionist_en.yaml oder receptionist_cn.yaml.

Das Profil steuert Bereiche wie:

• Rolle und Systemansagen.
• Begrüßungen und Sprachverhalten.
• Anforderungen an die Anruferkennung.
• Verfügbarkeitsprüfung vor der Weiterleitung.
• Zulässige Anrufaktionen.
• Blockierte Nebenstellen.
• Richtlinien zu Spam, feindseligen und nicht kooperativen Anrufern.
• Die im Modell verfügbaren MCP-Tools.

Starten Sie die Anwendung neu, nachdem Sie entweder die Datei config.yaml oder das ausgewählte Agentenprofil geändert haben.

Stellen Sie sicher, dass Eingabeaufforderungen und Werkzeugberechtigungen aufeinander abgestimmt sind. Die Information an das Modell, dass es eine Aktion ausführen kann, gewährt der zugrunde liegenden Anwendung oder dem Dienstprinzipal nicht die Berechtigung, diese Aktion auszuführen.

3CX MCP-Tools verwenden

Beim Start stellen die Beispiele eine Verbindung zum 3CX MCP-Endpunkt her und ermitteln die für den authentifizierten Dienstprinzipal verfügbaren Tools.

Nur die im Agentenprofil in der Zulassungsliste mcpTools aufgeführten Tools werden dem KI-Modell angezeigt. Das Standardprofil für Rezeptionisten aktiviert die Telefonbuchsuche.

mcpTools:

  - list_phonebook



Das Startprotokoll zeigt die vom Server erkannten Tools und deren Aktivierungsstatus an. Um ein weiteres autorisiertes Tool zu aktivieren, fügen Sie dessen genauen Namen zu mcpTools hinzu und starten Sie die Anwendung neu.

Beschränken Sie die Liste auf die für den Workflow erforderlichen Tools. Ein Tool, das dem Modell nicht zur Verfügung steht, kann vom Modell nicht aufgerufen werden.

Zusätzliche MCP-Server verbinden

Optionale MCP-Server können unter customMcpServers in config.yaml konfiguriert werden. Dadurch erhält die Sprachanwendung Zugriff auf genehmigte Kalender-, CRM- oder Geschäftsprozess-Tools.

Die Beispiele unterstützen zur Vereinfachung von Tests auth.type: bearer or auth.type: none. Für einen schnellen Test ohne eigenen MCP-Server verwenden Sie einen gehosteten Connector wie Smithery: Fügen Sie die Remote-URL und das Bearer-Token in  customMcpServers ein und aktivieren Sie anschließend die ermittelten Tool-Namen in mcpTools.

customMcpServers:

  - name: GoogleCalendar

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

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true



Fügen Sie jedes Tool, das Sie dem Agentenprofil zur Verfügung stellen möchten, unter Angabe seines genauen Namens hinzu:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add



Die von benutzerdefinierten MCP-Servern ermittelten Tools werden mit den verfügbaren 3CX MCP-Tools zusammengeführt, die Profil-Zulassungsliste behält jedoch die Kontrolle darüber, welche Tools das Modell verwenden darf.

Beim Hinzufügen externer MCP-Server:

• Verwenden Sie Anmeldeinformationen mit minimalen Berechtigungen.
• Stellen Sie nur die benötigten Tools bereit.
• Validieren Sie Tool-Parameter serverseitig.
• Fordern Sie gegebenenfalls eine Genehmigung für sensible oder irreversible Operationen an.
• Speichern Sie keine langlebigen Produktionsgeheimnisse direkt in der Quellcodeverwaltung.

Über das Rezeptionsbeispiel hinausgehen

Die integrierte Rezeptionslogik demonstriert Telefonbuchsuche, Weiterleitung, Mailbox und Anrufbeendigung. Dieselbe Architektur kann erweitert werden, um Arbeitsabläufe wie die folgenden zu unterstützen:

• Terminvereinbarung.
• Suche nach Kunden- oder Kontoinformationen.
• Automatisierte Umfragen.
• Interne IT- oder HR-Helpdesks.
• Erstellung und Aktualisierung von CRM-Tickets.
• Bestellstatus- oder Lieferinformationsdienste.
• Sprachschnittstellen für maßgeschneiderte Geschäftsanwendungen.

Die Anwendung bleibt für Geschäftslogik, Validierung, Fehlerbehandlung und Tool-Sicherheit verantwortlich. 3CX stellt die Anrufverbindung, das Audiostreaming und die Anrufsteuerung bereit, während der ausgewählte KI-Anbieter die Echtzeit-Konversation übernimmt.

Produktionscheckliste

Bevor eine benutzerdefinierte Anwendung über die Testphase hinausgeführt wird:

• Betreiben Sie den Dienst als verwalteten Dienst mit automatischem Neustart und Zustandsüberwachung.
• Schützen Sie die API-Zugangsdaten mit einem Geheimnismanager und rotieren Sie diese regelmäßig.
• Beschränken Sie den Dienstprinzipal auf die erforderlichen Nebenstellen und Funktionen.
• Überprüfen Sie die Richtlinien des KI-Anbieters zur Datenverarbeitung, Aufbewahrung und regionalen Verfügbarkeit.
• Informieren Sie Anrufer und holen Sie deren Einwilligung ein, wenn Aufzeichnungen, Transkriptionen oder die Weitergabe von KI-Daten erforderlich sind.
• Überwachen Sie die Nutzung, die Ratenbegrenzungen und die Kosten des Anbieters.
• Fügen Sie Timeouts, Wiederholungsversuche und eine alternative Route ohne KI hinzu.
• Testen Sie Weiterleitung, Mailbox, Fehlerbehandlung und Verbindungsabbruch unter realistischen Anrufbedingungen.
• Überprüfen Sie alle aktivierten MCP-Tools und schützen Sie sensible Aktionen durch zusätzliche Validierung oder Genehmigung.

Fehlerbehebung

yarn wird nicht erkannt

Stellen Sie sicher, dass Node.js 20 oder höher installiert ist, und aktivieren Sie dann Corepack:

corepack enable



Führen Sie yarn install erneut vom Stammverzeichnis des Repositorys aus.

PBX-Authentifizierung gibt Fehlercode 401 oder 403 zurück

Prüfen Sie, ob appId, appSecret und pbxBase mit dem Dienstprinzipal übereinstimmen. Stellen Sie sicher, dass der Zugriff auf die Call Control API aktiviert ist und dass die 3CX-Lizenz und -Berechtigungen die angeforderte Operation zulassen.

Die Anwendung startet, empfängt aber keine Anrufe.

Vergewissern Sie sich, dass die Anwendung noch läuft, wählen Sie die richtige Client-ID und überprüfen Sie, ob die DID dem Dienstprinzipal zugewiesen ist, wenn Sie externe Anrufe testen.

Ein MCP-Tool scheint deaktiviert zu sein

Kopieren Sie den exakten Toolnamen aus dem Startprotokoll in die mcpTools-Liste des Profils und starten Sie die Anwendung anschließend neu. Stellen Sie außerdem sicher, dass der Dienstprinzipal zur Verwendung des Tools berechtigt ist.

Weiterleitungen oder Mailbox-Fehler

Prüfen Sie, ob das Ziel gültig und für den Dienstprinzipal erreichbar ist. Wenn die Anruferkennung im Profil aktiviert ist, vergewissern Sie sich, dass die erforderlichen Erkennungsfelder vor dem Weiterleitungsversuch erfasst wurden.

Der KI-Provider lehnt die Verbindung ab

Überprüfen Sie den API-Schlüssel, die Kontoabrechnung, den Modellzugriff, die Region, das Kontingent und die WebSocket-Verbindung. Stellen Sie bei Qwen sicher, dass API-Schlüssel und Endpunkt zur selben Region und zum selben Arbeitsbereich gehören.

Die Audioübertragung ist verzögert oder der Agent wird häufig unterbrochen.

Prüfen Sie die Netzwerklatenz und den Paketverlust zwischen dem Anwendungshost, 3CX und dem KI-Anbieter. Überprüfen Sie die anbieterspezifischen Einstellungen zur Spracherkennung und Audioeinstellungen in der Datei config.yaml.

Letztes Update

Dieser Leitfaden wurde zuletzt am 31. Juli 2026 aktualisiert.

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