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

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

Einführung

Programmierbare 3CX-Nebenstellen ermöglichen es einer extern gehosteten Anwendung, sich mit der Telefonanlage zu verbinden und wie eine native Nebenstelle zu agieren. Die Anwendung kann Anrufe entgegennehmen, Audio in beide Richtungen streamen und die Anrufsteuerung über die 3CX Call Control API verwalten.

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

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

Jedes Beispiel nutzt eine einzige bidirektionale Echtzeit-Audiositzung. Spracherkennung, logische Verarbeitung und Sprachgenerierung werden vom ausgewählten KI-Anbieter übernommen, während 3CX weiterhin die Telefonie, Anrufleitung, Nebenstellen, SIP-Trunks und DIDs bereitstellt.

Die Beispiele verbinden sich über veröffentlichte 3CX-APIs und erfordern keine Änderungen am Quellcode der Telefonanlage. Sie verbinden sich auch mit dem 3CX MCP-Endpunkt, sodass die Sprachanwendung autorisierte PBX-Tools wie die Telefonbuchsuche nutzen kann. Optionale externe MCP-Server können für Kalender, CRMs und andere Geschäftssysteme hinzugefügt werden.

Welche Option sollte ich verwenden? 

Dieser Leitfaden behandelt programmierbare Nebenstellen, bei denen die Anwendung außerhalb von 3CX auf einer von Ihnen verwalteten Infrastruktur läuft. Für eine sofort konfigurierbare Lösung nutzen Sie die integrierten 3CX KI-Agenten. Für benutzerdefinierte Anwendungen, die direkt auf dem 3CX-Server laufen, verwenden Sie KI-Anrufskripte.

Was Sie bauen werden

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

• Interne Anrufe über ihre 3CX-Client-ID entgegennehmen.
• Externe Anrufe über eine zugewiesene DID entgegennehmen.
• Ein Sprachgespräch in Echtzeit mit Ihrem ausgewählten KI-Anbieter führen.
• Das 3CX-Telefonbuch über MCP durchsuchen.
• Anrufe vermitteln, an die Mailbox senden oder über die 3CX-Anrufsteuerung beenden.
• Verbindung zu zusätzlichen MCP-Servern herstellen und dem Modell ausgewählte Tools zur Verfügung stellen.

Das mitgelieferte Agentenprofil implementiert einen einfachen Rezeptionsablauf. 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.
• Administratorrechte zum Erstellen eines API-Dienstprinzipals.
• Node.js 20 oder höher auf dem Computer oder Server, der die Anwendung hosten wird.
• Die im Repository enthaltene Yarn-Version.
• Einen 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 GitHub-Repository herunter.

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

yarn install



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

corepack enable

yarn install



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

Schritt 2: Erstellen Sie einen 3CX-Dienstprinzipal

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

• Melden Sie sich beim 3CX Webclient an und öffnen Sie Admin.
• Gehen Sie zu Admin > Integrationen > API.
• Klicken Sie auf Hinzufügen, um einen Dienstprinzipal zu erstellen.
• Geben Sie eine Client-ID ein, z. B. ai-receptionist. Dies wird zur appId der Anwendung und zur internen Nummer, die Nutzer anrufen können, um die Anwendung zu erreichen.
• Aktivieren Sie den Zugriff auf die 3CX Call Control API für die Anwendung.
• Weisen Sie optional eine DID zu, falls externe Anrufer die Anwendung direkt erreichen sollen.
• Wählen Sie optional die Nebenstellen aus, die die Anwendung überwachen oder steuern darf. Gewähren Sie nur die für den vorgesehenen Arbeitsablauf erforderlichen Rechte.
• Speichern Sie den Dienstprinzipal.
• Kopieren Sie den generierten API-Schlüssel oder das Client-Geheimnis sofort. Er wird als appSecret verwendet und nur einmal angezeigt.

Schritt 3: Wählen Sie einen KI-Provider

Verwenden Sie eines der enthaltenen Beispiele.

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

• OpenAI API-Schlüssel
• Google AI Studio API-Schlüssel
• xAI-Konsole
• Alibaba Cloud DashScope Konsole

Informationen zur aktuellen Modellverfügbarkeit, zu Stimmen, Regionen, Preisen und Ratenlimits finden Sie in der Dokumentation des ausgewählten Anbieters und in der README-Datei im entsprechenden Beispielverzeichnis.

Hinweis zur Qwen-Region: DashScope-Zugangsdaten und -Endpunkte sind regionsspezifisch. Verwenden Sie den Endpunkt, der für die Region und den Arbeitsbereich erforderlich ist, in dem der API-Schlüssel erstellt wurde.

Qwen region note: DashScope credentials and endpoints are region-specific. Use the endpoint required for the region and workspace in which the API key was created.

Schritt 4: Anbieterkonfiguration erstellen

