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

Połącz zewnętrznie hostowaną aplikację głosową AI z systemem 3CX za pomocą interfejsu Call Control API, zestawu SDK Call Control oraz obsługiwanego dostawcy AI w czasie rzeczywistym.

Wprowadzenie

Programowalne numery wewnętrzne 3CX (3CX Programmable Extensions) pozwalają zewnętrznie hostowanej aplikacji na połączenie się z centralą PBX i działanie na zasadzie natywnego numeru wewnętrznego. Aplikacja może odbierać połączenia, przesyłać strumieniowo dźwięk w obu kierunkach i sterować kierowaniem połączeń za pośrednictwem 3CX Call Control API.

Przykłady z repozytorium Agentic Call Control dostarczają gotowe aplikacje w Node.js dla:

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

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

Przykłady łączą się poprzez opublikowane interfejsy API 3CX i nie wymagają modyfikacji kodu źródłowego centrali. Łączą się również z punktem końcowym 3CX MCP, dzięki czemu aplikacja głosowa może używać autoryzowanych narzędzi PBX (takich jak przeszukiwanie książki telefonicznej). Opcjonalne, zewnętrzne serwery MCP mogą zostać dodane w celu obsługi kalendarzy, systemów CRM i innych aplikacji biznesowych.

Którą opcję wybrać?

Ten przewodnik opisuje programowalne numery wewnętrzne (Programmable Extensions), gdzie aplikacja działa poza systemem 3CX na infrastrukturze zarządzanej przez użytkownika. Jeśli szukasz gotowego do konfiguracji rozwiązania, użyj wbudowanych Agentów 3CX AI. Z kolei w przypadku niestandardowych aplikacji działających bezpośrednio na serwerze 3CX, skorzystaj ze skryptów połączeń AI.

Co zbudujesz

Po ukończeniu tego przewodnika będziesz posiadać zewnętrzną aplikację głosową AI, która potrafi:

• Odbierać połączenia wewnętrzne za pośrednictwem swojego identyfikatora klienta 3CX (Client ID).
• Odbierać połączenia zewnętrzne poprzez przypisany numer DID.
• Prowadzić rozmowę głosową w czasie rzeczywistym przy użyciu wybranego dostawcy AI.
• Przeszukiwać książkę telefoniczną 3CX poprzez MCP.
• Przekazywać połączenia, kierować je do poczty głosowej lub kończyć za pomocą 3CX Call Control.
• Łączyć się z dodatkowymi serwerami MCP i udostępniać wybrane narzędzia modelowi.

Dostarczony profil agenta realizuje podstawowy przepływ pracy recepcjonisty. Służy jako punkt wyjścia i może zostać rozbudowany o rezerwację wizyt, obsługę informacji o klientach, ankiety, wewnętrzny helpdesk i inne procesy.

Wymagania wstępne

Wymagane elementy:

• System 3CX V20 Update 10 z dostępem do Call Control API.
• Dostęp administracyjny w celu utworzenia konta usługi API (Service Principal).
• Node.js w wersji 20 lub nowszej na komputerze/serwerze hostującym aplikację.
• Wersja Yarn dołączona do repozytorium.
• Klucz API i dostępny limit (quota) dla co najmniej jednego obsługiwanego dostawcy AI.
• Dostęp sieciowy z hosta aplikacji do adresu HTTPS FQDN centrali 3CX oraz punktów końcowych WebSocket wybranego dostawcy.

Krok 1: Pobranie przykładów

Sklonuj lub pobierz repozytorium Agentic Call Control z serwisu GitHub.

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

yarn install



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

corepack enable

yarn install



Nie uruchamiaj polecenia yarn install osobno w katalogu każdego dostawcy. Repozytorium jest obszarem roboczym Yarn (Yarn workspace) i instalacja musi odbyć się w katalogu głównym.

Krok 2: Tworzenie konta usługi 3CX (Service Principal)

Utwórz poświadczenia, które zewnętrzna aplikacja wykorzysta do uwierzytelnienia w centrali PBX:

• Zaloguj się do 3CX Web Client i otwórz sekcję Admin.
• Przejdź do Admin > Integrations (Integracje) > API.
• Kliknij Add (Dodaj), aby utworzyć konto usługi (Service Principal).
• Wprowadź identyfikator klienta (Client ID), na przykład ai-receptionist. Stanie się on identyfikatorem aplikacji (appId) i wewnętrznym numerem, na który użytkownicy mogą dzwonić, aby połączyć się z aplikacją.
• Włącz dostęp do 3CX Call Control API dla aplikacji.
• Opcjonalnie przypisz numer DID, jeśli zewnętrzni dzwoniący mają mieć możliwość bezpośredniego połączenia z aplikacją.
• Opcjonalnie wybierz numery wewnętrzne, które aplikacja ma prawo monitorować lub kontrolować. Przyznaj tylko te uprawnienia, które są niezbędne dla planowanego przepływu pracy.
• Zapisz konto usługi (Service Principal).
• Natychmiast skopiuj wygenerowany klucz API lub Client Secret. Jest on używany jako appSecret i zostanie wyświetlony tylko raz.

