Utwórz głosowego agenta OpenAI Realtime

Wprowadzenie

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

Skrypt zawiera również 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 OpenAI 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 openaivoiceagent.cs.

  • Wprowadź nazwę skryptu małymi literami bez spacji, np. openaireception.
  • Wybierz sposób uruchamiania skryptu; w przypadku recepcjonisty przypisz dedykowany numer DID lub skieruj odpowiednie połączenia przychodzące z trunku do skryptu.
  • Wybierz dział, który jest właścicielem skryptu.
  • Potwierdź wybór, aby otworzyć edytor kodu.

Konfiguracja OpenAI i skryptu

Dodaj następujące parametry do 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 wartości te są puste, skrypt automatycznie odczytuje klucz API i model z parametrów centrali PBX.

Nie wpisuj 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 pierwszeństwo przed odpowiadającym mu parametrem PBX.

Następnie przejrzyj poniższe ustawienia użytkownika znajdujące się na początku 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

Funkcja AddAll() jest wygodna dla wstępnych testów, ale powinna być wyłączona przed wdrożeniem produkcyjnym. Ustaw AllowAllVisibilityForTesting na false, a następnie skonfiguruj tylko te numery, działy i role, których potrzebuje agent.

Aby włączyć przykładowe narzędzie niestandardowe, przejrzyj jego statyczną odpowiedź i usuń komentarz (uncomment):

RegisterExampleCustomTool();

Zastąp przykład zaufanym źródłem danych przed użyciem go do obsługi prawdziwych informacji o klientach.

Wybierz „Save” (Zapisz), aby skompilować skrypt. Przed skierowaniem do niego ruchu produkcyjnego upewnij się, że w oknie „Script output” widnieje komunikat o pomyślnej kompilacji.

Jak to działa

  • Połączenie przychodzące dociera do punktu trasy skryptu.
  • Skrypt czyści i buduje na nowo listę widoczności katalogu dla AI.
  • 3CX przygotowuje kanał mediów.
  • Skrypt uruchamia sesję głosową OpenAI Realtime.
  • Agent korzysta wyłącznie z wbudowanych funkcji 3CX oraz jawnie zarejestrowanych narzędzi niestandardowych.
  • Pomyślne przełączenie przekazuje dzwoniącego do wybranego miejsca docelowego w 3CX.
  • Jeśli konfiguracja mediów lub sesja dostawcy zawiedzie, skrypt próbuje skorzystać ze skonfigurowanej trasy zapasowej („fallback”), a jeśli routing również zawiedzie, odtwarza komunikat ERROR.

Testowanie skryptu

  • Zadzwoń na przypisany numer DID i sprawdź powitanie oraz wybrany głos.
  • Wyszukaj dozwolony numer wewnętrzny po nazwie i numerze.
  • Potwierdź, że ukryte numery wewnętrzne nie mogą być wyszukiwane ani wybierane.
  • Przetestuj zachowanie przy niejednoznacznym dopasowaniu w katalogu.
  • Przetestuj przełączanie, pocztę głosową dla niedostępnego użytkownika oraz zachowanie wiadomości na czacie.
  • Użyj nieprawidłowego klucza dostawcy w środowisku testowym i zweryfikuj routing zapasowy (fallback).
  • Zakończ rozmowę w naturalny sposób i potwierdź zamknięcie sesji.

Rozwiązywanie problemów

  • Sesja dostawcy nie uruchamia się: Sprawdź klucz OPENAI_API_KEY, wspierany model „realtime”, dostęp do sieci, licencjonowanie oraz docelową wersję PBX.
  • Agent nie może znaleźć użytkownika: Sprawdź ustawienia AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments oraz VisibleRoles.
  • Widoczne są niewłaściwe obiekty: Wywołaj funkcję Clear() przed dodaniem produkcyjnej listy widoczności i unikaj korzystania z AddAll().
  • Fallback nie działa: Potwierdź, że miejsce docelowe istnieje i jest osiągalne z przypisanego działu.
  • Nie słychać komunikatu o błędzie: Potwierdź, że komunikat ERROR istnieje w aktywnym zestawie komunikatów.

Zobacz również


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