Создайте голосовое ИИ-приложение на базе программируемых добавочных номеров 3CX

Подключите внешнее голосовое ИИ-приложение к 3CX с помощью Call Control API, Call Control SDK и поддерживаемого провайдера ИИ реального времени.

Введение

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

Примеры Agentic Call Control предоставляют рабочие приложения Node.js для:

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

В каждом примере используется одна двунаправленная аудиосессия в реальном времени. Распознавание речи, логика и генерация речи обрабатываются выбранным ИИ-провайдером. При этом 3CX продолжает обеспечивать телефонию, маршрутизацию вызовов, работу добавочных номеров, транки и DID-номера.

Примеры подключаются через опубликованные API 3CX и не требуют изменения исходного кода АТС. Они также подключаются к конечной точке 3CX MCP endpoint, поэтому голосовое приложение использует авторизованные инструменты АТС, такие как поиск по адресной книге. Более того, можно добавить дополнительные внешние серверы MCP для календарей, CRM и других бизнес-систем.

Какую опцию использовать? 

В данном руководстве рассматриваются программируемые добавочные номера (Programmable Extensions), где приложение работает вне 3CX на управляемой инфраструктуре. Для готового к настройке решения используйте встроенных ИИ агентов 3CX. С другой стороны, для пользовательских приложений, работающих непосредственно на сервере 3CX, используйте ИИ скрипты обработки вызовов.

Что будет создано

По завершении данного руководства будет создано внешнее голосовое ИИ-приложение, которое умеет:

  • Принимать внутренние вызовы через свой "Client ID" 3CX.
  • Принимать внешние вызовы через назначенный DID.
  • Поддерживать голосовой разговор в реальном времени с использованием выбранного ИИ-провайдера.
  • Искать в адресной книге 3CX через MCP.
  • Переводить вызов, отправлять его на голосовую почту или завершать через 3CX Call Control.
  • Подключаться к дополнительным серверам MCP и предоставлять модели доступ к выбранным инструментам.

Предоставленный профиль агента реализует базовый сценарий “секретаря” (рецепции). Он задуман как отправная точка и расширяется для записи на прием, предоставления информации клиентам, проведения опросов, работы внутренней службы поддержки и других рабочих процессов.

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

Потребуется:

  • АТС 3CX V20 Update 10 с доступом к Call Control API.
  • Доступ администратора для создания "API Service Principal".
  • Node.js 20 или новее на компьютере или сервере, где будет размещено приложение.
  • Версия Yarn, поставляемая с репозиторием.
  • API-ключ и доступная квота как минимум для одного поддерживаемого ИИ-провайдера.
  • Сетевой доступ от хоста приложения к HTTPS FQDN 3CX и WebSocket-эндпоинтам выбранного провайдера.

Шаг 1: Скачайте примеры

Клонируйте или скачайте репозиторий Agentic Call Control: Репозиторий Agentic Call Control

В терминале перейдите в корень репозитория и установите все зависимости рабочей области:

yarn install

Если команда yarn недоступна, сначала включите Corepack:

corepack enable

yarn install

Не запускайте yarn install отдельно в каждой директории провайдера. Репозиторий является рабочей областью Yarn. Следовательно, установка должна выполняться из его корня.

Шаг 2: Создайте "3CX Service Principal"

Создайте учетные данные, которые внешнее приложение будет использовать для аутентификации в АТС.

  • Войдите в Веб-клиент 3CX и откройте консоль администратора.
  • Перейдите в Integrations > API.
  • Нажмите Add, чтобы создать "Service Principal".
  • Введите "Client ID", например ai-receptionist. Это станет параметром appId приложения и внутренним номером, на который пользователи смогут звонить для вызова приложения.
  • Включите доступ к 3CX Call Control API для приложения.
  • Опционально назначьте DID, если требуется, чтобы внешние абоненты могли звонить на него напрямую.
  • Также есть возможность выбрать добавочные номера, которые приложению разрешено отслеживать или контролировать. Предоставляйте только тот доступ, который необходим для предполагаемого рабочего процесса.
  • Сохраните "Service Principal".
  • Немедленно скопируйте сгенерированный API-ключ или "Client Secret". Он используется в качестве appSecret и отображается только один раз.

Шаг 3: Выберите ИИ-провайдера

Используйте один из включенных примеров.

Провайдер

Директория  с примером

Учетные данные провайдера

Команда запуска

OpenAI Realtime

examples/openai-realtime

openaiApiKey

yarn start:openai

Google Gemini Live

examples/gemini-realtime

geminiApiKey

yarn start:gemini

xAI Grok Voice Agent

examples/xai-realtime

xaiApiKey

yarn start:xai

Alibaba Qwen Omni Realtime

examples/alibaba-qwen-realtime

dashscopeApiKey

yarn start:alibaba-qwen

Создайте API-ключ в консоли выбранного провайдера и надежно сохраните его:

Информацию о доступности моделей, голосах, регионах, ценообразовании и ограничениях скорости можно найти в документации выбранного провайдера, а также в файле README в соответствующей директории примера.

Примечание по регионам Qwen: Учетные данные и эндпоинты DashScope зависят от региона. Поэтому используйте эндпоинт, требуемый для региона и рабочей области, в которых был создан API-ключ.

Шаг 4: Создайте конфигурацию провайдера

Скопируйте файл config.yaml.example to config.yaml в выбранной директории примера.

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

В Windows PowerShell используйте Copy-Item вместо cp.

Откройте новый файл config.yaml и введите следующие параметры 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?

Оставьте значение agentProfile предоставленное выбранным примером. OpenAI, Gemini и xAI используют receptionist; Qwen включает отдельные английские и китайские профили.

Далее установите учетные данные для выбранного провайдера. Например, конфигурация OpenAI содержит:

openaiApiKey: sk-your-openai-api-key

Используйте предоставленный провайдером файл config.yaml.example в качестве эталона для модели, голоса, обнаружения голосовой активности и специфичных для провайдера настроек. Для Qwen сохраните конфигурацию базового URL, привязанную к региону провайдера.

Безопасность: файл config.yaml содержит секретные данные. Он исключён из репозитория с помощью .gitignore. Однако его всё равно нельзя распространять, коммитить или включать в логи поддержки.  Для рабочей системы используйте менеджер секретов или метод развертывания на основе переменных окружения.

Шаг 5: Запустите приложение

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

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen

Точный вывод при запуске зависит от провайдера. Успешный запуск подтверждает, что:

  • Приложение прошло аутентификацию в 3CX.
  • Call Control SDK и WebSocket-соединение активны.
  • Приложение подключилось к эндпоинту 3CX MCP.
  • Включенные инструменты MCP загружены.
  • Обработчик вызовов инициализирован, следовательно, приложение готово принимать вызовы.

Шаг 6: Позвоните и протестируйте приложение

Сделайте внутренний вызов

С зарегистрированного добавочного номера 3CX наберите "Client ID" из "Service Principal", настроенный как appId.

Например, если "Client ID" — ai-receptionist, позвоните на номер ai-receptionist из Веб-клиента 3CX, десктопного приложения, мобильного приложения или настроенного телефона.

Сделайте внешний вызов

Если "Service Principal" назначен DID, позвоните на этот номер с внешнего телефона.

Рекомендуемые тесты

Проверьте весь сценарий перед тем, как настраивать его под свои задачи:

  • Убедитесь, что ИИ агент отвечает настроенным приветствием.
  • Попросите соединить с известным контактом из адресной книги.
  • Убедитесь, что ИИ агент ищет в адресной книге через MCP.
  • Протестируйте успешный перевод вызова.
  • Протестируйте маршрут при недоступности пользователя и голосовую почту.
  • Перебейте ИИ агента во время речи, чтобы проверить поведение функции вмешательства (barge-in).
  • Завершите вызов и убедитесь, что приложение корректно освобождает линию.

Остановите приложение с помощью Ctrl+C.

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

Базовые настройки, такие как название компании и имя ИИ агента, хранятся в файле  config.yaml.

Более детальное поведение определяется профилем YAML в директории agents выбранного примера. В зависимости от примера провайдера профиль по умолчанию называется receptionist.yaml, receptionist_en.yaml или receptionist_cn.yaml.

Профиль управляет такими параметрами, как:

  • Роль и системный промпт.
  • Приветствия и языковое поведение.
  • Требования к фильтрации вызовов.
  • Проверка доступности перед переводом вызова.
  • Разрешенные действия с вызовами.
  • Заблокированные добавочные номера.
  • Политики в отношении спама, агрессии и нежелающих сотрудничать абонентов.
  • Инструменты MCP, доступные модели.

Перезапустите приложение после изменения файла config.yaml или выбранного профиля агента.

Синхронизируйте промпты и разрешения инструментов. Указание модели на возможность выполнения действия не дает базовому приложению или "Service Principal" прав на его выполнение.

Использование инструментов 3CX MCP

При запуске примеры подключаются к эндпоинту 3CX MCP и обнаруживают инструменты, доступные аутентифицированному "Service Principal".

Только инструменты, перечисленные в списке разрешений mcpTools профиля ИИ агента, доступны модели ИИ. Кроме того, профиль ИИ секретаря по умолчанию включает поиск по адресной книге:

mcpTools:

  - list_phonebook

Лог запуска показывает инструменты, обнаруженные на сервере, и статус включения каждого из них. Чтобы предоставить доступ к другому авторизованному инструменту, добавьте его точное имя в mcpTools и перезапустите приложение.

Ограничьте список минимальным набором инструментов, необходимым для рабочего процесса. Соответственно, инструмент, не предоставленный модели, не может быть ею вызван.

Подключение дополнительных серверов MCP

