3CX 配置 API

1,491 阅读量

介绍

3CX Version 20 提供了一种新的方式来以编程手段配置您的系统，内部称之为 XAPI。通过 3CX 配置 API，您可以配置 3CX 的任何内容，这涵盖了管理控制台中可以进行的所有操作。该 API 是一个标准化的 Web REST API，基于 OData 技术，并兼容 OpenAPI 规范。

为了开始使用和尝试 XAPI，请下载最新版本的 Postman 和 3CX 配置 API JSON 文件。

将 JSON 文件导入到 Postman 后可以看到如下界面：

img

点击 3CX Configuration API，点击 Variables，可以看到 PBX_FQDN 的变量。将 Current Value 改成 3CX 系统的 FQDN:HTTPS_PORT （不要加 https:// ）。

image-20240624165516298

后续步骤将根据您选择的认证方法填写其他变量。

认证

3CX 配置 API 提供两种类型的认证令牌：

  • “多租户管理员” 令牌（Multi-Company Admin） – 可以管理所有部门和实体。
  • “用户” 令牌（User） – 可以管理自己及其权限范围内的实体。

多租户管理员认证

为了获取多租户管理员令牌，我们需要调用以下 API：

POST /connect/token
Accept: application/json
Authorization: Basic BASE64-ENCODED-USER-NAME-AND-PASSWORD
Content-Type: application/x-www-form-urlencoded
Body: client_id=customer-portal&grant_type=client_credentials

为了获取多公司管理员令牌，我们需要使用以下方法进行身份验证：

  • 授权方式：基础认证 (Basic)
  • 用户名：customer-portal (固定值)
  • 密码：您需要在 3CX 电话系统管理控制台中生成密码（前提是您的 3CX 以多公司模式部署，有关如何部署多公司模式，请参考。

生成密码的步骤：

  1. 登录 3CX 管理控制台。
  2. 导航到“系统” > “多公司”（如果您的 3CX 不是多公司模式，将高级 > 参数 > MULTICOMPANYMODE 设为 1）。
  3. 点击“生成令牌”按钮。

生成的密码将用于后续的 Basic 认证中。

img

在 Postman 中获取访问令牌的步骤：

复制您在 3CX 管理控制台中生成的密码。

在 Postman 中，找到 3CX 配置 API 的 Variables 路径。

创建两个新变量：

  • 名称：API_TOKEN
  • 值：粘贴前面生成的 Token
  • 名称：ACCESS_TOKEN (先留空，后续会用到)

保存这些变量。

在 Postman 中找到 “Multi-Company Admin authentication” 请求。

点击 “Send” 按钮运行该请求。

如果成功，响应体将类似于以下内容：

{
    "token_type": "Bearer",
    "expires_in": 60,
    "access_token": "ACCESS_TOKEN",
    "refresh_token": null
}

从响应体中复制 access_token 的值。

在 Postman 中，找到 3CX 配置 API 的 Variables 路径 (同步骤 2)。

编辑 ACCESS_TOKEN 变量，将值粘贴您复制的访问令牌。

保存 ACCESS_TOKEN 变量。

后续的 API 请求都需要在 Authorization 标头中使用此访问令牌，这样才能进行有效的认证。

用户（User）认证

除了多公司管理员令牌之外，您还可以选择使用某个特定用户身份进行身份验证，并仅在其权限范围内执行操作（具体取决于用户的角色和部门权限）。

创建用户

  1. 登录 3CX 电话系统管理控制台。
  2. 导航到“用户”。
  3. 创建一个新用户，可以设置任意角色（例如系统所有者），确保取消勾选“启用双重身份验证”选项，并为其指定一个有效的电子邮件地址。
  4. 用户创建后，会收到一封包含重置密码链接的欢迎电子邮件，请使用该链接重置密码。

获取用户令牌

为了获取用户令牌，我们需要调用以下 API：

POST /webclient/api/Login/GetAccessTokenAccept: application/jsonContent-Type: application/jsonBody: {"SecurityCode":"", "Password":"USER_PASS", "Username":"USER_NUM"}

