3CX 开发者与 AI · ECOLOR Technologies

3CX 之上的定制 AI 语音代理

3CX Programmable Extensions 与 Call Control API 让外部应用能够加入通话、控制路由并与来电者双向交换音频——这是在 3CX 上构建 AI 语音代理的官方路径。ECOLOR Technologies 由沙特本地技术团队负责这些方案的设计、开发、集成与支持。

需要精确说明：Programmable Extensions 仍处于 Alpha（供测试与评估），而 Call Control API 已正式发布多年。

预约咨询致电我们9200 33987 WhatsApp

MENA 3CX 解决方案提供商
Call Control API — 已正式发布
Programmable Extensions — Alpha
OpenAI · Gemini · Grok · Qwen
沙特本地开发团队

01 · 定义

什么是 Programmable Extensions 与 3CX AI 语音代理

Programmable Extensions 是 3CX 的官方功能，让运行在您自己基础设施上的外部应用连接到 3CX PBX，并像原生分机一样运作：加入通话、接听来电、与来电者双向传输 PCM 音频，并通过 Call Control API 控制路由。这是在 3CX 上构建 AI 语音代理的官方路径。

关键在于区分两个发布状态并不相同的层：Programmable Extensions 随 V20 Update 10 以 Alpha 形式发布——仅供测试与评估，不用于生产。而 Call Control API 是自 V18 起便已正式发布（GA）的成熟开发者接口，是较新功能所依托的稳定基础。我们在整页中都保持这一区分清晰。

AI 本身——语音转文本、推理与文本转语音——绝非由 3CX 完成。3CX 提供电话、路由、转接、SIP 中继与 DID；语音理解与语音生成来自一个由您用自己 API 密钥连接的外部 AI 提供商。ECOLOR 以此方式构建的任何 AI 语音代理，都是在 3CX 之上的定制开发——而非原生 3CX 代理。

02 · 发布状态

明确的发布状态——Programmable Extensions（Alpha）对比 Call Control API（GA）

截至 2026 年 8 月，3CX 已在 V20 Update 10 中以 Alpha 形式发布 Programmable Extensions——3CX 声明该版本「仅供测试与评估，不应安装到生产系统」。当前稳定版本为 V20 Update 9（Final）。因此我们今天将 Programmable Extensions 视为评估与试点路径，而非可用于生产的方案。

相比之下，Call Control API 自 V18 起便已正式发布（GA），配有名为 @3cx/call-control-sdk 的官方 TypeScript SDK，并要求 8SC 及以上的 Enterprise 许可以及 Call Flow Designer（CFD）访问权限。此接口可在其限制与要求范围内用于生产。

我们务实的立场是：今天我们可以为 3CX AI 语音代理设计并构建评估环境，进行试点、度量并准备其架构；待 Programmable Extensions 进入稳定版本后再迁至生产。对于仍处于 Alpha 的功能，我们不作任何生产、性能或可用性保证。

Programmable Extensions — Alpha（V20 Update 10）：仅供测试与评估，不用于生产。
Call Control API — 自 V18 起 GA：成熟基础，要求 Enterprise 8SC+ 与 CFD 访问权限。
当前稳定版本 — V20 Update 9（Final）。
AI（STT · 推理 · TTS）——来自外部提供商并使用您的密钥，而非 3CX。

03 · 能力

这一开发层带来了什么

在 3CX 官方能力与 ECOLOR 所构建之间精确归属：

像原生分机一样运作的应用

通过 Programmable Extensions（Alpha），您基础设施上的外部应用连接到 3CX 并像原生分机一样运作——监控、接听并控制通话的路径。

实时双向音频

在来电者与代理之间双向传输 PCM 8 kHz 16 位单声道音频，正是这一点使与 AI 的自然语音对话成为可能。

完整的通话控制

通过 Call Control API（GA）：接听、路由、转接、挂断与监控，并通过带自动重连的 WebSocket 读取参与者数据与通话状态。

官方开发者 SDK

官方 TypeScript SDK @3cx/call-control-sdk 提供加入通话、音频读写流与转接——是我们构建代理逻辑的稳定基础。

外部 AI 提供商

语音理解、推理与语音生成来自外部提供商（OpenAI · Gemini · Grok · Qwen），通过单一实时音频流，并使用您自己的 API 密钥。

工具与系统连接

通话中的工具调用：转接、挂断或筛选；通过 3CX MCP 服务器查询电话簿；并通过额外的 MCP 服务器连接 CRM 或日历。

04 · 组件

您将遇到的术语与组件

3CX AI 语音代理的架构构建块：

