Programowalne numery wewnętrzne 3CX - Dostawcy AI
Wprowadzenie
Programowalne numery wewnętrzne 3CX (Programmable Extensions) pozwalają programistom tworzyć agentów AI, którzy obsługują połączenia na żywo przez system telefoniczny 3CX.
„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 pokaże Ci, jak wybrać dostawcę, skonfigurować wybrany przykład przy użyciu danych uwierzytelniających 3CX i dostawcy, uruchomić go i wykonać połączenie testowe.
Zanim zaczniesz
Pobierz i rozpakuj kod źródłowy „3CX Agentic Call Control”. Wszystkie cztery przykłady znajdują się w tym samym pakiecie.
Wybierz OpenAI, xAI, Google Gemini lub Alibaba Cloud Qwen, a następnie użyj folderu przykładu i wartości konfiguracyjnych dla tego dostawcy.
- Administrator 3CX z dostępem do „Admin” > „Integrations” > „API”, który może utworzyć „Service Principal”.
- Zainstalowane środowisko Node.js 20+. Menedżer Yarn 4 jest dołączony do repozytorium.
- Klucz API z dostępem do usługi w czasie rzeczywistym (realtime) dla wybranego dostawcy AI.
- Działający numer wewnętrzny 3CX, taki jak Web Client, aplikacja mobilna lub telefon biurkowy, aby wykonać połączenie testowe do agenta AI.
Pobierz przykłady
Po pobraniu kodu źródłowego „3CX Agentic Call Control” przejdź do głównego folderu; zawiera on plik package.json, foldery examples oraz packages.
W folderze examples znajdziesz kod kontroli połączeń specyficzny dla danego dostawcy:
- examples/openai-realtime
- examples/xai-realtime
- examples/gemini-realtime
- examples/alibaba-qwen-realtime
Wewnątrz każdego z folderów przykładów znajdziesz plik config.yaml.example, który należy skopiować i zmienić nazwę kopii na config.yaml. Pozostaw plik config.yaml.example bez zmian, aby w razie potrzeby móc wrócić do oryginalnych ustawień przykładu.
Plik config.yaml zawiera ustawienia połączenia z centralą PBX oraz parametry dostawcy, które umożliwiają działanie kodu programowalnego numeru wewnętrznego.
Utwórz 3CX Service Principal
W centrali PBX otwórz „Admin” > „Integrations” > „API” i wybierz „Add a Service Principal” (Dodaj Service Principal).
- Wprowadź „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ł funkcje wyszukiwania kontaktów w całym systemie i sprawdzania statusów, musisz również włączyć: „Enable access to the 3CX Configuration API (XAPI) for this application” (Włącz dostęp do 3CX Configuration API (XAPI) dla tej aplikacji). Ustaw dział („department”) i rolę („role”) zgodnie z możliwościami, jakie chcesz nadać agentowi.
- Zapisz klucz API 3CX w bezpiecznym miejscu.
Wybierz dostawcę i skonfiguruj config.yaml
OpenAI
- W pliku config.yaml wprowadź:
- appId: Client ID z sekcji Integracje > API > Client ID.
- appSecret: Klucz API Service Principal z sekcji Integracje > API > Generate API Key.
- pbxBase: Adres Twojej 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 sekcji Integracje > API > Client ID.
- appSecret: Klucz API Service Principal z sekcji Integracje > API > Generate API Key.
- pbxBase: Adres Twojej 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 sekcji Integracje > API > Client ID.
- appSecret: Klucz API Service Principal z sekcji Integracje > API > Generate API Key.
- pbxBase: Adres Twojej 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 sekcji Integracje > API > Client ID.
- appSecret: Klucz API Service Principal z sekcji Integracje > API > Generate API Key.
- pbxBase: Adres Twojej 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)
Przetestuj 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.
Dostosuj 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 28 sierpnia 2026 r.
https://www.3cx.pl/docs/agentic-call-control-ai-providers/
Copyright © 2025