3CX 可编程分机的 AI 提供商

介绍

3CX 可编程分机(Programmable Extensions) 让开发者能够创建通过 3CX 电话系统处理实时通话的 AI Agent。

3CX Agentic 呼叫控制（Agentic Call Control） 是一套用于构建这些 AI Agent 的现成代码示例。每个示例都将一个可编程分机连接到实时 AI 提供商（如 OpenAI、xAI、Gemini 或 Qwen），并使相关的 3CX 通话控制功能可供 Agent 使用。

本指南展示如何选择 OpenAI、xAI、Gemini 或 Qwen，使用您的 3CX 和提供商凭证配置匹配的示例，启动它，并进行测试通话。

开始之前

下载并解压3CX Agentic 呼叫控制源代码，所有四个示例都包含在同一个包中。

选择 OpenAI、xAI、Google Gemini 或 Alibaba Cloud Qwen，然后使用该提供商的示例文件夹和配置值。

  • 拥有 3CX 管理员权限，可访问 管理员 > 集成 > API 并创建 Service Principal。
  • 已安装 Node.js 20+。Yarn 4 已捆绑在代码库中。
  • 拥有所选 AI 提供商实时服务的 API 密钥。
  • 拥有可用的 3CX 分机（如网页客户端、移动应用或桌面话机），用于向 AI Agent 拨打测试电话。

获取示例

下载 3CX Agentic 呼叫控制源代码后，请转到主文件夹；其中包含 package.json、examples 和 packages。

在 examples 文件夹中，您可以找到相关提供商特定的 Agentic 呼叫控制代码：

  • examples/openai-realtime
  • examples/xai-realtime
  • examples/gemini-realtime
  • examples/alibaba-qwen-realtime

在每个示例文件夹中，您都会找到 config.yaml.example 文件，需要将其复制并重命名为 config.yaml。请保留 config.yaml.example 不变，以便在需要时恢复原始示例设置。

config.yaml 文件包含 PBX 连接和提供商设置，使可编程分机代码能够正常工作。

创建 3CX 服务主体

在PBX中，打开管理 > 集成 > API并选择添加服务主体。

  1. 输入客户端 ID，例如：“assistant”。

Create a 3CX Service Principal

  1. 启用 "为此应用程序启用 3CX Call Control API 访问权限"。
  2. 如果您希望 Agent 具有系统范围的联系人搜索和状态检查能力，还需要启用："为此应用程序启用 3CX Configuration API (XAPI) 访问权限"。根据您希望 Agent 具备的能力设置部门和角色。

Add API Key

  1. 将 3CX API 密钥保存在安全位置。

选择提供商并配置 config.yaml 文件

OpenAI

  • 在 config.yaml 中输入：
  • appId：来自 PBX 集成 > API > 客户端 ID 的 客户端 ID
  • appSecret：来自 集成 > API > 生成 API 密钥 的服务主体的 PBX API 密钥 
  • pbxBase：PBX地址
  • openaiApiKey：来自 OpenAI API 的密钥OpenAI API密钥

OpenAI Configuration Example

安装依赖并启动 OpenAI 示例：

yarn install

yarn start:openai

成功的 OpenAI 启动日志包括：

openai-realtime starting

3CX PBX: https://your-pbx.3cx.eu:5001

OpenAI model: <configured model>

OpenAI voice: <configured voice>

Agent profile: receptionist (role: receptionist)

SDK connected (auth + WebSocket + state)

[MCP] connected to https://your-pbx.3cx.eu:5001/mcp

MCP tools (1/8):

✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

✗ get_server_time: Get the current server time in UTC and local timezone.

✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

✗ find_extension: Find a contact by exact extension number

✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

✗ find_by_email: Find a contact by email address

✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

[CallStore] initialized (OpenAI Realtime mode)

All systems ready (OpenAI Realtime mode)

xAI

  • 在 config.yaml 中输入
  • appId：来自 PBX 集成 > API > 客户端 ID 的 客户端 ID
  • appSecret：来自 集成 > API > 生成 API 密钥 的服务主体的 PBX API 密钥
  • pbxBase：PBX地址
  • xaiApiKey：来自 xAI API 的密钥console.x.ai

xAI Configuration Example

安装依赖项并启动 xAI 示例：

yarn install

yarn start:xai

成功的 xAI 启动日志包括：

xai-realtime starting