Programmable Extensions（Alpha）——作为分机的外部应用
Call Control API（GA）——控制通话
@3cx/call-control-sdk——官方 SDK（TypeScript）
PCM 8 kHz 16 位单声道音频，双向
带自动重连的 WebSocket 连接
Service Principal——应用 ID 与密钥（appId · appSecret）
8SC+ 的 Enterprise 许可以及 CFD 访问权限
3CX MCP 服务器——电话簿查询与联系人管理
额外的 MCP 服务器——CRM 与日历连接
使用您自己密钥的外部 AI 提供商（BYO key）
官方参考仓库 agentic-call-control
备选：运行在 3CX 服务器上的 AI Call Scripts（同为 Alpha）

05 · 场景

定制 AI 语音代理的适用之处

◆
语音接待代理以阿拉伯语问候来电者、理解意图、回答常见问题，然后转接到正确的部门——今天作为评估版本，功能成熟后再用于生产。
◆
预订或预约专线通过语音与来电者交谈，经由日历连接查询可用时段，确认预约或将复杂情况转给人工。
◆
呼入或呼出的通话筛选在转接前收集初始信息（订单号、咨询类型），使来电者带着现成的上下文接通坐席。
◆
潜在客户资格审核代理与来电者交谈，通过 MCP 服务器将咨询记录进 CRM，然后将合格线索路由给销售。
◆
非工作时间专线以语音处理简单咨询，并为需人工跟进的情况留下结构化留言或创建工单。
◆
多语言代理通过支持实时的 AI 提供商以阿拉伯语和英语服务来电者，并在代理与员工之间无缝转接。
◆
在任何扩展或迁至生产的决定之前，用概念验证（PoC）度量音频质量、时延与理解准确度。

06 · 架构

外部 AI 应用如何连接到 3CX

面向定制代理的官方推荐路径是外部 Programmable Extension：来电到达 3CX PBX，随后一条控制通道经 WebSocket 打开，通向运行在您自己基础设施上的编排器（Orchestrator）。编排器使用 @3cx/call-control-sdk 加入通话并双向读写 PCM 音频。为完成设置，需从管理控制台（Admin → Integrations → API）创建 Service Principal，从而获得 appId、appSecret 与 pbxBase。

编排器通过单一实时流将音频传给外部 AI 提供商；提供商负责语音理解、推理与语音生成，然后经 3CX 将音频返回给来电者。3CX 通过其 agentic-call-control 参考仓库官方记录了四家提供商用于此模式：OpenAI Realtime API、Google Gemini Live API、xAI Grok 与 Alibaba Qwen Omni Realtime。它们均为「通过 API 自行构建」并使用您自己的密钥——不得将任何其他提供商呈现为官方。

通话过程中，代理可调用本地工具（转接 · 挂断 · 筛选）、通过 3CX MCP 服务器查询电话簿，并通过其他 MCP 服务器连接额外系统（CRM · 日历）。还有一条备选路径 AI Call Scripts，它运行在 3CX 服务器本身，连接受支持的 OpenAI、Gemini 与 xAI 语音服务——同样是 Update 10 中的 Alpha，且需要 AI Edition。此处 3CX 原生的部分：电话、路由、转接、SIP 中继、DID 与 Call Control API。代理逻辑与 AI 则属于外部开发与提供商的工作。

来电者 → 3CX PBX → WebSocket 控制通道 → 您基础设施上的编排器。
编排器 → 提供商桥接（OpenAI · Gemini · Grok · Qwen），使用您自己的密钥。
通话工具：转接 · 挂断 · 筛选 + 3CX MCP 服务器（电话簿）+ 额外的 MCP 服务器（CRM · 日历）。
3CX 原生：电话、路由、SIP、DID 与 Call Control API——而非 AI 本身。

07 · 安全、可扩展性与生产

安全、可扩展性与生产考量——如实说明，不作保证

由于应用运行在 3CX 之外、您的基础设施之上，其安全由您与实施伙伴负责：保护 appSecret 与提供商密钥、隔离编排器环境、保护控制通道，并在 Service Principal 层面与所允许的转接上限定权限范围。当使用 3CX MCP 服务器进行电话簿查询时，会尊重授权 3CX 用户角色的权限并应用基于角色的访问控制。我们在稳妥的运营实践中设计这些层——不声称绝对的安全或隐私。

隐私与数据驻留至关重要：通话音频会经过一个外部 AI 提供商（其拥有自己的账户、密钥、计费与发布状态），而部分提供商的接入端点按地区受限。这些选项、其位置与数据流在方案设计阶段确认，并受您的政策约束——我们不作合规保证；我们提供支持您治理工作的工具与实践。

