Zbuduj własną głosową aplikację AI z programowalnymi numerami wewnętrznymi 3CX

Połącz zewnętrznie hostowaną głosową aplikację AI z 3CX, korzystając z Call Control API, Call Control SDK oraz wspieranego dostawcy AI czasu rzeczywistego (real-time).

Wprowadzenie

Programowalne numery wewnętrzne 3CX (Programmable Extensions) pozwalają aplikacji hostowanej zewnętrznie połączyć się z centralą PBX i działać jak natywny numer wewnętrzny. Aplikacja może odbierać połączenia, przesyłać strumieniowo dźwięk w obu kierunkach i kontrolować routing połączeń poprzez 3CX Call Control API.

Przykłady „Agentic Call Control” dostarczają gotowe aplikacje Node.js dla:

• OpenAI Realtime
• Google Gemini Live
• xAI Grok Voice Agent
• Alibaba Cloud Qwen Omni Realtime

Każdy przykład wykorzystuje pojedynczą, dwukierunkową sesję audio w czasie rzeczywistym. Rozpoznawanie mowy, wnioskowanie i generowanie odpowiedzi są obsługiwane przez wybranego dostawcę AI, podczas gdy 3CX nadal zapewnia telefonię, routing połączeń, numery wewnętrzne, trunki SIP oraz numery DID.

Przykłady łączą się poprzez opublikowane API 3CX i nie wymagają zmian w kodzie źródłowym centrali PBX. Łączą się one również z punktem końcowym 3CX MCP, dzięki czemu aplikacja głosowa może korzystać z autoryzowanych narzędzi centrali, takich jak przeszukiwanie książki telefonicznej. Opcjonalne zewnętrzne serwery MCP mogą zostać dodane dla kalendarzy, systemów CRM i innych systemów biznesowych.

Której opcji powinienem użyć?

Ten przewodnik dotyczy programowalnych numerów wewnętrznych (Programmable Extensions), gdzie aplikacja działa poza 3CX na infrastrukturze, którą zarządzasz. Dla gotowego do konfiguracji rozwiązania użyj wbudowanych Agentów AI 3CX. Dla niestandardowych aplikacji działających bezpośrednio na serwerze 3CX użyj skryptów połączeń AI (AI Call Scripts).

Co zbudujesz

Do końca tego przewodnika będziesz mieć zewnętrzną głosową aplikację AI, która potrafi:

• Odbierać połączenia wewnętrzne poprzez swój 3CX Client ID.
• Odbierać połączenia zewnętrzne przez przypisany numer DID.
• Prowadzić rozmowę głosową w czasie rzeczywistym przy użyciu wybranego dostawcy AI.
• Przeszukiwać książkę telefoniczną 3CX poprzez protokół MCP.
• Przełączać połączenia, wysyłać je do poczty głosowej lub kończyć je przez 3CX Call Control.
• Łączyć się z dodatkowymi serwerami MCP i udostępniać wybrane narzędzia modelowi AI.

Dostarczony profil agenta implementuje podstawowy schemat recepcjonisty. Ma on służyć jako punkt wyjścia i może zostać rozbudowany o rezerwację wizyt, informacje o klientach, ankiety, wewnętrzne działy pomocy (help desk) i inne procesy.

Zanim zaczniesz

Będziesz potrzebować:

• Systemu 3CX V20 Update 10 z dostępem do Call Control API.
• Dostępu administratora do tworzenia API Service Principal.
• Środowiska Node.js 20 lub nowszego na komputerze lub serwerze hostującym aplikację.
• Wersji Yarn dołączonej do repozytorium.
• Klucza API i dostępnego limitu (quota) dla co najmniej jednego wspieranego dostawcy AI.
• Dostępu sieciowego z hosta aplikacji do FQDN HTTPS 3CX oraz punktów końcowych WebSocket wybranego dostawcy.

Krok 1: Pobieranie przykładów

Sklonuj lub pobierz repozytorium Agentic Call Control.

W terminalu przejdź do katalogu głównego repozytorium i zainstaluj wszystkie zależności obszaru roboczego (workspace):

yarn install



Jeśli polecenie yarn nie jest dostępne, najpierw włącz Corepack:

corepack enable

yarn install



Nie uruchamiaj yarn install oddzielnie w każdym katalogu dostawcy. Repozytorium jest obszarem roboczym Yarn i powinno być instalowane z poziomu katalogu głównego (root).

Krok 2: Tworzenie 3CX Service Principal

Utwórz poświadczenia, których zewnętrzna aplikacja będzie używać do uwierzytelniania w centrali PBX.

