Utwórz głosowego agenta Gemini Realtime

Wprowadzenie

Przykładowy skrypt geminivoiceagent.cs łączy połączenie przychodzące 3CX z usługą Google Gemini Live. Agent może witać dzwoniących, korzystać z dozwolonych obiektów katalogu, kierować połączenia, oferować pocztę głosową lub czat, a po odpowiedniej konfiguracji – zapisywać przydatny kontekst rozmówcy.

Skrypt zawiera wyłączone narzędzie niestandardowe get_department_hours, które pokazuje, jak zarejestrować bezpieczną funkcję możliwą do wywołania przez AI.

Ten skrypt wymaga edycji 3CX AI, wersji systemu PBX Update 10 oraz konta Gemini API.

Utworzenie skryptu połączeń w 3CX

• Zaloguj się do Konsoli Administracyjnej 3CX.
• Przejdź do „Integrations” (Integracje) > „Call Scripts” (Skrypty połączeń).
• Wybierz „+Add from Store” (+Dodaj ze sklepu).

• Wybierz geminivoiceagent.cs.

• Wprowadź nazwę skryptu małymi literami bez spacji, np. geminireception.
• Wybierz sposób uruchamiania skryptu i przypisz wymagany numer DID, trasę trunku lub wewnętrzne miejsce docelowe.
• Wybierz dział będący właścicielem skryptu.
• Przejdź do edytora kodu.

Konfiguracja Gemini i skryptu

Dodaj następujące chronione parametry do centrali PBX:

• GEMINI_API_KEY - klucz API dla Twojego projektu Google AI.
• GEMINI_REALTIME_MODEL - model Gemini Realtime.

Pozostaw pola ApiKeyOverride oraz ModelOverride w skryptach puste. Gdy wartości te są puste, skrypt automatycznie odczytuje klucz API i model z parametrów centrali PBX.

Nie wpisuj klucza Gemini API bezpośrednio w skrypcie, zwłaszcza jeśli skrypt będzie udostępniany, eksportowany lub publikowany. Wartość skonfigurowana w ApiKeyOverride lub ModelOverride ma pierwszeństwo przed odpowiadającym mu parametrem PBX.

Następnie przejrzyj poniższe ustawienia użytkownika znajdujące się na początku skryptu:

Przed wdrożeniem produkcyjnym ustaw AllowAllVisibilityForTesting na false i skonfiguruj możliwie najkrótszą listę widoczności.

Aby włączyć opcjonalny przykład funkcji, przejrzyj jej dane i usuń komentarz (uncomment):

RegisterExampleCustomTool();



Wybierz „Save” (Zapisz) i sprawdź, czy kompilacja zakończyła się sukcesem.

Jak to działa

1. Połączenie przychodzące dociera do punktu trasy skryptu.
2. Skrypt czyści i buduje na nowo dozwoloną widoczność katalogu 3CX dla Gemini.
3. 3CX przygotowuje kanał mediów.
4. Skrypt rozpoczyna sesję głosową Gemini Live ze skonfigurowanymi instrukcjami, głosem, nazwą agenta, kluczem API i modelem.
5. Zatwierdzone narzędzia wykonują akcje dotyczące katalogu, przełączania, poczty głosowej, czatu i kontekstu.
6. W przypadku błędów połączenie jest kierowane do skonfigurowanego miejsca zapasowego („fallback”), a jeśli routing jest niedostępny, odtwarzany jest komunikat ERROR.

Testowanie skryptu

• Sprawdź wybrany głos Gemini i zachowanie w zależności od języka dzwoniącego.
• Wyszukaj dozwolone obiekty w katalogu.
• Upewnij się, że nie można wybrać ukrytych miejsc docelowych.
• Przetestuj potwierdzenie przełączenia, pocztę głosową i czat.
• Przetestuj naturalne pożegnanie.
• Symuluj awarię dostawcy i potwierdź routing zapasowy (fallback).

Rozwiązywanie problemów

• Sesja Gemini nie uruchamia się: Sprawdź klucz Gemini API, wspierany model „live”, licencję, wersję PBX oraz łączność wychodzącą.
• Głos jest odrzucany: Użyj głosu obsługiwanego przez skonfigurowany model Gemini.
• Brak wyników z katalogu: Sprawdź widoczność numerów, działów i ról.
• Udostępniono zbyt wiele obiektów: Wyłącz funkcję AddAll().
• Błąd fallbacku lub komunikatu: Sprawdź miejsce docelowe i aktywny komunikat ERROR.

Zobacz również

• Tworzenie skryptu przetwarzania połączeń
• Przykładowy skrypt przetwarzania połączeń dla kodu PIN
• Podręcznik administratora 3CX

Ostatnia aktualizacja
Ten przewodnik został ostatnio zaktualizowany 30 lipca 2026 r.
https://www.3cx.pl/docs/gemini-voice-agent/