解释：

  • 方法：POST
  • 路径：/webclient/api/Login/GetAccessToken
  • 请求头
    • Accept: application/json (指定服务器返回的数据格式)
    • Content-Type: application/json (指定发送给服务器的数据格式)
  • 请求体 (JSON 格式)
    • SecurityCode: 留空 (双重身份验证代码，此处不需要)
    • Password: 用户的 Web 客户端密码 (USER_PASS)
    • Username: 用户的分机号 (USER_NUM)

在 Postman 中设置用户凭证

  1. 在 Postman 中，找到 3CX 配置 API 的 Variables 路径。
  2. 创建两个新变量：
    • 名称：USER_NUM
    • 值：粘贴该用户的分机号
    • 名称：USER_PASS
    • 值：粘贴该用户的 Web 客户端密码
  3. 保存这些变量。
  4. 在 Postman 中找到 “User authentication” 请求。
  5. 点击 “Send” 按钮运行该请求。

获取访问令牌和刷新令牌

如果成功，响应体将类似于以下内容：

{  "Status": "AuthSuccess",  "Token": {    "token_type": "Bearer",    "expires_in": 60,    "access_token": "ACCESS_TOKEN",    "refresh_token": "REFRESH_TOKEN"  },  "TwoFactorAuth": null}

解释：

  • Status: “AuthSuccess” (表示身份验证成功)
  • Token: 令牌信息
    • token_type: “Bearer” (令牌类型)
    • expires_in: 60 (访问令牌的有效期，单位为秒，此处为 1 小时)
    • access_token: 访问令牌 (用于后续的 API 请求)
    • refresh_token: 刷新令牌 (可用于获取新的访问令牌)

使用访问令牌

  1. 从响应体中复制 access_token 的值。
  2. 在 Postman 中，找到 3CX 配置 API 的 Variables 路径 (同步骤 1)。
  3. 编辑 ACCESS_TOKEN 变量，将值粘贴您复制的访问令牌。
  4. 保存 ACCESS_TOKEN 变量。

后续的 API 请求都需要在 Authorization 标头中使用此访问令牌，这样才能进行有效的认证。

注意

  • 所有访问令牌会在 1 小时后过期，因此您的应用程序需要每隔 1 小时或收到 401 响应时重新进行编程身份验证。

快速测试 – 获取 3CX 版本

一旦完成身份验证，您可以调用以下 API 来获取 3CX 电话系统版本。这可以快速验证您的令牌是否有效可用：

GET /xapi/v1/Defs?%24select=IdAuthorization: Bearer ACCESS_TOKEN

解释：

  • 方法：GET
  • 路径：/xapi/v1/Defs?%24select=Id
  • 请求头
    • Authorization: Bearer ACCESS_TOKEN (包含您的访问令牌)

如果身份验证成功，响应状态将为 200 OK，并且响应头中将包含 3CX 电话系统版本信息：

X-3CX-Version: 20.0.x.x

部门（Department）

检查部门是否存在

在 3CX 电话系统中，每个新部门的名称必须唯一。在创建部门之前，我们应该检查该部门名称是否存在。

检查方法：

调用以下 API：

GET /xapi/v1/Groups?$filter=Name eq '3CX Test'

解释：

  • 方法：GET
  • 路径：/xapi/v1/Groups
  • 查询参数：$filter=Name eq '3CX Test' (根据名称 “3CX Test” 进行筛选)