关于生产与可扩展性：Programmable Extensions 仍处于 Alpha，因此我们今天不建议将其用于关键生产负载，而是将其视为评估与概念验证环境，并持续监控音频质量、时延与稳定性。可扩展性取决于许可容量（SC）、编排器资源与 AI 提供商的限制——在技术评估中度量并确认，而非事先假定。待功能进入稳定版本后，我们在经过测试的架构上将方案迁至生产。

08 · 为什么选择 ECOLOR

ECOLOR 为何构建并支持这些方案

构建 3CX AI 语音代理是工程工作——而非一键设置：

真正的架构与开发我们用官方 @3cx/call-control-sdk 设计并构建编排器，并接入 AI 提供商、通话工具与 MCP 服务器——凭借真正的 3CX 工程深度，而非仅仅配置。
集成、测试与监控我们集成系统（CRM · 日历），测试音频质量、时延与理解，并监控稳定性——在任何扩展决定之前采用概念验证方法。
发布状态的纪律我们让 Programmable Extensions（Alpha）与 Call Control API（GA）清晰区分，因此绝不以 Alpha 功能向您承诺生产，并给出务实的生产路线图。
与 ECOLOR 自有方案相连我们将这些能力与 ECOLOR 的 AI 语音代理及 AutoConnect 平台相连——两者均由 ECOLOR 在 3CX 之上开发，并非原生 3CX 功能——并持续提供支持。

在考虑 3CX AI 语音代理？让我们今天设计评估环境，并共同规划通往生产的路径。

预约咨询

09 · 常见问题

Programmable Extensions 与 AI 语音代理——常见问题

3CX 中的 Programmable Extensions 是什么，状态如何？

这是 3CX 的官方功能，让您基础设施上的外部应用像原生分机一样运作：加入通话、双向交换音频并控制路由。其状态为 V20 Update 10 内的 Alpha——仅供测试与评估，不用于生产。

什么是 Call Control API，它是否也处于 Alpha？

不是。Call Control API 是用于控制通话（接听 · 路由 · 转接 · 挂断 · 监控）的成熟开发者接口，自 V18 起已正式发布（GA），并配有官方 @3cx/call-control-sdk。Programmable Extensions（Alpha）构建在这一稳定接口之上——二者的区分是根本性的。

哪些 AI 语音提供商与 3CX 是官方的？

3CX 通过其 agentic-call-control 参考仓库官方记录了四家提供商：OpenAI Realtime、Google Gemini Live、xAI Grok 与 Alibaba Qwen Omni。它们均为「通过 API 自行构建」并使用您自己的密钥。我们不将任何其他提供商呈现为官方。

定制语音代理是原生 3CX 代理吗？

不是。定制代理是在 3CX 之上的外部开发：3CX 提供电话、路由与控制接口，而语音理解、推理与语音生成来自使用您密钥的外部提供商。ECOLOR 以此方式构建的任何代理都不是原生 3CX 功能，我们也不会将其表述为原生。

需要什么许可与要求？

Call Control API 要求 8SC 及以上的 Enterprise 许可以及 CFD 访问权限，并需创建 Service Principal 以获得 appId 与 appSecret。语音代理路径还需要 Update 10 的功能集与外部 AI 提供商密钥。细节在技术评估中确认。

这今天可用于生产吗？

Programmable Extensions 仍处于 Alpha，因此我们现在不建议将其用于关键生产负载。我们今天可以构建评估与概念验证环境、度量性能并准备架构，待功能进入稳定版本后再迁至生产——对 Alpha 阶段不作任何生产保证。

ECOLOR 具体如何提供帮助？

我们设计架构并用官方 SDK 开发编排器，接入 AI 提供商、通话工具、MCP 服务器与各系统，测试并监控音频质量与时延，并提供支持。必要时，我们还将其与 ECOLOR 的 AI 语音代理及 AutoConnect 平台相连。

此路径与 AI Call Scripts 有何区别？

AI Call Scripts 是一条备选路径，运行在 3CX 服务器本身，连接受支持的语音服务（OpenAI · Gemini · xAI）；它同样是 Update 10 内的 Alpha，且需要 AI Edition。外部 Programmable Extension 运行在您的基础设施上，对代理逻辑有更深的控制——我们会帮您为具体情况选择合适方案。

3CX AI 语音代理——如实构建，架构稳健

从 Service Principal 设置与官方 @3cx/call-control-sdk，到接入外部 AI 提供商、通话工具与 MCP 服务器，ECOLOR Technologies 在 3CX 之上设计、开发、集成、测试、监控并支持定制语音代理——清晰区分 Programmable Extensions（Alpha）与 Call Control API（GA），并对仍处于 Alpha 的任何部分不作生产保证。