3CX PBX: https://your-pbx.3cx.eu:5001

Agent profile: receptionist (role: receptionist)

xAI Voice: tara

SDK connected (auth + WebSocket + state)

[MCP] connected to https://your-pbx.3cx.eu:5001/mcp

MCP tools (1/8):

✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

✗ get_server_time: Get the current server time in UTC and local timezone.

✗ find_by_email: Find a contact by email address

✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

✗ find_extension: Find a contact by exact extension number

[CallStore] initialized (xAI realtime mode)

All systems ready (xAI realtime mode)

Gemini

  • 在 config.yaml 中输入
  • appId：来自 PBX 集成 > API > 客户端 ID 的 客户端 ID
  • appSecret：来自 集成 > API > 生成 API 密钥 的服务主体的 PBX API 密钥
  • pbxBase：PBX地址
  • geminiApiKey：来自 Google AI Studio API 的密钥Google AI Studio

Gemini Configuration Example

安装依赖项并启动 Gemini 示例：

yarn install

yarn start:gemini

成功的 Gemini 启动日志包括：

agentic-call-control starting

3CX PBX: https://your-pbx.3cx.eu:5001

Gemini Voice: Kore

Agent profile: receptionist (role: receptionist)

SDK connected (auth + WebSocket + state)

[MCP] connected to https://your-pbx.3cx.eu:5001/mcp

MCP tools (1/8):

✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

✗ get_server_time: Get the current server time in UTC and local timezone.

✗ find_by_email: Find a contact by email address

✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

✗ find_extension: Find a contact by exact extension number

[CallStore] initialized (Gemini Live mode)

All systems ready (Gemini Live mode)

Qwen

  • 在 config.yaml 中输入
  • appId：来自 PBX 集成 > API > 客户端 ID 的 客户端 ID
  • appSecret：来自 集成 > API > 生成 API 密钥 的服务主体的 PBX API 密钥
  • pbxBase：PBX地址
  • dashscopeApiKey：来自阿里云 DashScope API 的密钥阿里云DashScope API密钥
  • dashscopeBaseUrl： 国际/新加坡密钥使用 https://dashscope-intl.aliyuncs.com，中国大陆密钥使用 https://dashscope.aliyuncs.com。

Qwen Configuration Example

安装依赖项并启动Qwen 示例：

yarn install

yarn start:alibaba-qwen

成功的 Qwen 启动日志包括：

alibaba-qwen-realtime starting

3CX PBX: https://your-pbx.3cx.eu:5001

DashScope: https://dashscope-intl.aliyuncs.com

Model: qwen3.5-omni-plus-realtime

Voice: Tina

Agent profile: receptionist_en (role: receptionist)

SDK connected (auth + WebSocket + state)

[McpManager] connected to https://your-pbx.3cx.eu:5001/mcp

MCP tools (1/8):

✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company

✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.

✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.

✗ get_server_time: Get the current server time in UTC and local timezone.

✗ find_by_email: Find a contact by email address

✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system

✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.

✗ find_extension: Find a contact by exact extension number

[CallStore] initialized (Qwen Omni realtime)

All systems ready (Qwen realtime mode)

测试Agent

使用一个测试分机。对于转接测试，使用第二个内部测试分机。在 3CX Agentic Call Control 主文件夹中，运行您所配置提供商的命令：

  • OpenAI：yarn start:openai
  • xAI：yarn start:xai
  • Gemini：yarn start:gemini
  • Qwen: yarn start:alibaba-qwen

等待终端显示 PBX 连接和就绪状态。

  1. 从测试分机 呼叫 服务主体客户端 ID（appId）。例如，您拨打字面上的 "assistant" Client ID 来连接到 Agent。
  2. 确认 Agent 接听、播放问候语并回复您。
  3. 测试 分机查找或要求它为您挂断通话。
  4. 检查 终端输出是否有错误。

自定义 Agent

使用 config.yaml 更改问候语和提供商特定设置。要更改默认行为，请编辑 agents/receptionist.yaml 或在 agents/ 中添加另一个配置文件。如果您添加了 customMcpServers，请在该 Agent 配置文件的 mcpTools 下列出确切的工具名称。每次配置更改后重新启动 Agent，并再次进行测试通话。

另请参阅

最后更新
本文件最后更新于2026年8月28日
https://www.3cx.cn/docs/agentic-call-control-ai-providers/