响应结果：

  • 如果部门不存在，响应体将包含一个空数组：
{  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",  "value": []}
  • 如果部门存在，响应体会列出该部门的属性。

创建部门

创建部门的方法：

调用以下 API：

POST /xapi/v1/Groups{  "AllowCallService": true,  "Id": 0,  // 系统自动分配  "Language": "EN",  "Name": "3CX Test",  "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",  // 提示集标识 (具体含义查阅官方文档)  "Props": {    "LiveChatMaxCount": 20,  // 最大实时聊天数量    "PersonalContactsMaxCount": 500,  // 最大个人联系人数量    "PromptsMaxCount": 10,  // 最大提示数量    "SystemNumberFrom": "23960",  // 系统号码范围起始值    "SystemNumberTo": "23979",  // 系统号码范围结束值    "TrunkNumberFrom": "23900",  // 中继线号码范围起始值    "TrunkNumberTo": "23905",  // 中继线号码范围结束值    "UserNumberFrom": "23910",  // 用户号码范围起始值    "UserNumberTo": "23929"  // 用户号码范围结束值  },  "TimeZoneId": "51",  // 时区标识 (具体含义查阅官方文档)  "DisableCustomPrompt": true  // 禁用自定义提示}
  • Language：部门语言
    • EN 英语（US）
    • UK 英语（UK）
    • DE 德语
    • FR 法语
    • ES 西班牙语
    • IT 意大利语
    • PT 葡萄牙语
    • RU 俄语
    • PL 波兰语
    • ZH 中文
  • Prompt：系统提示音语言
  • UserNumberFrom – UserNumberTo
    • 允许用户使用的分机范围
  • TrunkNumberFrom – TrunkNumberTo
    • 允许使用的中继号码范围
  • SystemNumberFrom – SystemNumberTo
    • 允许用户使用的系统分机范围

创建部门后，响应体将包含已创建部门的属性。您应该特别注意以下两个属性，并将其保存下来以便用于后续的 API 请求：

  • Number: 部门的号码 (例如 “GRP1023”)
  • Id: 部门的标识符 (一个唯一的数字)

请将这两个值保存在适当的位置，例如 Postman 的变量中，以便在后续的 API 请求中引用。这将避免您重复输入这些值，并使您的脚本更加高效。

部门管理

更新部门信息

如果某个部门的属性需要更新，您可以按照以下步骤进行操作：

  1. 查找部门：使用以下 API 根据部门号码来查找部门信息：GET /xapi/v1/Groups?$filter=Number eq ‘GRPXXX’解释：
    • 方法：GET
    • 路径：/xapi/v1/Groups
    • 查询参数：$filter=Number eq 'GRPXXX' (根据部门号码 “GRPXXX” 进行筛选)
    注意：您需要将 GRPXXX ersetzt (替换) 为您创建的部门的实际号码 (例如 GRP1023)。
  2. 更新部门：找到部门后，您可以使用以下 API 更新其部分属性：PATCH /xapi/v1/Groups(GROUP-ID){  “Id”: GROUP-ID,  “Name”: “3CX Test1”,  “Props”: {    “LiveChatMaxCount”: 20,    “PersonalContactsMaxCount”: 500,    “PromptsMaxCount”: 10,    “SystemNumberFrom”: “23960”,    “SystemNumberTo”: “23979”,    “TrunkNumberFrom”: “23900”,    “TrunkNumberTo”: “23905”,    “UserNumberFrom”: “23910”,    “UserNumberTo”: “23929” }}解释：
    • 方法：PATCH
    • 路径：/xapi/v1/Groups(GROUP-ID) (将 GROUP-ID 替换为实际的部门标识符)
    • 请求体 (JSON 格式)：包含要更新的部门属性
      • Id：部门标识符 (该值应从第一步获取的查找结果中获得)
      • Name：部门名称
      • Props：包含一些可选属性，具体含义请参考 3CX 配置 API 文档

查找部门

您可以使用相同的方法 (GET /xapi/v1/Groups?$filter=Number eq ‘GRPXXX’) 根据部门号码来查找部门信息。

删除部门

要删除一个部门，请按照以下步骤操作：

  1. 查找部门：同更新部门一样，您需要先根据部门号码查找部门信息。
  2. 删除部门：找到部门后，您可以使用以下 API 删除该部门：POST /xapi/v1/Groups/Pbx.DeleteCompanyById{  “id”: GROUP-ID}解释：
    • 方法：POST
    • 路径：/xapi/v1/Groups/Pbx.DeleteCompanyById
    • 请求体 (JSON 格式)：包含要删除的部门标识符
      • id：部门标识符 (该值应从第一步获取的查找结果中获得)

3CX Live Chat URL 管理

检查网站链接是否存在

您可以使用以下 API 检查某个特定的网站链接是否已经分配给某个部门：

GET /xapi/v1/WebsiteLinks?$filter=Link eq 'LiveChat753947'

解释：

  • 方法：GET
  • 路径：/xapi/v1/WebsiteLinks
  • 查询参数：$filter=Link eq 'LiveChat753947' (根据链接 “LiveChat753947” 进行筛选)

创建 3CX Live Chat URL

如果要为某个部门创建一个新的 3CX Live Chat URL，请使用以下 API：

POST /xapi/v1/WebsiteLinks{  "Advanced": {    "CallTitle": "",    "CommunicationOptions": "PhoneAndChat",    "EnableDirectCall": true,    "IgnoreQueueOwnership": false  },  "CallsEnabled": true,  "ChatBox": {    "ButtonIconType": "Default",    "ButtonIconUrl": "",    "ChatDelay": 2000,    "Height": "28.5vh",    "LiveChatLanguage": "browser",    "LiveMessageUserinfoFormat": "Both",    "MessageDateformat": "Both",    "MinimizedStyle": "BottomRight",    "OperatorIcon": "",    "OperatorName": "",    "ShowOperatorActualName": true,    "WindowIcon": ""

用户 User

用户管理

获取部门用户列表

您可以使用以下 API 获取指定部门的用户列表：

GET /xapi/v1/Users?%24top=100&%24skip=0&%24orderby=Number&%24select=Id&%24select=FirstName&%24select=LastName&%24select=Number&%24select=EmailAddress&%24expand=Groups(%24expand%3DRights%29

解释：

  • 方法：GET
  • 路径：/xapi/v1/Users
  • 查询参数：
    • $top=100: 返回结果的最大条目数 (可选，默认为 100)
    • $skip=0: 跳过结果集中的前 N 个条目 (可选，默认为 0)
    • $orderby=Number: 按照分机号对结果进行排序
    • $select=Id,FirstName,LastName,Number,EmailAddress: 指定要返回的用户信息 (Id, 名, 姓, 分机号, 邮箱地址)
    • $expand=Groups(%24expand%3DRights): 扩展用户所属的组信息，并进一步扩展组的权限信息

检查用户邮箱是否唯一

在同一个 3CX 电话系统中，邮箱地址不能用于不同的用户。创建用户之前，需要使用以下 API 检查目标邮箱是否已经被占用：

GET /xapi/v1/Users?%24top=1&%24filter=tolower%28EmailAddress%29 eq %27testsmbcreation%40testsmbcreation1.com%27&%24orderby=Number&%24select=Id&%24select=FirstName&%24select=LastName&%24select=Number&%24select=EmailAddress&%24expand=Groups(%24expand%3DRights%29

解释：

  • 方法：GET
  • 路径：/xapi/v1/Users
  • 查询参数：
    • $top=1: 返回结果的最大条目数 (设置成 1，因为我们只需要检查是否存在)
    • $filter=tolower(EmailAddress) eq 'testsmbcreation@testsmbcreation1.com': 筛选条件，使用 tolower 函数将邮箱地址转换为小写进行匹配 (替换 ‘testsmbcreation@testsmbcreation1.com‘ 为您要检查的邮箱地址)
    • $orderby=Number: 按照分机号对结果进行排序 (可选)
    • $select=Id,FirstName,LastName,Number,EmailAddress: 指定要返回的用户信息 (Id, 名, 姓, 分机号, 邮箱地址)
    • $expand=Groups(%24expand%3DRights): 扩展用户所属的组信息，并进一步扩展组的权限信息

注意： 此操作需要使用 “多公司管理员” 或 “系统所有者” 权限的凭据，以检查所有 PBX 用户。

创建用户

如果邮箱地址可用，您可以使用以下 API 创建一个新用户：

POST /xapi/v1/Users{  "AccessPassword": "QrzxYQwa5!",  // 用户密码  "EmailAddress": "test@contoso.com",  // 用户邮箱地址  "FirstName": "TestFirstName",  // 名  "Id": 0,  // 系统自动分配  "Language": "EN",  // 用户语言 (默认为英语)  "LastName": "TestLastName",  // 姓  "Number": "211",  // 分机号  "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",  // 提示集标识 (具体含义查阅官方文档)  "SendEmailMissedCalls": true,  // 是否通过电子邮件发送未接来电通知  "VMEmailOptions": "Notification",  // 语音邮件电子邮件选项 (此处设置为 "Notification")  "Require2FA": true  // 是否强制启用双重身份验证}

响应将包含新创建用户的 ID 信息。

创建用户友好 Url

有效链接：

POST /xapi/v1/WebsiteLinks/Pbx.ValidateLink
{
    "model": {
        "FriendlyName": "testsmbcreationtests",
        "Pair": "23910"
    }
}

更新用户信息：

PATCH /xapi/v1/Users(USER-ID)
{
    "CallUsEnableChat": true,
    "ClickToCallId": "thisisatest",
    "Id": 1732,
    "WebMeetingFriendlyName": "thisisatest"
}

用户 ID (USER-ID) 是通过 GET /xapi/v1/Users 获取的用户的 ID (例如 1234)。

在部门中分配用户角色

PATCH /xapi/v1/Users(USER-ID)
{
    "Groups": [{
            "GroupId": GROUP-ID,
            "Rights": {
                "RoleName": "group_owners"
            }
        }
    ],
    "Id": USER-ID
}

RoleName 有下面几种身份：

  • “system_owners”
  • “system_admins”
  • “group_owners”
  • “managers”
  • “group_admins”
  • “receptionists”
  • “users”

删除用户

批量删除用户：用逗号分隔的用户 ID 列表指定要删除的用户。

POST /xapi/v1/Users/Pbx.BatchDelete
{
   "ids":[
            USER1-ID,
            USER2-ID
            ]
}

系统分机

创建共享通道

检查是否存在

GET /xapi/v1/Groups(GROUP-ID)?%24expand=Members

检查响应中是否有类型 “停泊 “的成员。

获取 DEFAULT 部门的信息（我们需要 ID）

GET /xapi/v1/Groups?$filter=Name eq 'DEFAULT'

创建共享停泊：

POST /xapi/v1/Parkings
{
    "Groups": [{
            "GroupId": GROUP-ID
        }, {
            "GroupId": DEFAULT-GROUP-ID
        }
    ],
    "Id": 0
}

删除呼叫停泊

删除分配给部门的呼叫停泊

获取部门成员（删除呼叫停泊）

GET /xapi/v1/Groups(1731)?%24expand=Members

为每个 “呼叫停泊” 类型的成员获取停泊详细信息（我们需要停泊 ID）并将其删除：

GET /xapi/v1/Parkings/Pbx.GetByNumber(number=%27SP271%27)
DELETE /xapi/v1/Parkings(PARKING-ID)

PARKING-ID 在前面的步骤中获得。

其他接口

的确，3CX 配置 API 为自动化任务和将您的 3CX 系统与其他应用程序集成打开了大门。 通过浏览 YAML 文件，您可以发现所有可用的端点，它们对应于您可以在 Web 客户端和管理控制台中执行的操作。

以下是快速入门步骤：

  1. 浏览到 3CX 配置 API YAML 文件。
  2. 将 YAML 文件保存到您的本地计算机上。
  3. 将 YAML 文件导入 Postman（或其他 API 客户端工具）中的新工作区或集合下。 这将使用所有 API 端点填充您的客户端，并使其更易于探索和测试。

通过遵循这些步骤，您将拥有用于以编程方式与您的 3CX 系统交互的强大工具集。如果您有使用 Postman 或类似工具的经验，这将是自动化任务和扩展 3CX 系统功能的好方法。

img

绝对没问题，欢迎您随时提供反馈！ 如果您在使用 API 时遇到任何问题或想讨论相关主题，请随时在我们的论坛中提问 https://www.3cx.com/community/tags/api/。

Filed Under: 未分类