Krok 3: Wybór dostawcy AI

Skorzystaj z jednego z dołączonych przykładów:

Utwórz klucz API w konsoli wybranego dostawcy i zapisz go bezpiecznie:

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

Informacje na temat aktualnej dostępności modeli, głosów, regionów, cennika i limitów zapytania znajdują się w dokumentacji danego dostawcy oraz w pliku README w odpowiednim katalogu przykładu.

Uwaga dotycząca regionu Qwen: Poświadczenia i punkty końcowe DashScope są przypisane do konkretnych regionów. Użyj punktu końcowego wymaganego dla regionu i obszaru roboczego, w którym utworzono klucz API.

Krok 4: Tworzenie konfiguracji dostawcy

Skopiuj plik config.yaml.example do pliku 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 systemu 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 osobne profile angielskie i chińskie.

Następnie ustaw poświadczenie dla wybranego dostawcy. Przykładowo, konfiguracja dla OpenAI zawiera:

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



Użyj pliku config.yaml.example dostarczonego przez danego producenta jako wzorca w kwestii modelu, głosu, detekcji aktywności głosowej (VAD) oraz ustawień specyficznych dla dostawcy. W przypadku Qwen zachowaj regionalną konfigurację bazowego adresu URL.

Bezpieczeństwo: Plik config.yaml zawiera poufne dane. Jest on wykluczony przez dołączony plik .gitignore, ale należy unikać jego udostępniania, umieszczania w repozytorium czy załączania w logach wsparcia technicznego. W środowisku produkcyjnym używaj menedżera haseł/sekretów 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 komunikaty startowe różnią się w zależności od dostawcy. Pomyślne uruchomienie powinno potwierdzić, że:

• Aplikacja pomyślnie uwierzytelniła się w centrali 3CX.
• Zestaw Call Control SDK 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.
• Moduł obsługi połączeń został zainicjalizowany i aplikacja jest gotowa do przyjmowania połączeń.

Krok 6: Połączenie i testowanie aplikacji

Wykonanie połączenia wewnętrznego

Z zarejestrowanego numeru wewnętrznego 3CX zadzwoń na identyfikator klienta (Client ID), skonfigurowany jako appId.

Na przykład, jeśli Client ID to ai-receptionist, zadzwoń na numer ai-receptionist z poziomu klienta webowego 3CX, aplikacji desktopowej, aplikacji mobilnej lub skonfigurowanego telefonu stacjonarnego.

Wykonanie połączenia zewnętrznego

Jeśli do konta usługi (Service Principal) został przypisany numer DID, zadzwoń na ten numer z telefonu zewnętrznego.

Sugerowane testy

Przed dostosowaniem aplikacji przetestuj kompletny przepływ pracy:

• Potwierdź, że agent odpowiada skonfigurowanym powitaniem.
• Poproś o rozmowę z kontaktem ze znanej książki telefonicznej.
• Potwierdź, że agent przeszukuje książkę telefoniczną za pomocą MCP.
• Przetestuj pomyślne przekazanie połączenia.
• Przetestuj ścieżkę niedostępności użytkownika i przekierowania do poczty głosowej.
• Przerwij wypowiedź agenta w trakcie mówienia, aby sprawdzić zachowanie funkcji wcinania się w rozmowę (barge-in).
• Zakończ połączenie i potwierdź, że aplikacja prawidłowo zwalnia linię.

Zatrzymaj aplikację za pomocą skrótu Ctrl+C.

Dostosowywanie agenta

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

Bardziej szczegółowe zachowania są zdefiniowane w profilu YAML umieszczonym w katalogu agents wybranego przykładu. W zależności od przykładu dostawcy, domyślny profil nosi nazwę receptionist.yaml.

Profil kontroluje obszary takie jak:

• Rola i instrukcja systemowa (system prompt).
• Powitania oraz zachowanie językowe.
• Wymagania dotyczące weryfikacji/filtracji połączeń (call screening).
• Sprawdzanie dostępności przed transferem.
• Dozwolone akcje na połączeniu.
• Zablokowane numery wewnętrzne.
• Zasady dotyczące spamu, wrogości i dzwoniących nie współpracujących.
• Narzędzia MCP udostępnione modelowi.

Zrestartuj aplikację po każdej zmianie w pliku config.yaml lub w profilu agenta.

Zadbaj o spójność instrukcji (promptów) i uprawnień narzędzi. Poinformowanie modelu, że może wykonać daną akcję, nie nadaje samej aplikacji ani kontu usługi (Service Principal) uprawnień technicznych do jej wykonania.

Używanie narzędzi 3CX MCP

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

Modelowi AI udostępniane są wyłącznie narzędzia umieszczone na białej liście mcpTools w profilu agenta. Domyślny profil receptionist włącza przeszukiwanie książki telefonicznej:

mcpTools:

  - list_phonebook



Log startowy wyświetla narzędzia wykryte z serwera oraz informację o tym, czy każde z nich zostało włączone. Aby udostępnić inne autoryzowane narzędzie, dodaj jego dokładną nazwę do sekcji mcpTools i zrestartuj aplikację.

Ogranicz listę do najmniejszego zestawu narzędzi wymaganych przez dany proces. Narzędzie, które nie zostało 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 dać aplikacji głosowej dostęp do zatwierdzonych kalendarzy, systemów CRM lub narzędzi procesów biznesowych.

Przykłady obsługują dla wygody podczas testów typy uwierzytelniania auth.type: bearer lub none. Aby przeprowadzić szybki test bez uruchamiania własnego serwera MCP, użyj hostowanego agregatora MCP, takiego jak Smithery AI lub Zapier. Utwórz konto, wklej zdalny 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ć agentowi, do profilu agenta, używając jego dokładnej nazwy:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add



Narzędzia wykryte z zewnętrznych serwerów MCP są łączone z dostępnymi narzędziami 3CX MCP, ale biała lista profilu zachowuje pełną kontrolę nad tym, z których narzędzi model może korzystać.

Podczas dodawania zewnętrznych serwerów MCP:

• Używaj poświadczeń o minimalnych wymaganych uprawnieniach.
• Udostępniaj tylko niezbędne narzędzia.
• Weryfikuj parametry narzędzi po stronie serwera.
• Wymagaj zatwierdzenia dla wrażliwych lub nieodwracalnych operacji, gdzie jest to wskazane.
• Nie umieszczaj długoterminowych poświadczeń produkcyjnych bezpośrednio w systemie kontroli wersji.

Wyjście poza przykład recepcjonisty

Dołączona logika recepcjonisty demonstruje wyszukiwanie w książce telefonicznej, transfer połączeń, pocztę głosową oraz rozłączanie połączeń. Ta sama architektura może zostać rozbudowana o obsługę procesów takich jak:

• Planowanie i rezerwacja wizyt.
• Wyszukiwanie informacji o klientach lub kontach.
• Automatyczne ankiety i badania opinii.
• Wewnętrzny helpdesk IT lub HR.
• Tworzenie i aktualizacja zgłoszeń w systemach CRM.
• Usługi statusu zamówień lub informacji o dostawach.
• Interfejsy głosowe dla niestandardowych aplikacji biznesowych.

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

Lista kontrolna dla środowiska produkcyjnego

Przed wdrożeniem produkcyjnym niestandardowej aplikacji:

• Uruchom aplikację jako zarządzaną usługę z automatycznym restartem i monitorem stanu (health monitoring).
• Chroń poświadczenia API za pomocą menedżera sekretów i cyklicznie je zmieniaj.
• Ogranicz uprawnienia konta usługi (Service Principal) do wymaganych numerów wewnętrznych i funkcji.
• Przejrzyj zasady przetwarzania danych, przechowywania oraz dostępności regionalnej dostawcy AI.
• Informuj dzwoniących i uzyskaj odpowiednie zgody, jeśli wymagane jest nagrywanie, transkrypcja lub ujawnienie faktu rozmowy ze sztuczną inteligencją.
• Monitoruj zużycie API, limity zapytania (rate limits) oraz koszty u dostawcy.
• Dodaj obsługę limitów czasu (timeouts), ponawiania prób oraz zapasową trasę bez AI (non-AI fallback).
• Przetestuj scenariusze transferu, poczty głosowej, awarii i rozłączenia w realistycznych warunkach połączeniowych.
• Przejrzyj każde włączone narzędzie MCP i zabezpiecz wrażliwe akcje dodatkową walidacją lub zatwierdzeniem.

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 obsługę Corepack:

corepack enable



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

Uwierzytelnianie PBX zwraca błąd 401 lub 403

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

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

Upewnij się, że aplikacja nadal działa, zadzwoń na prawidłowy Client ID i zweryfikuj, czy numer DID został przypisany do konta usługi (Service Principal) podczas testowania połączeń zewnętrznych.

Narzędzie MCP jest wyświetlane jako 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ż, że konto usługi (Service Principal) posiada uprawnienia do używania tego narzędzia.

Transfery lub poczta głosowa nie działają

Sprawdź, czy punkt docelowy jest prawidłowy i dostępny dla konta usługi (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ą transferu.

Dostawca AI odrzuca połączenie

Sprawdź klucz API, stan rozliczeń konta, dostępność modelu, region, dostępne limity oraz łączność WebSocket. W przypadku Qwen upewnij się, ż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 i utratę pakietów między hostem aplikacji, systemem 3CX a dostawcą AI. Przejrzyj specyficzne dla dostawcy ustawienia detekcji aktywności głosowej (VAD) oraz dźwięku w pliku config.yaml.

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