在 3CX 上构建定制 AI 语音代理：Programmable Extensions 与 Call Control API

3CX 上的定制 AI 语音代理，是一个外部托管的应用程序，它连接到您的 PBX，双向传输来电者的音频，并控制呼叫路由——将 3CX 的两个开发者接口与一个外部 AI 提供商结合在一起。这两个接口的发布状态截然不同，厘清这一点正是本文的核心。Programmable Extensions——即官方认可的、将外部应用作为 3CX extension 运行 AI 语音的方式——随 V20 Update 10 以 ALPHA 状态发布（于 2026-07-30 公布），仅供测试和评估，不可用于生产环境。而它所依赖的 Call Control API 则自 V18 起已正式发布（GA），今天即可用于生产。本文说明各组件如何协同、哪些稳定哪些仍处于预览阶段，以及 ECOLOR 如何为您设计、构建、集成、测试、监控和支持一个语音代理。

两大基础组件——以及它们状态为何不同

3CX 上的每一个定制 AI 语音代理，都建立在两项原生开发者能力加一个外部「大脑」之上。请分别保留各自的发布状态，切勿让任何供应商把 Alpha 功能混淆成生产承诺。

Programmable Extensions——ALPHA（V20 Update 10 Alpha，于 2026-07-30 公布）。一个外部托管的应用程序，连接到 PBX 并像原生 extension 一样运作：可加入通话、接收音频、双向传输音频，并通过 Call Control API 驱动路由。这是 3CX 上 AI 语音代理的官方文档化架构——但截至 2026 年 8 月，它仅供测试和评估，不得安装在生产系统上。要试用它，PBX 必须先升级到 V20 Update 9，然后选择 Update 10 Alpha。
Call Control API——自 V18 起 GA（生产可用）。用于以编程方式控制呼叫的成熟接口：发起、接听、路由、转接、挂断和监控呼叫，并检索参与者信息。它以 Call Control Web API 形式提供，并配有官方 TypeScript SDK @3cx/call-control-sdk。它需要 8SC 及以上的 Enterprise 许可证和 Call Flow Designer（CFD）访问权限。这是 Alpha 阶段语音功能所构建于其上的稳定基础。
外部 AI 提供商（自带密钥）。在定制代理路径中，3CX 本身从不执行语音转文字、推理或文字转语音。这一智能能力始终来自您所连接并直接付费的外部实时语音提供商。

简言之：传输音频并控制呼叫的「管道」（Call Control API）已可用于生产；而将外部应用封装为 extension 的 Programmable Extensions 路径仍处于 Alpha 阶段。我们针对两者进行构建和验证，但会诚实地依据已达到稳定版本的部分来定位生产上线。

3CX 官方文档化的四家外部 AI 提供商

3CX 通过其自有的 agentic-call-control GitHub 仓库，正式文档化并演示了恰好四家外部实时语音提供商。每一家都是自带密钥的开发者构建模式——您提供提供商账户和 API 密钥，提供商在单一的实时双向流中完成语音识别、推理和语音合成：

OpenAI Realtime API
Google Gemini Live API
xAI Grok Voice Agent API
Alibaba Cloud Qwen Omni Realtime（DashScope）

我们不会声称这四家之外的任何提供商获得官方支持。每家提供商都有各自的发布状态、区域可用性、定价和计费——这些在方案设计阶段确认，且 AI 使用费由提供商直接向您计费，而非 3CX。

参考架构：定制 AI 语音代理如何组装

定制代理的官方推荐模式是一个完全运行在您自有基础设施上的外部 Programmable Extension——无需 3CX 源代码或任何修改。音频以 PCM、8 kHz、16-bit、单声道（mono）格式传输，编排器（orchestrator）通过带自动重连的 WebSocket 连接到 3CX。典型的构建如下：

在 3CX 中注册 Service Principal。在 Web Client 中进入 Admin → Integrations → API，添加一个 service principal，设置 Client ID，为该应用启用 Call Control API 访问权限，可选地分配一个 DID 并选择它可控制的 extensions，然后记录 Client Secret（仅显示一次）。
部署编排器应用。使用 @3cx/call-control-sdk，外部应用以 app ID、app secret 和 PBX 基础地址进行连接，然后作为 Programmable Extension 加入通话。
将音频桥接到 AI 提供商。编排器将来电者的 PCM 音频流传输至四家已文档化提供商之一，并将提供商合成的语音回传到通话中——双向、实时。
为代理配备工具。接入本地呼叫控制操作（转接、语音信箱、挂断、筛选），可选地接入电话簿查询等操作，以及用于 CRM 或日历工作流的自定义工具。
智能路由。使用 Call Control API 在对话需要时升级到人工队列、转接到相应部门，或回退到 IVR。