• Zaloguj się do 3CX Web Client i otwórz „Admin”.
• Przejdź do „Integrations” (Integracje) > „API”.
• Kliknij „Add” (Dodaj), aby utworzyć „Service Principal” (Podmiot usługi).
• Wprowadź „Client ID”, na przykład ai-receptionist. Stanie się on identyfikatorem appId aplikacji oraz numerem wewnętrznym, pod który użytkownicy mogą dzwonić.
• Włącz opcję „3CX Call Control API access” dla tej aplikacji.
• Opcjonalnie przypisz numer DID, jeśli dzwoniący z zewnątrz muszą mieć możliwość bezpośredniego połączenia.
• Opcjonalnie wybierz numery wewnętrzne, które aplikacja może monitorować lub kontrolować. Przyznaj tylko taki dostęp, jakiego wymaga dany proces.
• Zapisz Service Principal.
• Skopiuj natychmiast wygenerowany klucz API lub „Client Secret”. Jest on używany jako appSecret i zostanie wyświetlony tylko raz.

Krok 3: Wybór dostawcy AI

Użyj jednego z dołączonych przykładów.

Utwórz klucz API w konsoli wybranego dostawcy i przechowuj go w bezpieczny sposób:

• Klucze API OpenAI
• Klucze API Google AI Studio
• Konsola xAI
• Konsola Alibaba Cloud DashScope

Informacje o aktualnej dostępności modeli, głosach, regionach, cenach i limitach stawek (rate limits) można znaleźć w dokumentacji wybranego dostawcy oraz w pliku README w katalogu odpowiedniego przykładu.

Uwaga dotycząca regionu Qwen: Dane uwierzytelniające i punkty końcowe (endpoints) DashScope są specyficzne dla regionu. Należy użyć punktu końcowego wymaganego dla regionu i obszaru roboczego (workspace), w którym został utworzony klucz API.

Krok 4: Tworzenie konfiguracji dostawcy

Skopiuj plik config.yaml.example to config.yaml w katalogu wybranego przykładu.

OpenAI

cp examples/openai-realtime/config.yaml.example examples/openai-realtime/config.yaml

Gemini

cp examples/gemini-realtime/config.yaml.example examples/gemini-realtime/config.yaml

xAI

cp examples/xai-realtime/config.yaml.example examples/xai-realtime/config.yaml

Alibaba Qwen

cp examples/alibaba-qwen-realtime/config.yaml.example examples/alibaba-qwen-realtime/config.yaml



W programie Windows PowerShell użyj polecenia Copy-Item zamiast cp.

Otwórz nowy plik config.yaml i wprowadź wspólne wartości dla 3CX:

appId: ai-receptionist

appSecret: your-3cx-api-key

pbxBase: https://your-pbx.example.com

companyName: Your Company

agentName: Assistant

initialGreeting: Thank you for calling. How can I help you today?



Zachowaj wartość agentProfile dostarczoną w wybranym przykładzie. OpenAI, Gemini i xAI używają profilu receptionist; Qwen zawiera oddzielne profile dla języka angielskiego i chińskiego.

Następnie ustaw dane uwierzytelniające dla wybranego dostawcy. Na przykład konfiguracja OpenAI zawiera:

openaiApiKey: sk-your-openai-api-key



Użyj dostarczonego przez dostawcę pliku config.yaml.example jako głównego źródła informacji dla ustawień modelu, głosu, wykrywania aktywności głosowej (VAD) oraz parametrów specyficznych dla danego dostawcy. W przypadku Qwen zachowaj konfigurację podstawowego adresu URL specyficzną dla danego regionu.

Bezpieczeństwo: Plik config.yaml zawiera dane wrażliwe (sekrety). Jest on wykluczony przez dostarczony plik .gitignore, ale mimo to należy unikać jego udostępniania, przesyłania do repozytorium lub dołączania do logów wsparcia technicznego. W środowisku produkcyjnym należy używać menedżera haseł lub metod wdrażania opartych na zmiennych środowiskowych.

Krok 5: Uruchomienie aplikacji

Uruchom polecenie dla wybranego dostawcy z katalogu głównego repozytorium.

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen



Dokładne informacje wyświetlane podczas uruchamiania różnią się w zależności od dostawcy. Pomyślny start powinien potwierdzić, że:

• Aplikacja uwierzytelniła się w systemie 3CX.
• SDK Call Control oraz połączenie WebSocket są aktywne.
• Aplikacja połączyła się z punktem końcowym 3CX MCP.
• Włączone narzędzia MCP zostały załadowane.
• Obsługa połączeń została zainicjowana, a aplikacja jest gotowa do przyjmowania rozmów.

Krok 6: Nawiązanie połączenia i testowanie aplikacji

Wykonanie połączenia wewnętrznego

Z zarejestrowanego numeru wewnętrznego 3CX wybierz identyfikator „Service Principal Client ID” skonfigurowany jako appId.