Kopieren Sie config.yaml.example nach 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



Verwenden Sie in der Windows PowerShell Copy-Item anstelle von cp.

Öffnen Sie die neue Datei config.yaml 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 englische und chinesische Profile.

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

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



Verwenden Sie die vom Anbieter bereitgestellte config.yaml.example als Grundlage für Modell-, Sprach-, Spracherkennungs- und anbieterspezifische Einstellungen. Behalten Sie bei Qwen die regionsspezifische Basis-URL-Konfiguration des Anbieters bei.

Sicherheit: config.yaml enthält vertrauliche Daten. Sie wird durch die mitgelieferte .gitignore ausgeschlossen, dennoch sollten Sie vermeiden, sie zu teilen, zu committen oder in Support-Protokolle einzubinden. Verwenden Sie für die Produktion einen Secret-Manager oder eine umgebungsbasierte Bereitstellungsmethode.

Schritt 5: Starten Sie die Anwendung

Führen Sie den Befehl für den ausgewählten Anbieter aus dem 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 hat sich 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 Anruf-Handler 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 Client-ID des Dienstprinzipals, die als appId konfiguriert ist.

Wenn die Client-ID beispielsweise ai-receptionist lautet, wählen Sie ai-receptionist über den 3CX Webclient, 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 Arbeitsablauf, bevor Sie ihn anpassen:

• Bestätigen Sie, dass der Agent mit der konfigurierten Begrüßung antwortet.
• Bitten Sie darum, mit einem bekannten Telefonbuchkontakt verbunden zu werden.
• Bestätigen Sie, dass der Agent das Telefonbuch über MCP durchsucht.
• Testen Sie eine erfolgreiche Vermittlung.
• Testen Sie den Pfad für nicht erreichbare Nutzer und die Mailbox.
• Unterbrechen Sie den Agenten während des Sprechens, um das Barge-in-Verhalten zu überprüfen.
• Beenden Sie den Anruf und bestätigen Sie, dass die Anwendung den Anruf korrekt trennt.

Stoppen Sie die Anwendung mit Strg+C.

Agenten anpassen

Grundeinstellungen wie der Firmenname und der Name des Agenten werden in config.yaml gespeichert.

Detaillierteres Verhalten wird durch das YAML-Profil im Verzeichnis agents des ausgewählten Beispiels definiert. Je nach Anbieterbeispiel heißt das Standardprofil receptionist.yaml.

Das Profil steuert Bereiche wie:

• Die Rolle und den System-Prompt.
• Begrüßungen und Sprachverhalten.
• Anforderungen an die Anrufprüfung (Call Screening).
• Verfügbarkeitsprüfungen vor der Vermittlung.
• Zulässige Anrufaktionen.
• Blockierte Nebenstellen.
• Richtlinien für Spam, Feindseligkeit und nicht-kooperative Anrufer.
• Die dem Modell zur Verfügung gestellten MCP-Tools.

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

Halten Sie Prompts und Tool-Berechtigungen aufeinander abgestimmt. Dem Modell zu sagen, dass es eine Aktion ausführen kann, gewährt der zugrundeliegenden Anwendung oder dem Dienstprinzipal nicht automatisch die Berechtigung dazu.

3CX MCP-Tools verwenden

Beim Start verbinden sich die Beispiele mit dem 3CX MCP-Endpunkt und ermitteln die für den authentifizierten Dienstprinzipal verfügbaren Tools.

Nur die in der Positivliste mcpTools des Agentenprofils aufgeführten Tools werden dem KI-Modell zur Verfügung gestellt. Das Standard-Rezeptionsprofil aktiviert die Telefonbuchsuche:

mcpTools:

  - list_phonebook



Das Startprotokoll zeigt die vom Server ermittelten Tools und ob jedes einzelne aktiviert ist. Um ein weiteres autorisiertes Tool freizugeben, fügen Sie dessen genauen Namen zu mcpTools hinzu und starten Sie die Anwendung neu.

Beschränken Sie die Liste auf das kleinste für den Arbeitsablauf erforderliche Set an Tools. Ein Tool, das dem Modell nicht zur Verfügung gestellt wird, kann vom Modell nicht aufgerufen werden.

Zusätzliche MCP-Server verbinden

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

Die Beispiele unterstützen auth.type: bearer oder none für ein einfaches Testen. Für einen schnellen Test ohne eigenen MCP-Server können Sie einen gehosteten MCP-Aggregator wie Smithery AI oder Zapier nutzen. Erstellen Sie ein Konto und fügen Sie die Remote-URL und das Bearer-Token in customMcpServers ein. 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 Agenten zur Verfügung stellen möchten, unter seinem genauen Namen im Agentenprofil hinzu:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add



