Programowalne numery wewnętrzne 3CX - Dostawcy AI
Wprowadzenie
Programowalne numery wewnętrzne 3CX (3CX Programmable Extensions) umożliwiają deweloperom tworzenie agentów AI przeznaczonych do obsługi połączeń na żywo w systemie 3CX Phone System.
„3CX Agentic Call Control” to zestaw gotowych przykładów kodu do budowania takich agentów. Każdy przykład łączy programowalny numer wewnętrzny z dostawcą AI działającym w czasie rzeczywistym (takim jak OpenAI, xAI, Gemini lub Qwen) i udostępnia agentowi odpowiednie funkcje kontroli połączeń 3CX.
Ten przewodnik pokazuje, jak wybrać dostawcę (OpenAI, xAI, Gemini lub Qwen), skonfigurować odpowiedni przykład przy użyciu poświadczeń systemu 3CX i dostawcy AI, uruchomić go oraz wykonać połączenie testowe.
Zanim zaczniesz
Pobierz i rozpakuj kod źródłowy 3CX Agentic Call Control. Wszystkie cztery przykłady są zawarte w tym samym pakiecie.
Wybierz OpenAI, xAI, Google Gemini lub Alibaba Cloud Qwen, a następnie użyj odpowiedniego folderu z przykładem i wartości konfiguracyjnych dla danego dostawcy.
- Administrator 3CX z dostępem do sekcji „Admin” > „Integrations” (Integracje) > „API”, który może utworzyć konto usługi (Service Principal).
- Zainstalowany Node.js w wersji 20 lub nowszej. Menedżer Yarn 4 jest dołączony do repozytorium.
- Klucz API z dostępem do usługi w czasie rzeczywistym dla wybranego dostawcy AI.
- Działający numer wewnętrzny 3CX (np. klient webowy, aplikacja mobilna lub telefon biurkowy), aby wykonać połączenie testowe do agenta AI.
Pobranie przykładów
Po pobraniu kodu źródłowego 3CX Agentic Call Control przejdź do folderu głównego; zawiera on plik package.json oraz foldery examples i packages.
W folderze examples znajdziesz kod Agentic Call Control dedykowany dla poszczególnych dostawców:
- examples/openai-realtime
- examples/xai-realtime
- examples/gemini-realtime
- examples/alibaba-qwen-realtime
Wewnątrz każdego z folderów z przykładami należy skopiować plik config.yaml.example i zmienić nazwę kopii na config.yaml. Zachowaj oryginalny plik config.yaml.example w stanie niezmienionym, aby w razie potrzeby móc powrócić do pierwotnych ustawień.
Plik config.yaml zawiera ustawienia połączenia z centralą PBX oraz ustawienia dostawcy, które umożliwiają działanie kodu programowalnego numeru wewnętrznego.
Tworzenie konta usługi 3CX (Service Principal)
W centrali PBX przejdź do: „Admin” > „Integrations” (Integracje) > „API” i wybierz „Add a Service Principal” (Dodaj konto usługi).
- Wprowadź identyfikator klienta (Client ID), np. assistant.
- Włącz opcję „Enable access to the 3CX Call Control API for this application” (Włącz dostęp do 3CX Call Control API dla tej aplikacji).
- Jeśli chcesz, aby agent posiadał uprawnienia do ogólnosystemowego wyszukiwania kontaktów i sprawdzania statusów obecności, musisz również włączyć opcję „Enable access to the 3CX Configuration API (XAPI) for this application” (Włącz dostęp do 3CX Configuration API dla tej aplikacji). Ustaw dział (Department) i rolę (Role) zgodnie z zakresem uprawnień, jakie ma posiadać agent.
- Zapisz wygenerowany klucz 3CX API w bezpiecznym miejscu.
Wybór dostawcy i konfiguracja pliku config.yaml
OpenAI
- W pliku config.yaml wprowadź:
- appId: Client ID z konsoli 3CX („Admin” > „Integrations” > „API” > „Client ID”)
- appSecret: Klucz API konta usługi („Admin” > „Integrations” > „API” > „Generate API Key”)
- pbxBase: Adres centrali PBX
- openaiApiKey: Klucz API OpenAI z sekcji OpenAI API Keys.
Zainstaluj zależności i uruchom przykład OpenAI:
yarn install
yarn start:openai
Poprawny log uruchomienia OpenAI zawiera:
openai-realtime starting
3CX PBX: https://your-pbx.3cx.eu:5001
OpenAI model: <configured model>
OpenAI voice: <configured voice>
Agent profile: receptionist (role: receptionist)
SDK connected (auth + WebSocket + state)
[MCP] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
[CallStore] initialized (OpenAI Realtime mode)
All systems ready (OpenAI Realtime mode)
xAI
- W pliku config.yaml wprowadź:
- appId: Client ID z konsoli 3CX („Admin” > „Integrations” > „API” > „Client ID”)
- appSecret: Klucz API konta usługi („Admin” > „Integrations” > „API” > „Generate API Key”)
- pbxBase: Adres centrali PBX
- xaiApiKey: Klucz API xAI z console.x.ai.
Zainstaluj zależności i uruchom przykład xAI:
yarn install
yarn start:xai
Poprawny log uruchomienia xAI zawiera:
xai-realtime starting
3CX PBX: https://your-pbx.3cx.eu:5001
Agent profile: receptionist (role: receptionist)
xAI Voice: tara
SDK connected (auth + WebSocket + state)
[MCP] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
[CallStore] initialized (xAI realtime mode)
All systems ready (xAI realtime mode)
Gemini
- W pliku config.yaml wprowadź:
- appId: Client ID z konsoli 3CX („Admin” > „Integrations” > „API” > „Client ID”)
- appSecret: Klucz API konta usługi („Admin” > „Integrations” > „API” > „Generate API Key”)
- pbxBase: Adres centrali PBX
- geminiApiKey: Klucz API Google AI Studio z Google AI Studio
Zainstaluj zależności i uruchom przykład Gemini:
yarn install
yarn start:gemini
Poprawny log uruchomienia Gemini zawiera:
agentic-call-control starting
3CX PBX: https://your-pbx.3cx.eu:5001
Gemini Voice: Kore
Agent profile: receptionist (role: receptionist)
SDK connected (auth + WebSocket + state)
[MCP] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
[CallStore] initialized (Gemini Live mode)
All systems ready (Gemini Live mode)
Qwen
- W pliku config.yaml wprowadź:
- appId: Client ID z konsoli 3CX („Admin” > „Integrations” > „API” > „Client ID”)
- appSecret: Klucz API konta usługi („Admin” > „Integrations” > „API” > „Generate API Key”)
- pbxBase: Adres centrali PBX
- dashscopeApiKey: Klucz API Alibaba Cloud DashScope z Alibaba Cloud DashScope API key.
- dashscopeBaseUrl: Użyj https://dashscope-intl.aliyuncs.com dla klucza międzynarodowego (Singapur) lub https://dashscope.aliyuncs.com dla klucza z Chin kontynentalnych.
Zainstaluj zależności i uruchom przykład Qwen:
yarn install
yarn start:alibaba-qwen
Poprawny log uruchomienia Qwen zawiera:
alibaba-qwen-realtime starting
3CX PBX: https://your-pbx.3cx.eu:5001
DashScope: https://dashscope-intl.aliyuncs.com
Model: qwen3.5-omni-plus-realtime
Voice: Tina
Agent profile: receptionist_en (role: receptionist)
SDK connected (auth + WebSocket + state)
[McpManager] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
[CallStore] initialized (Qwen Omni realtime)
All systems ready (Qwen realtime mode)
Testowanie agenta
Użyj testowego numeru wewnętrznego. Do testów przełączania połączeń użyj drugiego, wewnętrznego numeru wewnętrznego. W głównym folderze „3CX Agentic Call Control” uruchom polecenie dla skonfigurowanego dostawcy:
- OpenAI: yarn start:openai
- xAI: yarn start:xai
- Gemini: yarn start:gemini
- Qwen: yarn start:alibaba-qwen
Poczekaj, aż terminal wyświetli połączenie z PBX i stan gotowości.
- Wykręć „Client ID” (appId) swojego Service Principal z testowego numeru wewnętrznego. Na przykład wybierz dosłownie nazwę „assistant”, aby połączyć się z agentem.
- Potwierdź, że agent odbiera, odtwarza powitanie i odpowiada Ci.
- Przetestuj wyszukiwanie numeru wewnętrznego lub poproś agenta o rozłączenie połączenia za Ciebie.
- Sprawdź dane wyjściowe w terminalu pod kątem ewentualnych błędów.
Dostosowywanie agenta
Użyj pliku config.yaml, aby zmienić powitanie i ustawienia specyficzne dla dostawcy. Aby zmienić domyślne zachowanie, edytuj plik agents/receptionist.yaml lub dodaj inny profil w folderze agents/. Jeśli dodasz niestandardowe serwery MCP (customMcpServers), wymień dokładne nazwy narzędzi w sekcji mcpTools w tym profilu agenta. Zrestartuj agenta po każdej zmianie konfiguracji i wykonaj ponowne połączenie testowe.
Zobacz również
- 3CX Agentic Call Control
- 3CX Call Control API
- API Konfiguracji 3CX
- Specyfikacja punktów końcowych Call Control API
Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 9 września 2026 r.
https://www.3cx.pl/docs/agentic-call-control-ai-providers/
Copyright © 2025