Utwórz głosowego agenta Grok xAI Realtime

Wprowadzenie

Przykładowy skrypt grokvoiceagent.cs łączy przychodzące połączenie 3CX z sesją głosową w czasie rzeczywistym xAI Grok. Agent może odpowiadać dzwoniącym, przeszukiwać zatwierdzoną książkę telefoniczną firmy, łączyć rozmowy, oferować pocztę głosową lub czat oraz zapisywać kontekst rozmówcy po odpowiedniej konfiguracji.

Próbka zawiera również wyłączone domyślnie niestandardowe narzędzie get_department_hours, które pokazuje, jak zarejestrować bezpieczną funkcję możliwą do wywołania przez sztuczną inteligencję.

Skrypt wymaga licencji 3CX AI, centrali PBX w wersji Update 10 oraz konta API xAI.

Tworzenie skryptu połączenia w systemie 3CX

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

  • Wybierz plik grokvoiceagent.cs.

  • Wprowadź nazwę skryptu pisaną małymi literami bez spacji, na przykład grokreception.
  • Wybierz sposób uruchamiania skryptu i przypisz wymagany numer DID, trasę łącza TRUNK lub wewnętrzny punkt docelowy.
  • Przypisz skrypt do odpowiedniego działu (Department).
  • Przejdź do edytora kodu.

Konfiguracja xAI oraz skryptu

Dodaj następujące chronione parametry w 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 wprowadzaj 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 priorytet nad odpowiadającym jej parametrem PBX i powinna być stosowana wyłącznie do tymczasowych testów.

Następnie przejrzyj poniższe ustawienia znajdujące się w górnej części skryptu:

Ustawienie

Cel

Przykładowa wartość

FallbackDestination

Trasa używana po awarii dostawcy lub mediów

102

VoiceName

Głos Grok Realtime

Eve

AgentName

Nazwa sesji agenta

Eve

AllowAllVisibilityForTesting

Pozwala na szeroką widoczność podczas wstępnych testów

true

VisibleNumbers

Wyraźnie zatwierdzone miejsca docelowe 3CX

100, 102

VisibleDepartments

Zatwierdzone działy

Sales, Support

VisibleRoles

Opcjonalny filtr ról

puste

AgentInstructions

Zachowanie firmy i polityka routingu

Example Company

Przed wdrożeniem produkcyjnym ustaw AllowAllVisibilityForTesting na false i udostępnij tylko wymagane obiekty książki telefonicznej.

Aby aktywować opcjonalny przykład narzędzia (custom tool), przejrzyj jego procedurę obsługi i odkomentuj w kodzie:

RegisterExampleCustomTool();

Kliknij Save (Zapisz) i potwierdź pomyślną kompilację w sekcji wyjściowej skryptu (Script output).

Jak to działa

  • Dzwoniący dociera do skryptu.
  • Skrypt tworzy ograniczoną listę widoczności książki telefonicznej.
  • System 3CX przygotowuje kanał mediów i uruchamia sesję głosową Grok realtime.
  • Agent rozmawia z dzwoniącym i wywołuje zatwierdzone funkcje 3CX.
  • Transfery są wykonywane za pomocą dedykowanych narzędzi, a nie samych deklaracji w rozmowie.
  • Awaria dostawcy lub mediów kieruje dzwoniącego do skonfigurowanej trasy zapasowej (Fallback).

Testowanie skryptu

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

Rozwiązywanie problemów

  • Sesja kończy się natychmiastowym błędem: Sprawdź parametr GROK_API_KEY, obsługiwany model, licencję, wersję kompilacji PBX oraz łączność wychodzącą do dostawcy.
  • Transfer jest zapowiadany, ale nie zostaje wykonany: Potwierdź, że instrukcje niestandardowe nadal wymagają użycia narzędzia połączeniowego i nie zostały nadpisane.
  • Wyszukiwanie w książce telefonicznej zwraca zbyt wiele wyników: Wyłącz AddAll() i ogranicz widoczność.
  • Trasa zapasowa (Fallback) nie działa: Sprawdź punkt docelowy oraz uprawnienia działu.
  • Brak komunikatu: Potwierdź, że komunikat ERROR istnieje w aktywnym zestawie komunikatów głosowych.

Zobacz również


Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 9 września 2026 r.
https://www.3cx.pl/docs/grok-ai-voice-agent/