Tools, die von benutzerdefinierten MCP-Servern ermittelt wurden, werden mit den verfügbaren 3CX MCP-Tools zusammengeführt, aber die Positivliste des Profils behält die Kontrolle darüber, welche Tools das Modell verwenden kann.

Beim Hinzufügen externer MCP-Server:

• Verwenden Sie Zugriffsrechte nach dem Prinzip der geringsten Rechte (Least Privilege).
• Geben Sie nur die erforderlichen Tools frei.
• Validieren Sie Tool-Parameter serverseitig.
• Fordern Sie bei sensiblen oder unumkehrbaren Operationen gegebenenfalls eine Genehmigung an.
• Legen Sie langlebige Produktions-Geheimnisse nicht direkt in der Quellcodeverwaltung ab.

Über das Rezeptionsbeispiel hinausgehen

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

• Terminplanung.
• Abfrage von Kunden- oder Kontoinformationen.
• Automatisierte Umfragen.
• Interne IT- oder HR-Helpdesks.
• CRM-Ticketerstellung und -aktualisierungen.
• Bestellstatus- oder Lieferinformationsdienste.
• Sprachschnittstellen für benutzerdefinierte Geschäftsanwendungen.

Die Anwendung bleibt verantwortlich für Geschäftslogik, Validierung, Fehlerbehandlung und Tool-Sicherheit. 3CX stellt die Anrufverbindung, das Audio-Streaming und die Anrufsteuerungsfunktionen bereit, während der ausgewählte KI-Anbieter das Echtzeitgespräch führt.

Produktionscheckliste

Bevor Sie eine benutzerdefinierte Anwendung über die Testphase hinaus einsetzen:

• Betreiben Sie sie als verwalteten Dienst mit automatischem Neustart und Überwachung des Systemzustands.
• Schützen Sie API-Zugangsdaten mit einem Secret-Manager und erneuern Sie sie regelmäßig.
• Beschränken Sie den Dienstprinzipal auf die erforderlichen Nebenstellen und Funktionen.
• Überprüfen Sie die Richtlinien des KI-Anbieters zu Datenverarbeitung, Speicherung und regionaler Verfügbarkeit.
• Informieren Sie Anrufer und holen Sie deren Einwilligung ein, sofern Aufzeichnung, Transkription oder KI-Offenlegung erforderlich sind.
• Überwachen Sie Nutzung, Ratenlimits und Kosten des Anbieters.
• Fügen Sie Timeouts, Fehlerbehandlung bei Wiederholungsversuchen und eine Nicht-KI-Ausweichroute hinzu.
• Testen Sie Vermittlungs-, Mailbox-, Fehler- und Trennungspfade unter realistischen Anrufbedingungen.
• Überprüfen Sie jedes aktivierte MCP-Tool und schützen Sie sensible Aktionen mit zusätzlicher 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 aus dem Stammverzeichnis des Repositorys aus.

PBX-Authentifizierung gibt Fehlercode 401 oder 403 zurück

Überprüfen Sie, ob appId, appSecret und pbxBase mit dem Dienstprinzipal übereinstimmen. Bestätigen Sie, dass der Zugriff auf die Call Control API aktiviert ist und dass die 3CX-Lizenz sowie die Berechtigungen den angeforderten Vorgang zulassen.

Die Anwendung startet, empfängt aber keine Anrufe

Bestätigen Sie, dass die Anwendung weiterhin läuft, wählen Sie die korrekte Client-ID und stellen Sie sicher, dass die DID dem Dienstprinzipal zugewiesen ist, wenn Sie externe Anrufe testen.

Ein MCP-Tool scheint deaktiviert zu sein

Kopieren Sie den genauen Tool-Namen aus dem Startprotokoll in die Liste mcpTools des Profils und starten Sie die Anwendung neu. Bestätigen Sie außerdem, dass der Dienstprinzipal zur Nutzung des Tools berechtigt ist.

Weiterleitungen oder Mailbox-Fehler

Stellen Sie sicher, dass das Ziel gültig und für den Dienstprinzipal zugänglich ist. Wenn die Anrufprüfung im Profil aktiviert ist, bestätigen Sie, dass die erforderlichen Prüffelder vor dem Vermittlungsversuch erfasst wurden.

Der KI-Provider lehnt die Verbindung ab

Überprüfen Sie API-Schlüssel, Kontobreachnung, Modellzugriff, Region, Kontingent und WebSocket-Konnektivität. Stellen Sie bei Qwen sicher, dass API-Schlüssel und Endpunkt zur selben Region und demselben Arbeitsbereich gehören.

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

Prüfen Sie Netzwerklatenz und Paketverlust zwischen Anwendungshost, 3CX und dem KI-Anbieter. Überprüfen Sie die anbieterspezifischen Einstellungen für Spracherkennung und Audio in config.yaml.

Letztes Update

Dieses Dokument wurde zuletzt am 21. September 2026 aktualisiert

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