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

介绍

openaivoiceagent.cs 示例将 3CX 入站呼叫连接到 OpenAI Realtime 语音会话。它可以问候呼叫者、回答一般问题、搜索允许的 3CX 目录条目、连接呼叫者、提供语音信箱或聊天，并在启用该功能时保存有用的呼叫者上下文。

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

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

在 3CX 中创建呼叫脚本

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

• 选择 openaivoiceagent.cs。

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

配置 OpenAI 和脚本

将以下参数添加到PBX：

• OPENAI_API_KEY- 您的 OpenAI 项目的 API 密钥。
• OPENAI_REALTIME_MODEL- OpenAI Realtime 模型。

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

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

接下来，请查看页面顶部附近的这些客户设置。openaivoiceagent.cs：

AddAll() 在初次测试时很方便，但通常应在生产前禁用。将 AllowAllVisibilityForTesting 设为 false，然后仅配置代理需要的号码、部门和角色。

要启用示例自定义工具，请查看其静态响应并取消注释：

RegisterExampleCustomTool();



在将其用于真实客户信息之前，请将示例替换为可信数据源。

选择 保存 以编译。在将生产流量分配给脚本之前，请确认脚本输出报告编译成功。

工作原理

• 入站呼叫到达脚本路由点。
• 脚本清除并重建 AI 目录可见性列表。
• 3CX 准备媒体通道。
• 脚本启动 OpenAI Realtime 语音会话。
• 代理仅使用内置的 3CX 函数和任何显式注册的自定义工具。
• 成功转接后，呼叫者被转接到选定的 3CX 目标。
• 如果媒体设置或提供商会话失败，脚本将尝试配置的回退目标，如果路由也失败，则播放 ERROR 提示。

测试脚本

• 拨打分配的 DID，确认问候语和所选语音。
• 按姓名和号码搜索允许的分机。
• 确认无法搜索或选择隐藏的分机。
• 测试模糊的目录匹配。
• 测试转接、不可用用户的语音信箱和聊天消息行为。
• 在测试环境中使用无效的提供商密钥，并验证回退路由。
• 自然结束对话并确认会话清理。

故障排除

• 提供商会话失败： 验证 OPENAI_API_KEY、支持的实时模型、网络访问、许可证和目标 PBX 版本。
• 坐席找不到用户： 检查 AllowAllVisibilityForTesting、VisibleNumbers、VisibleDepartments 和 VisibleRoles。
• 可见的对象错误： 在添加生产可见性列表之前调用 Clear()，并避免使用 AddAll()。
• 回退不起作用： 确认目标存在且可从指定部门到达。
• 听不到错误提示： 确认活动提示集中存在 ERROR。

另请参阅

• 创建呼叫处理脚本
• 用于 PIN 的呼叫处理脚本示例
• 3CX 管理手册

最后更新时间

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

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