使用 3CX 可编程扩展构建您自己的 AI 语音应用

使用呼叫控制 API、呼叫控制 SDK 和受支持的实时 AI 提供商，将外部托管的 AI 语音应用程序连接到 3CX。

介绍

3CX 可编程扩展允许外部托管的应用程序连接到 PBX，并像原生分机一样运行。该应用程序可以接收呼叫、双向流式传输音频，并通过 3CX 呼叫控制 API 控制呼叫路由。

Agentic Call Control 示例提供了适用于以下平台的可运行的 Node.js 应用程序：

  • OpenAI Realtime
  • Google Gemini Live
  • xAI Grok Voice Agent
  • 阿里云 Qwen Omni Realtime

每个示例都使用单个双向实时音频会话。语音识别、推理和语音生成由所选 AI 提供商处理，而 3CX 继续提供电话功能、呼叫路由、分机、SIP 中继和 DID。

这些示例通过已发布的 3CX API 连接，无需更改 PBX 源代码。它们还连接到 3CX MCP 端点，以便语音应用程序可以使用授权的 PBX 工具（如电话簿查找）。您还可以添加可选的外部 MCP 服务器，用于日历、CRM 和其他业务系统。

我应该使用哪个选项？

本指南介绍 可编程扩展，即应用程序在您管理的基础设施上运行于 3CX 外部。对于即用型可配置解决方案，请使用内置的 3CX AI 代理。对于直接在 3CX 服务器上运行的自定义应用程序，请使用 AI 呼叫脚本。

您将构建什么

完成本指南后，您将拥有一个外部 AI 语音应用程序，它能够：

  • 通过其 3CX 客户端 ID 接收内部呼叫。
  • 通过分配的 DID 接收外部呼叫。
  • 使用您选择的 AI 提供商进行实时语音对话。
  • 通过 MCP 搜索 3CX 电话簿。
  • 通过 3CX 呼叫控制转接呼叫、发送至语音信箱或结束呼叫。
  • 连接到其他 MCP 服务器，并向模型公开选定的工具。

提供的代理配置文件实现了一个基本的接待员流程。它旨在作为起点，可以扩展用于预约、客户信息、调查、内部服务台和其他工作流。

开始之前

你需要：

  • 具有呼叫控制 API 访问权限的 3CX V20 Update 10 系统。
  • 管理员访问权限以创建 API 服务主体。
  • 托管应用程序的计算机或服务器上安装 Node.js 20 或更高版本。
  • 存储库中捆绑的 Yarn 版本。
  • 至少一个受支持的 AI 提供商的 API 密钥和可用配额。
  • 从应用程序主机到 3CX HTTPS FQDN 以及所选提供商的 WebSocket 端点的网络访问。

步骤 1：下载示例

克隆或下载 Agentic Call Control 仓库：打开 Agentic Call Control 存储库

在终端中，切换到存储库根目录并安装所有工作区依赖项：

yarn install

如果 yarn 命令不可用，请先启用 Corepack：

corepack enable

yarn install

不要运行yarn 安装每个提供程序目录下都应单独安装。该仓库是一个 Yarn 工作区，应从其根目录安装。

步骤 2：创建 3CX 服务主体

创建外部应用程序用于向 PBX 进行身份验证的凭据。

  • 登录 3CX 网页客户端 并打开 管理。
  • 转到 集成 > API。
  • 点击 添加 以创建服务主体。
  • 输入 客户端 ID，例如 ai-receptionist。这将成为应用程序的 appId，也是用户可以拨号以呼叫该应用程序的内部号码。
  • 为应用程序启用 3CX 呼叫控制 API 访问。
  • 如果外部呼叫者必须能够直接联系到它，则可选地分配一个 DID。
  • 可选地选择应用程序被允许监控或控制的分机。仅授予工作流程所需的访问权限。
  • 保存服务主体。
  • 立即复制生成的 API 密钥或客户端密钥。它将用作 appSecret，且仅显示一次。

步骤 3：选择 AI 提供商

使用以下包含的示例之一。

提供商

示例目录

提供商凭据

启动命令

OpenAI Realtime

examples/openai-realtime

openaiApiKey

yarn start:openai

Google Gemini Live

        examples/gemini-realtime

geminiApiKey

yarn start:gemini

xAI Grok Voice Agent

examples/xai-realtime

xaiApiKey

yarn start:xai

