Создание голосового агента OpenAI Realtime

Введение

Пример скрипта openaivoiceagent.cs подключает входящий вызов 3CX к голосовой сессии OpenAI Realtime. Он может приветствовать звонящих, отвечать на общие вопросы, искать разрешенные записи в телефонной книге 3CX, соединять абонентов, предлагать голосовую почту или чат, а также сохранять полезный контекст вызова, если эта функция включена.

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

Для этого скрипта требуется лицензия 3CX AI, сборка АТС Update 10 и учетная запись OpenAI API.

Создание скрипта обработки вызова в 3CX

• Войдите в консоль администратора 3CX.
• Перейдите в Integrations > Call Scripts.
• Нажмите +Add from Store.

• Выберите openaivoiceagent.cs.

• Введите имя скрипта строчными буквами без пробелов, например openaireception.
• Выберите, как будет запускаться скрипт; для профиля секретаря назначьте выделенный DID или направьте на скрипт соответствующие входящие вызовы с транка.
• Выберите отдел (Department), которому принадлежит скрипт.
• Подтвердите выбор, чтобы открыть редактор кода.

Настройка OpenAI и скрипта

Добавьте следующие параметры в АТС:

• OPENAI_API_KEY - API-ключ для вашего проекта OpenAI.
• OPENAI_REALTIME_MODEL - модель OpenAI Realtime.

Оставьте ApiKeyOverride и ModelOverride в скрипте пустыми. Если эти значения не заполнены, скрипт автоматически считывает API-ключ и модель из параметров АТС.

Не вводите API-ключ OpenAI непосредственно в скрипт, особенно если он будет передаваться, экспортироваться или публиковаться. Значение, настроенное в ApiKeyOverride или ModelOverride, имеет приоритет над соответствующим параметром АТС.

Затем просмотрите следующие пользовательские настройки в верхней части файла openaivoiceagent.cs:

Использование AddAll() удобно для начального тестирования, но перед развертыванием в рабочей среде эту функцию следует отключить. Установите для параметра AllowAllVisibilityForTesting значение false, затем настройте только те номера, отделы и роли, которые требуются агенту.

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

RegisterExampleCustomTool();



Перед использованием инструмента для получения реальной информации о клиентах замените пример на надежный источник данных.

Нажмите Save для компиляции. Убедитесь, что в выводе скрипта сообщается об успешной компиляции, прежде чем направлять на него рабочий трафик.

Как это работает

• Входящий вызов поступает на точку маршрутизации скрипта.
• Скрипт очищает и перестраивает список видимости телефонной книги для ИИ.
• 3CX подготавливает медиаканал.
• Скрипт запускает голосовую сессию OpenAI Realtime.
• Агент использует только встроенные функции 3CX и любые явно зарегистрированные пользовательские инструменты.
• При успешном переводе вызывающий абонент перенаправляется на выбранное место назначения 3CX.
• Если настройка медиа или сессия провайдера завершается ошибкой, скрипт пытается использовать настроенный резервный маршрут (fallback), а затем воспроизводит голосовое сообщение ERROR, если маршрутизация также не удалась.

Тестирование скрипта

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

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

• Сбой сессии провайдера: Проверьте OPENAI_API_KEY, поддерживаемую модель реального времени, доступ к сети, наличие лицензии и сборку АТС.
• Агент не может найти пользователя: Проверьте параметры AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments и VisibleRoles.
• Видимы неправильные объекты: Вызовите Clear() перед добавлением списка видимости для рабочей среды и избегайте использования AddAll().
• Резервный маршрут не работает: Убедитесь, что место назначения существует и доступно из назначенного отдела.
• Не воспроизводится сообщение об ошибке: Убедитесь, что файл ERROR существует в активном наборе системных голосовых сообщений.

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

• Создание скрипта обработки вызовов
• Пример: Call Processing Script for PIN
• Руководство администратора V20

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

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

https://www.3cx.ru/docs/open-ai-voice-agent/