Anrufskript: Erstellen eines OpenAI-Echtzeit-Sprachagenten

Einführung

Das Beispielskript openaivoiceagent.cs verbindet einen eingehenden 3CX-Anruf mit einer OpenAI-Echtzeit-Sprachsitzung. Es kann Anrufer begrüßen, allgemeine Fragen beantworten, die zulässigen 3CX-Verzeichniseinträge durchsuchen, Anrufer verbinden, Mailbox oder Chat anbieten und – sofern aktiviert – nützliche Anruferkontexte speichern.

Das Skript enthält außerdem ein deaktiviertes benutzerdefiniertes Tool namens get_department_hours, das die Registrierung einer sicheren, KI-aufrufbaren Funktion demonstriert.

Für dieses Skript benötigen Sie eine 3CX AI Edition-Lizenz, eine PBX-Version Update 10 und ein OpenAI-API-Konto.

Erstellen des Anrufskripts in 3CX

• Melden Sie sich in der 3CX-Administrationskonsole an.
• Gehen Sie zu Integrationen > Anrufskripte.
• Wählen Sie „+Aus Store hinzufügen“.

• Wählen Sie openaivoiceagent.cs.

• Geben Sie einen Skriptnamen in Kleinbuchstaben ohne Leerzeichen ein, z. B. openaireception.
• Wählen Sie die Ausführungsmethode des Skripts aus. Weisen Sie beispielsweise einer Rezeption eine dedizierte Rufnummer zu oder leiten Sie die entsprechenden eingehenden Anrufe an das Skript weiter.
• Wählen Sie die Abteilung aus, der das Skript gehört.
• Bestätigen Sie Ihre Auswahl, um den Code-Editor zu öffnen.

OpenAI und das Skript konfigurieren

Fügen Sie der Telefonanlage die folgenden Parameter hinzu:

• OPENAI_API_KEY - der API-Schlüssel für Ihr OpenAI-Projekt.
• OPENAI_REALTIME_MODEL - das OpenAI-Echtzeitmodell.

Lassen Sie ApiKeyOverride und ModelOverride im Skript leer. Wenn diese Werte leer sind, liest das Skript den API-Schlüssel und das Modell automatisch aus den PBX-Parametern.

Geben Sie den OpenAI-API-Schlüssel nicht direkt im Skript ein, insbesondere wenn das Skript geteilt, exportiert oder veröffentlicht werden soll. Ein in ApiKeyOverride oder ModelOverride konfigurierter Wert hat Vorrang vor dem entsprechenden PBX-Parameter.

Überprüfen Sie anschließend die Kundeneinstellungen im oberen Bereich von openaivoiceagent.cs:

Die Funktion AddAll() eignet sich zwar für erste Tests, sollte aber vor dem Produktiveinsatz deaktiviert werden. Setzen Sie AllowAllVisibilityForTesting auf false und konfigurieren Sie anschließend nur die Nummern, Abteilungen und Rollen, die der Agent benötigt.

Um das benutzerdefinierte Beispieltool zu aktivieren, überprüfen Sie dessen statische Antwort und entfernen Sie die Kommentarzeichen vor der entsprechenden Zeile.

RegisterExampleCustomTool();



Ersetzen Sie das Beispiel durch eine vertrauenswürdige Datenquelle, bevor Sie es für echte Kundendaten verwenden.

Wählen Sie „Speichern“, um zu kompilieren. Vergewissern Sie sich, dass die Skriptausgabe eine erfolgreiche Kompilierung meldet, bevor Sie den Produktivverkehr zuweisen.

So funktioniert es

• Ein eingehender Anruf erreicht den Skript-Routingpunkt.
• Das Skript löscht und aktualisiert die Sichtbarkeitsliste des KI-Verzeichnisses.
• 3CX bereitet den Medienkanal vor.
• Das Skript startet eine OpenAI-Echtzeit-Sprachsitzung.
• Der Agent verwendet ausschließlich die integrierten 3CX-Funktionen und alle explizit registrierten benutzerdefinierten Tools.
• Bei erfolgreicher Weiterleitung wird der Anrufer an das ausgewählte 3CX-Ziel weitergeleitet.
• Falls die Medieneinrichtung oder die Provider-Sitzung fehlschlägt, versucht das Skript den konfigurierten Ausweichkanal und gibt anschließend die Fehlermeldung aus, falls auch die Weiterleitung fehlschlägt.

Testen Sie das Skript

• Rufen Sie die zugewiesene Rufnummer an und bestätigen Sie die Begrüßung und die gewählte Stimme.
• Suchen Sie anhand von Name und Nummer nach einer zulässigen Nebenstelle.
• Stellen Sie sicher, dass versteckte Nebenstellen weder gesucht noch ausgewählt werden können.
• Testen Sie eine mehrdeutige Verzeichnisübereinstimmung.
• Testen Sie die Weiterleitung, die Mailbox für nicht erreichbare Nutzer und das Verhalten von Chatnachrichten.
• Verwenden Sie einen ungültigen Provider-Schlüssel in einer Testumgebung und überprüfen Sie das alternative Routing.
• Beenden Sie das Gespräch regulär und bestätigen Sie die Sitzungsbereinigung.

Fehlerbehebung

• Die Provider-Sitzung schlägt fehl: Überprüfen Sie den OPENAI_API_KEY, das unterstützte Echtzeitmodell, den Netzwerkzugriff, die Lizenzierung und die Ziel-PBX-Version.
• Der Agent findet keinen Nutzer: Überprüfen Sie AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments und VisibleRoles.
• Falsche Objekte sind sichtbar: Rufen Sie „Clear()“ auf, bevor Sie die Sichtbarkeitsliste für die Produktion hinzufügen, und vermeiden Sie AddAll().
• Fallback funktioniert nicht: Stellen Sie sicher, dass das Ziel existiert und von der zugewiesenen Abteilung aus erreichbar ist.
• Es wird keine Fehlermeldung ausgegeben: Stellen Sie sicher, dass ERROR in der aktiven Promptgruppe vorhanden ist.

Siehe auch

• Erstellen eines Anrufverarbeitungsskripts
• Beispiel-Anrufverarbeitungsskript für PIN 
• 3CX-Administrationshandbuch

Letztes Update

Dieser Leitfaden wurde zuletzt am 31. Juli 2026 aktualisiert.

https://www.3cx.de/docs/open-ai-voice-agent/