阿里云 Qwen Omni Realtime

examples/alibaba-qwen-realtime

dashscope API密钥

yarn start:alibaba-qwen

在所选提供商的控制台中创建 API 密钥并妥善保存：

有关当前模型可用性、语音、区域、定价和速率限制，请参阅所选提供商的文档以及相应示例目录中的 README。

Qwen 区域说明：DashScope 凭据和端点是区域特定的。请使用创建 API 密钥的区域和工作空间所需的端点。

步骤 4：创建提供商配置

将 config.yaml.example 复制为所选示例目录中的 config.yaml。

OpenAI

cp examples/openai-realtime/config.yaml.example examples/openai-realtime/config.yaml

Gemini

cp examples/gemini-realtime/config.yaml.example examples/gemini-realtime/config.yaml

xAI

cp examples/xai-realtime/config.yaml.example examples/xai-realtime/config.yaml

阿里云 Qwen

cp examples/alibaba-qwen-realtime/config.yaml.example examples/alibaba-qwen-realtime/config.yaml

在 Windows PowerShell 中，请使用 Copy-Item 代替 cp。

打开新的 config.yaml 并输入通用的 3CX 值：

appId: ai-receptionist

appSecret: your-3cx-api-key

pbxBase: https://your-pbx.example.com

companyName: Your Company

agentName: Assistant

initialGreeting: Thank you for calling. How can I help you today?

保留所选示例提供的 agentProfile 值。OpenAI、Gemini 和 xAI 使用 receptionist；Qwen 包含单独的英文和中文配置文件。

接下来，设置所选提供商的凭据。例如，OpenAI 配置包含：

openaiApiKey： sk-your-openai-api-key

使用提供商提供的 config.yaml.example 作为模型、语音、语音活动检测和提供商特定设置的准确来源。对于 Qwen，请保留提供商特定区域的基础 URL 配置。

安全： config.yaml 包含机密信息。它已被提供的 .gitignore 排除，但您仍应避免共享、提交或将其包含在支持日志中。生产环境请使用机密管理器或基于环境的部署方法。

步骤 5：启动应用程序

从存储库根目录运行所选提供商的命令。

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

阿里云 Qwen

yarn start:alibaba-qwen

具体的启动输出因提供商而异。成功启动应确认以下事项：

  • 应用程序已通过 3CX 身份验证。
  • 呼叫控制 SDK 和 WebSocket 连接处于活动状态。
  • 应用程序已连接到 3CX MCP 端点。
  • 已启用的 MCP 工具已加载。
  • 呼叫处理程序已初始化，应用程序已准备好接受呼叫。

步骤 6：呼叫并测试应用程序

进行内部通话

从已注册的 3CX 分机，拨打配置为 appId 的 客户端 ID。

例如，如果客户端 ID 是 ai-receptionist，则从 3CX 网页客户端、桌面应用、移动应用或已配置的电话拨打 ai-receptionist。

进行外部呼叫

如果您为服务主体分配了 DID，请从外部电话拨打该号码。

建议的测试

在自定义之前，请测试完整工作流：

  • 确认坐席以配置的问候语应答。
  • 要求与已知电话簿联系人通话。
  • 确认坐席通过 MCP 搜索电话簿。
  • 测试成功转接。
  • 测试不可用用户和语音信箱路径。
  • 在坐席说话时打断它，以验证插话行为。
  • 结束呼叫并确认应用程序正确释放呼叫。

使用 Ctrl+C 停止应用程序。

自定义坐席

基本设置（如公司名称和代理名称）存储在 config.yaml 中。

更详细的行为由所选示例的 agents 目录中的 YAML 配置文件定义。根据提供商示例，默认配置文件名为 receptionist.yaml、receptionist_en.yaml 或 receptionist_cn.yaml。

配置文件控制以下方面：

  • 角色和系统提示词。
  • 问候语和语言行为。
  • 呼叫筛选要求。
  • 转接前的可用性检查。
  • 允许的呼叫操作。
  • 被阻止的分机。
  • 垃圾邮件、敌意和不配合呼叫者策略。
  • 向模型公开的 MCP 工具。

更改 config.yaml 或选定的代理配置文件后，重新启动应用程序。

保持提示词和工具权限一致。告诉模型它可以执行某个操作，并不授予底层应用程序或服务主体执行该操作的权限。

使用 3CX MCP 工具

