获取用户配置数据

Apps API 旨在检索用户配置数据。您可以读取所有用户或单个用户的当前用户配置，无论其角色或状态如何。此输出中包含系统角色和自定义角色。

此端点与批量用户上传过程中使用的端点不同，可提供支持批量操作所需的信息。如需详细了解如何执行批量用户管理流程，请参阅 Bulk User Management API。

API 功能和限制

检索用户数据时，您可以添加参数，以便根据自己的需求定制 API 响应。支持以下参数：

  • 特定用户

    • ID 选项：电子邮件地址、系统 ID 或自定义用户 ID。用户可以指定一个或多个 ID。如果多个用户 ID 指向同一用户，则该用户在响应中应仅显示一次。

  • 分页

    • 用户可以检索分页结果集，以便管理大型数据集。 API 响应应指明是否还有其他网页可供检索。

    • API 参数允许用户请求特定页面的结果。

    • 用户可以指定页面大小。默认页面大小为 100，最大值为 1,000。如果提供了特定页码，则请求中不能包含用户 ID。

API 响应包含所有用户个人资料和配置字段，但“状态”字段除外。该 API 将提供 deactivated_at 字段，而不是“状态”字段。此字段将包含：

  • 没有活跃用户值。

  • 用户被停用的日期和时间。

下表列出了将包含在 API 响应中的用户个人资料字段：

表 1. 用户个人资料字段表

Order 列类型 列数 列名称 有效值
1 电子邮件 1 电子邮件 电子邮件
2 代理 ID 1 代理 ID 字符串
3 名字 1 名字 字符串
4 姓氏 1 姓氏 字符串
5 别名 1 别名 字符串
6 停用时间 1 停用时间 无值，日期/时间
7 Location 1 Location 一个字符串，表示位置名称；空字符串（表示不更改）；null（表示移除当前位置）。
8 Chat 并发性 1 Chat 并发性 1 到 X（其中 X 是配置的值），空
9 Chat 并发状态 1 Chat 并发状态 0、1、空
10 不受限制的国际长途电话 1 不受限制的国际长途电话 (True/False)
11 外部用户 1 外部用户 （是/否）
12 外部 SIP URI 1 外部 SIP URI 字符串
13 UCaaS 用户名 1 UCaaS 用户名 字符串
14 代理扩展 1 代理扩展
15 角色 多个 角色：角色名称 A 角色：角色名称 B 角色：角色名称 C 等。 0、1、空
16 团队 多个 团队：团队名称 A，

团队：团队名称 B，

团队：团队名称 C 等。

0、1、空
17 电话号码 多个 直接入库数量：1，

直接拨入号码：2，

直接入站号码：3

E 中的电话号码。164 格式
18 过滤 单程 过滤 字符串
19 过滤超时 单程 过滤超时 介于 0 到 1,440 之间的数值

限制

  • 每个请求仅支持一种类型的用户 ID。

  • 每个 API 请求的 ID 数量上限为 1,000。

  • 用户无法在单个 API 请求中同时提供用户 ID 和页码请求。API 将根据请求返回所有用户，最多 1,000 个。

API 错误消息

在特定情况下，该 API 会提供以下错误消息：

  • 页面大小：“请求的页面大小超过了最大值（最大值为 1,000）”

  • 页面大小（需要输入数字）：“页面大小请求无效；必须为数值”

  • 用户 ID 和分页请求的组合：“不支持用户 ID 和分页请求的组合”

  • 用户 ID（超出上限）：“超出用户 ID 数量上限（上限为 1,000）”

请求和响应示例

此示例演示了如何检索第一页用户（每页 100 位用户）。响应正文包含一个用户对象数组，每个对象都包含详细的用户配置数据。

请求：

Method: GET
Type:
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/users?page=1&per_page=100

响应：

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

此示例演示了如何通过传递电子邮件参数来检索单个用户的详细信息。响应正文包含一个用户对象，其中包含详细的用户配置数据。

请求：

Method: GET
Type:
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/users?email[]=email

响应：

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  }
]