Дополнительные серверы MCP настраиваются в разделе customMcpServers в файле config.yaml. Это предоставляет голосовому приложению доступ к разрешенным инструментам календаря, CRM или бизнес-процессов.

В примерах используется auth.type: bearer или auth.type: none для удобства при тестировании. Для быстрого тестирования без запуска собственного сервера MCP используйте облачный коннектор, например Smithery: вставьте удаленный URL и токен bearer в customMcpServers, а затем включите обнаруженные имена инструментов в mcpTools.

customMcpServers:

  - name: GoogleCalendar

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

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true

Добавьте каждый инструмент, который требуется предоставить профилю агента, используя его точное имя:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add

Инструменты, обнаруженные на пользовательских серверах MCP, объединяются с доступными инструментам 3CX MCP. Однако список разрешений профиля по-прежнему контролирует, какие инструменты разрешено использовать модели..

При добавлении внешних серверов MCP:

  • Do not place long-lived production secrets directly in source control.
  • Используйте учетные данные с минимальными привилегиями.
  • Предоставляйте доступ только к необходимым инструментам.
  • Проверяйте параметры инструментов на стороне сервера.
  • Запрашивайте подтверждение для конфиденциальных или необратимых операций там, где это применимо.
  • Не помещайте долгоживущие секреты рабочей среды непосредственно в систему контроля версий.

Расширение возможностей примера с секретарем

Включенная логика секретаря демонстрирует поиск по адресной книге, перевод вызова, голосовую почту и завершение вызова. Эту же архитектуру можно расширить для поддержки таких рабочих процессов, как:

  • Планирование встреч.
  • Поиск информации о клиенте или учетной записи.
  • Автоматизированные опросы.
  • Служба поддержки внутренних IT или HR отделов.
  • Создание и обновление тикетов в CRM.
  • Информационные сервисы по статусу заказов и доставке.
  • Голосовые интерфейсы для пользовательских бизнес-приложений.

Приложение по-прежнему отвечает за бизнес-логику, валидацию, обработку ошибок и безопасность инструментов. В то же время, 3CX обеспечивает соединение вызова, потоковую передачу звука и функции управления вызовами, а выбранный ИИ-провайдер обрабатывает разговор в реальном времени.

Контрольный список для рабочей среды

Перед переносом пользовательского приложения из тестовой среды в рабочую:

  • Запускайте его как управляемую службу с автоматическим перезапуском и мониторингом состояния.
  • Защитите учетные данные API с помощью менеджера секретов и периодически меняйте их.
  • Ограничьте "Service Principal" необходимыми добавочными номерами и функциями.
  • Изучите политики ИИ-провайдера по обработке данных, их хранению и региональной доступности.
  • Информируйте абонентов и получайте согласие там, где требуется запись, транскрипция или уведомление об использовании ИИ.
  • Отслеживайте использование провайдера, ограничения скорости и затраты.
  • Добавьте тайм-ауты, обработку повторных попыток и резервный маршрут без ИИ.
  • Протестируйте маршруты перевода, голосовой почты, сбоя и отключения в реалистичных условиях вызова.
  • Проверьте каждый включенный инструмент MCP и защитите конфиденциальные действия дополнительной валидацией или утверждением.

Устранение неполадок

Команда yarn не распознана

Убедитесь, что установлен Node.js 20 или новее, а затем включите Corepack::

corepack enable

Снова запустите yarn install из корня репозитория.

Аутентификация в АТС возвращает ошибку 401 или 403

Убедитесь, что  appId, appSecret и pbxBase соответствуют "Service Principal". Подтвердите, что доступ к Call Control API включен, и лицензия и права 3CX разрешают запрашиваемую операцию.

Приложение запускается, но не принимает вызовы

Убедитесь, что приложение все еще работает, наберите правильный "Client ID" и проверьте, что DID назначен "Service Principal" при тестировании внешних вызовов.

Инструмент MCP отображается как отключенный

Скопируйте точное имя инструмента, показанное в журнале запуска, в список mcpTools профиля, а затем перезапустите приложение. Кроме того, убедитесь, что "Service Principal" авторизован для использования этого инструмента.

Сбой перевода вызова или голосовой почты

Убедитесь, что пункт назначения действителен и доступен для "Service Principal". Если в профиле включена фильтрация вызовов, подтвердите, что необходимые поля фильтрации были собраны до попытки перевода вызова.

ИИ-провайдер отклоняет соединение

Проверьте API-ключ, биллинг аккаунта, доступ к модели, регион, квоту и подключение WebSocket. Для Qwen убедитесь, что API-ключ и эндпоинт принадлежат одному региону и рабочей области.

Задержка звука или частые прерывания речи агента

Проверьте сетевую задержку и потерю пакетов между хостом приложения, 3CX и ИИ-провайдером. Ознакомьтесь с настройками обнаружения голосовой активности и звука для конкретного провайдера в файле config.yaml.

Версия документа

Последнее обновление документа 30 июля 2026

https://www.3cx.ru/docs/programmable-extensions/