启动时，示例会连接到 3CX MCP 端点，并发现已认证服务主体可用的工具。

只有坐席配置文件 mcpTools 允许列表中列出的工具才会暴露给 AI 模型。默认的接待员配置文件启用了电话簿查找：

mcpTools:

  - list_phonebook

启动日志会显示从服务器发现的工具以及每个工具是否已启用。要公开另一个已授权的工具，请将其确切名称添加到 mcpTools 并重新启动应用程序。

将该列表限制为工作流所需的最小工具集。未暴露给模型的工具无法被模型调用。

连接其他 MCP 服务器

可以在 config.yaml 的 customMcpServers 下配置可选的 MCP 服务器。这可以使语音应用程序访问经批准的日历、CRM 或业务流程工具。

为方便测试，这些示例支持 auth.type: bearer 或 auth.type: none。若要快速试用而无需运行自己的 MCP 服务器，可使用托管连接器如 Smithery：将远程 URL 和 Bearer 令牌粘贴到 customMcpServers 中，然后在 mcpTools 中启用发现的工具名称。

customMcpServers:

  - name: GoogleCalendar

    url: https://mcp.example.com/your-server

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true

使用工具的确切名称将每个要暴露的工具添加到坐席配置文件中：

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add

从自定义 MCP 服务器发现的工具将与可用的 3CX MCP 工具合并，但配置文件允许列表仍控制模型可以使用哪些工具。

添加外部 MCP 服务器时：

  • 使用最小权限凭据。
  • 仅暴露所需的工具。
  • 在服务器端验证工具参数。
  • 对于敏感或不可逆操作，酌情要求审批。
  • 不要将长期有效的生产机密直接放入源代码管理。

超越接待员的例子

附带的接待员逻辑演示了电话簿搜索、转接、语音信箱和呼叫终止。相同的架构可以扩展以支持以下工作流：

  • 预约安排。
  • 客户或账户信息查询。
  • 自动化调查。
  • 内部 IT 或 HR 服务台。
  • CRM 工单创建和更新。
  • 订单状态或配送信息服务。
  • 自定义业务应用程序的语音界面。

应用程序负责业务逻辑、验证、错误处理和工具安全性。3CX 提供呼叫连接、音频流和呼叫控制功能，而所选 AI 提供商处理实时对话。

生产环境检查清单

在将自定义应用程序投入生产之前：

  • 将其作为托管服务运行，具备自动重启和健康监控。
  • 使用机密管理器保护 API 凭据，并定期轮换。
  • 将服务主体限制为所需的分机和功能。
  • 审查 AI 提供商的数据处理、保留和区域可用性政策。
  • 在需要录音、转录或 AI 披露时，告知呼叫者并获取同意。
  • 监控提供商使用量、速率限制和成本。
  • 添加超时、重试处理和非 AI 回退路由。
  • 在真实呼叫条件下测试转接、语音信箱、故障和断开路径。
  • 审查每个已启用的 MCP 工具，并通过额外的验证或审批来保护敏感操作。

故障排除

yarn 未被识别

请确保已安装 Node.js 20 或更高版本，然后启用 Corepack：

corepack enable

从存储库根目录再次运行 yarn install。

PBX 认证返回 401 或 403

检查 appId、appSecret 和 pbxBase 是否与服务主体匹配。确认已启用呼叫控制 API 访问，并且 3CX 许可证和权限允许所请求的操作。

应用程序启动但未收到呼叫

确认应用程序仍在运行，拨打正确的客户端 ID，并在测试外部呼叫时验证 DID 已分配给服务主体。

MCP 工具显示为禁用

将启动日志中显示的确切工具名称复制到配置文件的 mcpTools 列表中，然后重新启动应用程序。同时确认服务主体已被授权使用该工具。

转接或语音信箱失败

验证目标是否有效且服务主体可以访问。如果配置文件中启用了呼叫筛选，请确认在尝试转接之前已收集所需的筛选字段。

AI 提供商拒绝连接

检查 API 密钥、账户计费、模型访问权限、区域、配额和 WebSocket 连接。对于 Qwen，请确认 API 密钥和端点属于同一区域和工作空间。

音频延迟或坐席频繁被打断

检查应用程序主机、3CX 和 AI 提供商之间的网络延迟和丢包情况。查看 config.yaml 中提供商特定的语音活动检测和音频设置。

最后更新时间

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

https://www.3cx.cn/docs/programmable-extensions/