Провайдеры ИИ для 3CX Programmable Extensions

Введение

Программно-управляемые добавочные номера 3CX (3CX Programmable Extensions) позволяют разработчикам создавать ИИ-агентов, которые обрабатывают звонки в режиме реального времени через АТС 3CX.

3CX Agentic Call Control - это набор готовых примеров кода для создания таких ИИ-агентов. Каждый пример подключает программно-управляемый добавочный номер к провайдеру ИИ реального времени, такому как OpenAI, xAI, Gemini или Qwen, и предоставляет агенту доступ к соответствующим функциям управления вызовами 3CX.

В данном руководстве показано, как выбрать OpenAI, xAI, Gemini или Qwen, настроить соответствующий пример с использованием учетных данных 3CX и провайдера, запустить его и совершить тестовый вызов.

Перед началом работы

Загрузите и распакуйте исходный код 3CX Agentic Call Control. Все четыре примера включены в один архив.

Выберите OpenAI, xAI, Google Gemini или Alibaba Cloud Qwen, после чего используйте папку с примером и значения конфигурации для соответствующего провайдера.

  • Доступ администратора 3CX в раздел Admin > Integrations > API для создания субъекта-службы (Service Principal).
  • Установленный Node.js 20+. Yarn 4 поставляется вместе с репозиторием.
  • Ключ API с доступом к сервису реального времени выбранного провайдера ИИ.
  • Работающий добавочный номер 3CX (например, веб-клиент, мобильное приложение или настольный телефон) для совершения тестового вызова ИИ-агенту.

Получение примеров

После загрузки исходного кода 3CX Agentic Call Control перейдите в основную папку; она содержит package.json, examples and packages.

В папке examples вы найдете код агентского управления вызовами для конкретного провайдера:

  • examples/openai-realtime
  • examples/xai-realtime
  • examples/gemini-realtime
  • examples/alibaba-qwen-realtime

Внутри каждой папки с примером необходимо скопировать файл config.yaml.exampleи переименовать копию в config.yaml. Оставьте файл config.yaml.example без изменений, чтобы при необходимости можно было вернуться к исходным настройкам примера.

Файл config.yaml содержит настройки подключения к АТС и провайдеру, необходимые для работы кода программно-управляемого добавочного номера.

Создание 3CX Service Principal

В АТС перейдите в Admin > Integrations > API и выберите Add a Service Principal.

  1. Введите Client ID, например, “assistant”.

Create a 3CX Service Principal

  1. Включите опцию "Enable access to the 3CX Call Control API for this application".
  2. Если вы хотите, чтобы агент имел возможность поиска контактов по всей системе и проверки статуса присутствия, вам также необходимо включить: "Enable access to the 3CX Configuration API (XAPI) for this application". Установите отдел (department) и роль (role) в зависимости от того, какие возможности вы хотите предоставить агенту.

Add API Key

  1. Сохраните ключ API 3CX в безопасном месте.

Выбор провайдера и настройка config.yaml

OpenAI

  • В файле config.yaml укажите:
  • appId:Client ID из раздела АТС Integrations > API > Client ID
  • appSecret: Ключ API Service Principal PBX из раздела Integrations > API > Generate API Key
  • pbxBase: Адрес АТС
  • openaiApiKey: Ключ API OpenAI из раздела OpenAI API Keys

OpenAI Configuration Example

Установите зависимости и запустите пример OpenAI:

yarn install

yarn start:openai

При успешном запуске OpenAI в журнале появится примерно следующее:

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

  • В файле config.yaml укажите:
  • appId: Client ID из раздела АТС Integrations > API > Client ID
  • appSecret: Ключ API Service Principal PBX из раздела Integrations > API > Generate API Key
  • pbxBase: Адрес АТС
  • xaiApiKey: Ключ API xAI из console.x.ai

xAI Configuration Example

Установите зависимости и запустите пример xAI:

yarn install

yarn start:xai

При успешном запуске xAI в журнале появится примерно следующее:

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

  • В файле config.yaml укажите:
  • appId: Client ID из раздела АТС Integrations > API > Client ID
  • appSecret: Ключ API Service Principal PBX из раздела Integrations > API > Generate API Key
  • pbxBase: Адрес АТС
  • geminiApiKey: Ключ API Google AI Studio из Google AI Studio

Gemini Configuration Example

Установите зависимости и запустите пример Gemini:

yarn install

yarn start:gemini

При успешном запуске Gemini в журнале появится примерно следующее:

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

  • In config.yaml, enter:
  • appId: Client ID из раздела АТС Integrations > API > Client ID
  • appSecret: Ключ API Service Principal PBX из раздела Integrations > API > Generate API Key
  • pbxBase: Адрес АТС
  • dashscopeApiKey: Ключ API Alibaba Cloud DashScope из Alibaba Cloud DashScope API key
  • dashscopeBaseUrl: Используйте https://dashscope-intl.aliyuncs.com для международного ключа/ключа для Сингапура, или https://dashscope.aliyuncs.com для ключа материкового Китая.

Qwen Configuration Example

Установите зависимости и запустите пример Qwen:

yarn install

yarn start:alibaba-qwen

При успешном запуске Qwen в журнале появится примерно следующее:

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)

Тестирование агента

Используйте тестовый добавочный номер. Для тестирования перевода вызова используйте второй внутренний тестовый добавочный номер. Из главной папки 3CX Agentic Call Control выполните команду для настроенного провайдера:

  • OpenAI: yarn start:openai
  • xAI: yarn start:xai
  • Gemini: yarn start:gemini
  • Qwen: yarn start:alibaba-qwen

Дождитесь, пока в терминале не появится сообщение о подключении к АТС и состоянии готовности.

  1. Позвоните на Service Principal Client ID (appId) с тестового добавочного номера. Например, наберите буквенный Client ID "assistant" для подключения к агенту.
  2. Убедитесь, что агент отвечает, воспроизводит приветствие и реагирует на ваши запросы.
  3. Протестируйте поиск добавочного номера или попросите агента завершить вызов.
  4. Проверьте вывод терминала на наличие ошибок.

Настройка агента

Используйте файл config.yaml для изменения приветствия и настроек, специфичных для провайдера. Чтобы изменить поведение по умолчанию, отредактируйте файл agents/receptionist.yaml или добавьте другой профиль в папку agents/. Если вы добавляете customMcpServers, перечислите точные имена инструментов в разделе mcpTools в соответствующем профиле агента. Перезапускайте агента после каждого изменения конфигурации и совершайте повторный тестовый вызов.

Дополнительная информация

Версия документа
Последнее обновление документа 28 августа 2026
https://www.3cx.ru/docs/agentic-call-control-ai-providers/