Utwórz głosowego agenta OpenAI Realtime

Wprowadzenie

Przykładowy skrypt openaivoiceagent.cs łączy przychodzące połączenie 3CX z sesją głosową OpenAI Realtime. Może on witać dzwoniących, odpowiadać na ogólne pytania, przeszukiwać dozwolone wpisy w książce telefonicznej 3CX, łączyć rozmówców, oferować pocztę głosową lub czat oraz zapisywać przydatny kontekst dzwoniącego, gdy ta funkcja jest włączona.

Skrypt 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 OpenAI.

Tworzenie skryptu połączenia w systemie 3CX

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

  • Wybierz plik openaivoiceagent.cs.

  • Wprowadź nazwę skryptu pisaną małymi literami bez spacji, na przykład  openaireception.
  • Wybierz sposób uruchamiania skryptu; w przypadku recepcjonisty przypisz dedykowany numer DID lub skieruj odpowiednie przychodzące połączenia z łączy TRUNK do skryptu.
  • Wybierz dział (Department), do którego należy skrypt.
  • Potwierdź wybór, aby otworzyć edytor kodu.

Konfiguracja OpenAI oraz skryptu

Dodaj następujące parametry w centrali PBX:

  • OPENAI_API_KEY - klucz API dla Twojego projektu OpenAI.
  • OPENAI_REALTIME_MODEL - model OpenAI 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 OpenAI 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.

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

Ustawienie

Cel

Przykładowa wartość

FallbackDestination

Trasa używana, gdy zawiodą media lub sesja AI

102

VoiceName

Głos OpenAI używany przez agenta

Coral

AgentName

Nazwa prezentowana w sesji dostawcy

Alex

AllowAllVisibilityForTesting

Udostępnia wszystkie obsługiwane obiekty katalogu

true

VisibleNumbers

Zatwierdzone numery wewnętrzne, kolejki lub grupy dzwonienia

100, 102

VisibleDepartments

Działy, które AI może przeszukiwać

Sales, Support

VisibleRoles

Opcjonalne dozwolone role

puste

AgentInstructions

Tożsamość firmy, zachowanie i reguły routingu

Example Company

Opcja AddAll() jest wygodna podczas wstępnych testów, ale przed wdrożeniem produkcyjnym należy ją wyłączyć. Ustaw AllowAllVisibilityForTesting na false, a następnie skonfiguruj tylko te numery, działy i role, których agent rzeczywiście potrzebuje.

Aby włączyć przykładowe narzędzie niestandardowe (custom tool), przejrzyj jego statyczną odpowiedź i odkomentuj w kodzie:

RegisterExampleCustomTool();

Zastąp przykładowy kod zaufanym źródłem danych przed użyciem go do przetwarzania prawdziwych informacji o klientach.

Kliknij Save (Zapisz), aby skompilować kod. Potwierdź, że sekcja wyjściowa skryptu (Script output) zgłasza pomyślną kompilację przed skierowaniem ruchu produkcyjnego.

Jak to działa

  • Połączenie przychodzące dociera do punktu trasowania skryptu.
  • Skrypt czyści i odbudowuje listę widoczności obiektów dla AI.
  • System 3CX przygotowuje kanał mediów.
  • Skrypt uruchamia sesję głosową OpenAI Realtime.
  • Agent używa wyłącznie wbudowanych funkcji 3CX oraz wszelkich jawnie zarejestrowanych narzędzi niestandardowych.
  • Pomyślny transfer przekazuje dzwoniącego do wybranego punktu docelowego w 3CX.
  • Jeśli konfiguracja mediów lub sesja dostawcy nie powiedzie się, skrypt próbuje użyć skonfigurowanej trasy zapasowej (Fallback), a jeśli trasowanie również zawiedzie, odtwarza komunikat ERROR.

Testowanie skryptu

  • Zadzwoń na przypisany numer DID i potwierdź powitanie oraz wybrany głos.
  • Wyszukaj dozwolony numer wewnętrzny według nazwy i numeru.
  • Potwierdź, że ukryte numery wewnętrzne nie mogą być wyszukiwane ani wybierane.
  • Przetestuj przypadek dwuznacznego dopasowania w książce telefonicznej (np. dwa podobne nazwiska).
  • Przetestuj transfer połączenia, zachowanie poczty głosowej w przypadku niedostępności użytkownika oraz funkcję wiadomości czat.
  • Użyj nieprawidłowego klucza dostawcy w środowisku testowym i zweryfikuj działanie trasowania zapasowego (Fallback).
  • Zakończ rozmowę w naturalny sposób i potwierdź zamknięcie sesji.

Rozwiązywanie problemów

  • Sesja dostawcy nie powodzi się: Sprawdź parametr OPENAI_API_KEY, obsługiwany model realtime, dostęp do sieci, licencjonowanie oraz docelową wersję kompilacji PBX.
  • Agent nie może znaleźć użytkownika: Sprawdź ustawienia AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments oraz VisibleRoles.
  • Widoczne są niewłaściwe obiekty: Wywołaj Clear() przed dodaniem produkcyjnej listy widoczności i unikaj stosowania AddAll().
  • Trasa zapasowa (Fallback) nie działa: Potwierdź, że cel istnieje i jest osiągalny z poziomu przypisanego działu.
  • Brak komunikatu o błędzie: 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/open-ai-voice-agent/