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

Введение

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

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

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

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

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

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

• Введите имя скрипта строчными буквами без пробелов, например geminireception.
• Выберите, как будет запускаться скрипт, и назначьте необходимый DID, маршрут транка или внутреннее направление.
• Выберите отдел, которому принадлежит скрипт.
• Перейдите к редактору кода.

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

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

• GEMINI_API_KEY - API-ключ для вашего проекта Google AI.
• GEMINI_REALTIME_MODEL - модель Gemini Realtime.

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

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

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

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

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

RegisterExampleCustomTool();



Нажмите Save и убедитесь в успешной компиляции.

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

1. Входящий вызов поступает на точку маршрутизации скрипта.
2. Скрипт очищает и перестраивает список видимости телефонной книги для Gemini.
3. 3CX подготавливает медиаканал.
4. Скрипт запускает голосовую сессию Gemini Live с заданными инструкциями, голосом, именем агента, API‑ключом и моделью.
5. Разрешенные инструменты выполняют действия, связанные с телефонной книгой, переводом вызовов, голосовой почтой, чатом и контекстом.
6. В случае сбоя вызовы направляются на настроенный резервный маршрут, а если маршрутизация недоступна — используется сообщение ERROR.

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

• Проверьте выбранный голос Gemini и поведение системы в зависимости от языка звонящего.
• Выполните поиск разрешенных объектов телефонной книги.
• Убедитесь, что скрытые направления недоступны для выбора.
• Протестируйте подтверждение перевода вызова, голосовую почту и чат.
• Протестируйте естественное прощание.
• Смоделируйте сбой провайдера и проверьте маршрутизацию на резервное направление (fallback).

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

• Сбой сессии Gemini: проверьте API-ключ Gemini, поддерживаемую live-модель, лицензию, версию сборки АТС 3CX и исходящее подключение.
• Голос отклонен: используйте голос, поддерживаемый настроенной моделью Gemini.
• Отсутствуют результаты поиска по телефонной книге: проверьте настройки видимости номера, отдела и роли.
• Открыт доступ к слишком большому количеству объектов: отключите AddAll().
• Сбой резервного маршрута или промпта: проверьте направление и голосовое сообщение (промпт) ERROR.

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

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

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

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

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