Anrufskript: Erstellen eines Gemini-Echtzeit-Sprachagenten

Einführung

Das Beispiel geminivoiceagent.cs verbindet einen eingehenden 3CX-Anruf mit Google Gemini Live. Der Agent kann Anrufer begrüßen, zugelassene Verzeichnisobjekte verwenden, Anrufe weiterleiten, Sprachnachrichten oder Chats anbieten und – sofern konfiguriert – nützlichen Anruferkontext speichern.

Das Skript enthält ein deaktiviertes benutzerdefiniertes Tool get_department_hours, das demonstriert, wie eine sichere, vom KI-System aufrufbare Funktion registriert wird.

Dieses Skript erfordert eine 3CX AI Edition-Lizenz, eine PBX-Version ab Update 10 sowie ein Gemini-API-Konto.

Erstellen des Anrufskripts in 3CX

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

• Wählen Sie geminivoiceagent.cs.

• Geben Sie einen klein geschriebenen Namen ohne Leerzeichen ein, zum Beispiel geminireception.
• Wählen Sie aus, wie das Skript ausgeführt werden soll, und weisen Sie die erforderliche DID, die Trunk-Route oder ein internes Ziel zu.
• Wählen Sie die zuständige Abteilung aus.
• Fahren Sie mit dem Code-Editor fort.

Gemini und das Skript konfigurieren

Fügen Sie der PBX die folgenden geschützten Parameter hinzu:

• GEMINI_API_KEY – der API-Schlüssel für Ihr Google AI-Projekt.
• GEMINI_REALTIME_MODEL – das Gemini-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 Gemini-API-Schlüssel nicht direkt im Skript ein, insbesondere wenn das Skript geteilt, exportiert oder veröffentlicht wird. Ein in ApiKeyOverride oder ModelOverride konfigurierter Wert hat Vorrang vor dem entsprechenden PBX-Parameter.

Überprüfen Sie als Nächstes diese Kundeneinstellungen im oberen Bereich des Skripts:

Setzen Sie AllowAllVisibilityForTesting vor der Produktion auf false und konfigurieren Sie die kleinstmögliche praktische Sichtbarkeitsliste.

Um das optionale Funktionsbeispiel zu aktivieren, überprüfen Sie dessen Daten und entfernen Sie die Auskommentierung:

RegisterExampleCustomTool();



Wählen Sie ‘Speichern’ und überprüfen Sie die erfolgreiche Kompilierung.

So funktioniert es

1. Ein eingehender Anruf erreicht den Skript-Routenpunkt.
2. Das Skript löscht und baut die zulässige 3CX-Verzeichnissichtbarkeit von Gemini neu auf.
3. 3CX bereitet den Medienkanal vor.
4. Das Skript startet die Gemini Live-Sprachsitzung mit den konfigurierten Anweisungen, der Stimme, dem Agentennamen, dem API-Schlüssel und dem Modell.
5. Genehmigte Tools führen Verzeichnis-, Weiterleitungs-, Sprachnachrichten-, Chat- und Kontextaktionen aus.
6. Fehler werden an das konfigurierte Ausweichziel geleitet und verwenden die Ansage ERROR, falls keine Weiterleitung verfügbar ist.

Testen Sie das Skript

• Überprüfen Sie die ausgewählte Gemini-Stimme und das Verhalten bezüglich der Sprache des Anrufers.
• Suchen Sie nach zulässigen Verzeichnisobjekten.
• Stellen Sie sicher, dass verborgene Ziele nicht ausgewählt werden können.
• Testen Sie Weiterleitungsbestätigung, Sprachnachricht und Chat.
• Testen Sie eine natürliche Verabschiedung.
• Simulieren Sie einen Anbieterfehler und bestätigen Sie die Ausweich-Weiterleitung.

Fehlerbehebung

• Gemini-Sitzung schlägt fehl: Überprüfen Sie den Gemini-API-Schlüssel, das unterstützte Live-Modell, die Lizenz, das PBX-Build und die ausgehende Konnektivität.
• Eine Stimme wird abgelehnt: Verwenden Sie eine Stimme, die vom konfigurierten Gemini-Modell unterstützt wird.
• Verzeichnisergebnisse fehlen: Überprüfen Sie die Sichtbarkeit von Nummern, Abteilungen und Rollen.
• Zu viele Objekte werden offengelegt: Deaktivieren Sie AddAll().
• Ausweichziel oder Ansage schlägt fehl: Überprüfen Sie das Ziel und die aktive Ansage ERROR.

Siehe auch

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

Letztes Update

Dieser Leitfaden wurde zuletzt am 21. September 2026 aktualisiert.

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