关键在于，这是 ECOLOR 定制开发，而非原生的 3CX AI 代理。3CX 提供电话、路由、extensions、SIP 中继和 DID；外部提供商提供智能；而编排、提示词、工具和业务逻辑则按项目定制设计。我们绝不会把 ECOLOR 构建的或自带密钥的代理描述为 3CX 的原生功能。

安全、数据控制与生产考量

由于代理运行在您自有的基础设施上并调用外部 AI 提供商，安全和数据治理是设计决策，而非默认配置。我们会规划经过认证、按 extension 最小权限限定的 Service Principal 凭据、音频与控制通道的加密传输、对通话音频与转录文本的谨慎处理，以及对 AI 提供商保留内容的明确边界。托管位置和数据驻留选项在方案设计阶段确认；架构旨在支持您的治理与合规工作，但任何配置本身都无法使一个组织符合某项特定法规。

在可扩展性和生产就绪方面，我们会考虑并发相对于同时呼叫（SC）许可的关系、编排器的自动扩缩与重连行为、音频桥接的延迟预算、平滑的人工交接、可观测性，以及提供商的速率限制与故障切换。我们始终明确发布状态这条线：只要 Programmable Extensions 仍处于 Alpha，我们今天即可交付评估与试点环境，并将生产上线安排在该功能达到 3CX 稳定版本之时。不对正常运行时间、延迟或成本节省作出任何保证——目标均针对您的具体环境进行验证。

ECOLOR 如何交付您的 AI 语音代理

作为 MENA 3CX Solution Provider，ECOLOR Technologies 提供端到端交付：方案架构、开发、提供商集成、严格测试、监控和持续支持——由驻沙特的技术团队提供阿拉伯语和英语支持。我们负责 Service Principal 配置、编排器、提供商桥接、路由逻辑和可观测性，让您的团队得到一个可用的代理，而不是一堆 SDK。

除原生 3CX 能力外，ECOLOR 还提供自有的 AI Voice Agent——由 ECOLOR 开发、深度集成的对话式语音代理——以及 AutoConnect，ECOLOR 自有的通信自动化平台（AutoDialer、AutoDistributor / Ready Distributor、Evaluation、Smart Routing、仪表板以及 API/webhook 工作流）。两者都扩展并集成 3CX；但都不是 3CX 的原生功能。这使我们能够为您的需求匹配最合适的方式——原生路径、定制的 Programmable Extension 代理、ECOLOR 自有的 AI Voice Agent，或 AutoConnect 自动化——而不是把单一模式强加于每一个用例。请查看我们的 3CX Programmable Extensions 与 AI 语音代理页面、更广泛的 3CX AI 代理中心、ECOLOR 的 AI Voice Agent、AutoConnect 平台、处于 Alpha 的 3CX AI Customer Service Agent，以及这一切如何运行在您的沙特阿拉伯 3CX 电话系统之上。

常见问题

3CX 上的定制 AI 语音代理今天可用于生产吗？

它所依赖的 Call Control API 已 GA 并可用于生产（自 V18 起）。而将外部 AI 应用封装为 3CX extension 的 Programmable Extensions 路径在 V20 Update 10 中为 Alpha（于 2026-07-30 公布）——仅供测试和评估，不可用于生产。ECOLOR 今天即可构建评估与试点环境，并将生产上线安排在 Programmable Extensions 达到稳定版本之时。

3CX 官方为语音代理支持哪些 AI 提供商？

3CX 通过 agentic-call-control 仓库正式文档化了四家外部实时语音提供商：OpenAI Realtime、Google Gemini Live、xAI Grok 和 Alibaba Qwen Omni。它们全都是自带密钥模式——由您提供并支付提供商账户费用。我们不会将任何其他提供商呈现为官方支持。

我需要哪种 3CX 许可证？

Call Control API 需要 8SC 及以上的 Enterprise 许可证和 Call Flow Designer（CFD）访问权限。Programmable Extensions / AI 语音代理路径还额外需要 V20 Update 10 的功能集，且每家外部 AI 提供商都需要各自的账户和 API 密钥。确切的许可按项目确认。