呼叫流程脚本：创建 Gemini 实时语音坐席

介绍

geminivoiceagent.cs示例将 3CX 入站呼叫连接到 Google Gemini Live。该坐席可以问候呼叫者、使用允许的目录对象、路由呼叫、提供语音信箱或聊天，并在配置后保存有用的呼叫者上下文。

该脚本包含一个已禁用的 get_department_hours 自定义工具，用于演示如何注册一个安全的 AI 可调用函数。

此脚本需要3CX AI 版许可证、PBX 版本 Update 10 以及 Gemini API 账户。

在 3CX 中创建呼叫脚本

  • 登录 3CX 管理控制台。
  • 前往集成>呼叫脚本。
  • 选择 +从商店添加。

  • 选择 geminivoiceagent.cs。

  • 请输入不带空格的小写名称，例如geminireception。
  • 选择脚本的运行方式，并分配所需的 DID、中继路由或内部目标。
  • 选择所属部门。
  • 继续打开代码编辑器。

配置 Gemini 和脚本

将以下受保护参数添加到 PBX：

  • GEMINI_API_KEY- 您的 Google AI 项目的 API 密钥。
  • GEMINI_REALTIME_MODEL- Gemini Realtime 模型。

在脚本中保留 ApiKeyOverride 和 ModelOverride 为空。当这些值为空时，脚本会自动从 PBX 参数读取 API 密钥和模型。

请勿直接在脚本中输入 Gemini API 密钥，尤其当脚本会被共享、导出或发布时。在 ApiKeyOverride 或 ModelOverride 中配置的值将优先于对应的 PBX 参数。

接下来，请查看脚本顶部附近的这些客户设置：

设置

用途

示例值

FallbackDestination

媒体或提供商失败后使用的路由

102

VoiceName

Gemini Live 语音

Capella 

AgentName

坐席会话名称

Capella 

AllowAllVisibilityForTesting

初始测试时广泛的目录访问权限

true

VisibleNumbers

AI 可以使用的明确目标

100，102

VisibleDepartments

允许的部门

Sales, Support

VisibleRoles

可选允许的角色

空

AgentInstructions

组织行为和路由规则 

Example Company

在生产环境中，请将 AllowAllVisibilityForTesting 设为 false，并配置最小可行的可见性列表。

要启用可选功能示例，请检查其数据并取消注释：

RegisterExampleCustomTool();

选择 '保存'并验证编译是否成功。

工作原理

  1. 入站呼叫到达脚本路由点。
  2. 脚本清除并重建 Gemini 允许的 3CX 目录可见性。
  3. 3CX 准备媒体通道。
  4. 脚本使用配置的指令、语音、坐席名称、API 密钥和模型启动 Gemini Live 语音会话。
  5. 批准的工具执行目录查询、转接、语音信箱、聊天和上下文操作。
  6. 失败时路由到配置的回退目标，如果路由不可用则使用 ERROR 提示。

测试脚本

  • 验证所选 Gemini 语音和呼叫者语言行为。
  • 搜索允许的目录对象。
  • 验证隐藏的目标无法被选择。
  • 测试转接确认、语音信箱和聊天。
  • 测试自然的告别。
  • 模拟提供商故障并确认回退路由

故障排除

  • Gemini会话失败：确认 Gemini API 密钥、支持的实时模型、许可证、PBX 版本和出站连接。
  • 语音被拒绝：使用配置的 Gemini 模型支持的语音。
  • 缺少目录结果：检查号码、部门和角色可见性。
  • 暴露过多对象：禁用AddAll()。
  • 回退或提示失败：验证目标地址和活动的 ERROR 提示。

另请参阅

最后更新时间

本指南最后更新于2026年7月30日。

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