Na przykład, jeśli Client ID to ai-receptionist, wybierz ai-receptionist z poziomu 3CX Web Client, aplikacji desktopowej, aplikacji mobilnej lub skonfigurowanego telefonu biurkowego.

Wykonanie połączenia zewnętrznego

Jeśli przypisałeś numer DID do Service Principal, zadzwoń pod ten numer z telefonu zewnętrznego.

Sugerowane testy

Przetestuj pełny proces przepływu przed wprowadzeniem własnych zmian:

• Potwierdź, że agent odpowiada skonfigurowanym powitaniem.
• Poproś o rozmowę ze znanym kontaktem z książki telefonicznej.
• Potwierdź, że agent przeszukuje książkę telefoniczną poprzez MCP.
• Przetestuj pomyślne przełączenie rozmowy.
• Przetestuj ścieżkę dla niedostępnego użytkownika i poczty głosowej.
• Przerwij agentowi, gdy mówi, aby zweryfikować zachowanie „barge-in” (wtrącanie się w wypowiedź).
• Zakończ połączenie i potwierdź, że aplikacja poprawnie zwalnia linię.

Zatrzymaj aplikację, używając skrótu Ctrl+C.

Personalizacja agenta

Podstawowe ustawienia, takie jak nazwa firmy i nazwa agenta, są przechowywane w pliku config.yaml.

Bardziej szczegółowe zachowanie jest definiowane przez profil YAML w katalogu agents wybranego przykładu. W zależności od dostawcy, domyślny profil nosi nazwę receptionist.yaml, receptionist_en.yaml lub receptionist_cn.yaml.

Profil kontroluje takie obszary jak:

• Rola i prompt systemowy.
• Powitania i zachowanie językowe.
• Wymagania dotyczące weryfikacji połączeń (screening).
• Sprawdzanie dostępności przed przełączeniem rozmowy.
• Dozwolone akcje na połączeniach.
• Zablokowane numery wewnętrzne.
• Polityka wobec spamu, agresji oraz rozmówców niewspółpracujących.
• Narzędzia MCP udostępnione modelowi.

Zrestartuj aplikację po zmianie pliku config.yaml lub wybranego profilu agenta.

Pamiętaj o spójności promptów i uprawnień narzędzi. Poinformowanie modelu, że może wykonać daną akcję, nie nadaje automatycznie aplikacji ani podmiotowi Service Principal uprawnień do jej wykonania.

Korzystanie z narzędzi 3CX MCP

Podczas uruchamiania przykłady łączą się z punktem końcowym 3CX MCP i wykrywają narzędzia dostępne dla uwierzytelnionego Service Principal.

Tylko narzędzia wymienione na białej liście mcpTools w profilu agenta są udostępniane modelowi AI. Domyślny profil recepcjonisty włącza przeszukiwanie książki telefonicznej:

mcpTools:

  - list_phonebook



Log startowy pokazuje narzędzia wykryte na serwerze oraz informację, czy każde z nich jest włączone. Aby udostępnić inne autoryzowane narzędzie, dodaj jego dokładną nazwę do listy mcpTools i zrestartuj aplikację.

Ogranicz listę do minimalnego zestawu narzędzi wymaganego przez dany proces. Narzędzie, które nie jest udostępnione modelowi, nie może zostać przez niego wywołane.

Podłączanie dodatkowych serwerów MCP

Opcjonalne serwery MCP można skonfigurować w sekcji customMcpServers w pliku config.yaml. Może to zapewnić aplikacji głosowej dostęp do zatwierdzonych kalendarzy, systemów CRM lub narzędzi procesów biznesowych.

Przykłady obsługują typy uwierzytelniania auth.type: bearer lub auth.type: none dla wygody podczas testowania. Aby szybko przeprowadzić próbę bez uruchamiania własnego serwera MCP, użyj hostowanego konektora, takiego jak Smithery: wklej zdalny adres URL i token bearer do customMcpServers, a następnie włącz wykryte nazwy narzędzi w mcpTools.

customMcpServers:

  - name: GoogleCalendar

    url: https://mcp.example.com/your-server

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true



Dodaj każde narzędzie, które chcesz udostępnić, do profilu agenta, używając jego dokładnej nazwy:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add



Narzędzia wykryte z niestandardowych serwerów MCP są łączone z dostępnymi narzędziami 3CX MCP, ale to biała lista w profilu nadal decyduje o tym, których narzędzi model może użyć.

Podczas dodawania zewnętrznych serwerów MCP:

• Używaj poświadczeń o najniższych niezbędnych uprawnieniach (least-privilege).
• Udostępniaj tylko wymagane narzędzia.
• Weryfikuj parametry narzędzi po stronie serwera.
• Wymagaj zatwierdzenia dla wrażliwych lub nieodwracalnych operacji, jeśli jest to zasadne.
• Nie umieszczaj długoterminowych sekretów produkcyjnych bezpośrednio w systemie kontroli wersji.

Wyjście poza przykład recepcjonisty

Dołączona logika recepcjonisty demonstruje przeszukiwanie książki telefonicznej, przełączanie rozmów, pocztę głosową oraz kończenie połączeń. Tę samą architekturę można rozbudować o obsługę procesów takich jak:

• Planowanie wizyt i spotkań.
• Wyszukiwanie informacji o klientach lub kontach.
• Zautomatyzowane ankiety.
• Wewnętrzne działy pomocy IT lub HR.
• Tworzenie i aktualizacja zgłoszeń w systemach CRM.
• Usługi sprawdzania statusu zamówienia lub informacji o dostawie.
• Interfejsy głosowe dla niestandardowych aplikacji biznesowych.

Aplikacja pozostaje odpowiedzialna za logikę biznesową, walidację, obsługę błędów oraz bezpieczeństwo narzędzi. 3CX zapewnia połączenie telefoniczne, przesyłanie strumieniowe dźwięku i funkcje sterowania połączeniami, podczas gdy wybrany dostawca AI obsługuje rozmowę w czasie rzeczywistym.

Lista kontrolna przed wdrożeniem produkcyjnym

Przed przeniesieniem niestandardowej aplikacji poza fazę testów:

• Uruchamiaj ją jako usługę zarządzaną z automatycznym restartem i monitorowaniem kondycji (health monitoring).
• Chroń poświadczenia API za pomocą menedżera haseł i okresowo je zmieniaj.
• Ogranicz uprawnienia Service Principal tylko do wymaganych numerów wewnętrznych i funkcji.
• Przejrzyj polityki przetwarzania danych, retencji i dostępności regionalnej dostawcy AI.
• Informuj dzwoniących i uzyskuj zgodę w przypadkach, gdy wymagane jest nagrywanie, transkrypcja lub ujawnienie faktu rozmowy z AI.
• Monitoruj zużycie u dostawcy, limity stawek i koszty.
• Dodaj limity czasu (timeouts), obsługę ponownych prób oraz trasę zapasową (fallback) nieopartą na AI.
• Przetestuj ścieżki przełączania, poczty głosowej, awarii i rozłączania w realistycznych warunkach połączeń.
• Przejrzyj każde włączone narzędzie MCP i zabezpiecz wrażliwe działania dodatkową walidacją lub procesem zatwierdzania.

Rozwiązywanie problemów

Polecenie yarn nie jest rozpoznawane

Upewnij się, że zainstalowano Node.js w wersji 20 lub nowszej, a następnie włącz Corepack:

corepack enable



Uruchom ponownie yarn install z poziomu katalogu głównego repozytorium.

Uwierzytelnianie PBX zwraca błąd 401 lub 403

Sprawdź, czy appId, appSecret oraz pbxBase zgadzają się z danymi podmiotu Service Principal. Potwierdź, że dostęp do Call Control API jest włączony oraz że licencja i uprawnienia 3CX zezwalają na żądaną operację.

Aplikacja uruchamia się, ale nie odbiera połączeń

Upewnij się, że aplikacja nadal działa, wybierz poprawny Client ID i sprawdź, czy numer DID jest przypisany do Service Principal podczas testowania połączeń zewnętrznych.

Narzędzie MCP wydaje się być wyłączone

Skopiuj dokładną nazwę narzędzia wyświetloną w logu startowym do listy mcpTools w profilu, a następnie zrestartuj aplikację. Potwierdź również, czy Service Principal ma uprawnienia do korzystania z tego narzędzia.

Przełączenia lub poczta głosowa nie działają

Zweryfikuj, czy miejsce docelowe jest prawidłowe i osiągalne dla Service Principal. Jeśli w profilu włączono weryfikację połączeń (call screening), upewnij się, że wymagane pola weryfikacji zostały zebrane przed próbą przełączenia.

Dostawca AI odrzuca połączenie

Sprawdź klucz API, biling konta, dostęp do modelu, region, limity (quota) oraz łączność WebSocket. W przypadku Qwen potwierdź, że klucz API i punkt końcowy należą do tego samego regionu i obszaru roboczego.

Dźwięk jest opóźniony lub agent jest często przerywany

Sprawdź opóźnienia sieciowe (latency) i utratę pakietów między hostem aplikacji, 3CX a dostawcą AI. Przejrzyj ustawienia wykrywania aktywności głosowej i parametry audio specyficzne dla dostawcy w pliku config.yaml.

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