Utwórz głosowego agenta Grok xAI Realtime

Wprowadzenie

Przykładowy skrypt grokvoiceagent.cs łączy połączenie przychodzące 3CX z sesją głosową Grok xAI Realtime. Agent może odpowiadać dzwoniącym, przeszukiwać zatwierdzony katalog firmowy, łączyć rozmowy, oferować pocztę głosową lub czat, a także zapisywać kontekst rozmówcy po odpowiedniej konfiguracji.

Przykład 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 xAI API.

Utworzenie skryptu połączeń w 3CX

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

• Wybierz grokvoiceagent.cs.

• Wprowadź nazwę skryptu małymi literami bez spacji, np. grokreception.
• Wybierz sposób uruchamiania skryptu i przypisz wymagany numer DID, trasę trunku lub wewnętrzne miejsce docelowe.
• Przypisz skrypt do działu.
• Przejdź do edytora kodu.

Konfiguracja xAI i skryptu

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

• GROK_API_KEY - klucz API dla Twojego konta xAI.
• GROK_REALTIME_MODEL - model głosowy Grok Realtime.

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

Nie wpisuj klucza Grok 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 i powinna być używana normalnie tylko do tymczasowych testów.

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

Przed wdrożeniem produkcyjnym ustaw AllowAllVisibilityForTesting na false i udostępnij tylko wymagane obiekty katalogu.

Aby aktywować opcjonalny przykład narzędzia, przejrzyj jego procedurę obsługi (handler) i usuń komentarz (uncomment):

RegisterExampleCustomTool();



Wybierz „Save” (Zapisz) i potwierdź pomyślną kompilację w sekcji „Script output”.

Jak to działa

• Dzwoniący dociera do skryptu.
• Skrypt tworzy ograniczoną listę widoczności katalogu.
• 3CX przygotowuje kanał mediów i rozpoczyna sesję głosową Grok xAI Realtime.
• Agent rozmawia z dzwoniącym i wywołuje zatwierdzone funkcje 3CX.
• Przełączenia są realizowane za pomocą narzędzi, a nie tylko poprzez deklaracje słowne (conversational promises).
• Awaria dostawcy lub mediów kieruje dzwoniącego do skonfigurowanego miejsca zapasowego (fallback).

Testowanie skryptu

• Potwierdź wybrany głos Grok i zachowanie wielojęzyczne.
• Wyszukaj dozwolone oraz ukryte numery wewnętrzne.
• Potwierdź, że agent wykonuje przełączenie po potwierdzeniu przez dzwoniącego.
• Przetestuj pocztę głosową i czat, gdy użytkownik jest niedostępny.
• Pożegnaj się i sprawdź, czy sesja kończy się normalnie.
• Przetestuj awarię dostawcy i zachowanie trasy zapasowej (fallback).

Rozwiązywanie problemów

• Sesja kończy się natychmiast: Sprawdź GROK_API_KEY, wspierany model, licencję, wersję systemu PBX oraz łączność wychodzącą z dostawcą.
• Przełączenie jest zapowiadane, ale nie wykonywane: Potwierdź, że niestandardowe instrukcje nadal wymagają użycia narzędzia połączenia i nie zostały nadpisane.
• Wyszukiwanie w katalogu zwraca zbyt wiele wyników: Wyłącz AddAll() i ogranicz widoczność.
• Błąd fallbacku: Sprawdź uprawnienia do miejsca docelowego i działu.
• Brak komunikatu: Potwierdź, że komunikat ERROR istnieje w aktywnym zestawie komunikatów.

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/grok-ai-voice-agent/