Apps API /apps/api/v1/users 端点会检索用户配置数据。您可以读取所有用户或单个用户的当前用户配置，无论其角色如何，也无论其账号是处于活跃状态还是已停用。此输出包含系统角色和自定义角色。如需仅检索活跃客服人员的实时状态和在线状态数据，请参阅 Manager API 客服人员端点。
此端点与批量用户上传流程中使用的端点不同，它提供支持批量操作所需的信息。如需详细了解如何执行批量用户管理流程，请参阅批量用户管理 API。
API 功能和限制
检索用户数据时，您可以添加参数，以便根据需要定制 API 响应。支持以下参数：
特定用户
- ID 选项：邮箱、系统 ID 或自定义用户 ID。用户可以指定一个或多个 ID。如果多个用户 ID 指向同一用户，则该用户在响应中应仅表示一次。
分页
用户可以检索分页结果集，以便管理大型数据集。 API 响应应指明是否有其他页面可供检索。
API 参数允许用户请求特定页面的结果。
用户可以指定页面大小。默认页面大小为 100，最大值为 1,000。如果提供了特定页码，则请求中不能包含用户 ID。
API 响应包含所有用户个人资料和配置字段，但“状态”字段除外。该 API 将提供 deactivated_at 字段，而不是“状态”字段。此字段将包含：
活跃用户数没有值。
用户被停用的日期和时间。
下表列出了 API 响应中包含的用户个人资料字段：
表 1. 用户个人资料字段表
| 订购 | 列类型 | 列数 | 列名称 | 有效值 |
| 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 格式的电话号码。164 格式 |
| 18 | 过滤 | 单 | 过滤 | 字符串 |
| 19 | 过滤超时 | 单人 | 过滤超时 | 介于 0 到 1,440 之间的数值 |
限制
每个请求仅支持一种类型的用户 ID。
每个 API 请求的 ID 数量上限为 1,000。
用户无法在单个 API 请求中同时提供用户 ID 和页码请求。该 API 将根据请求返回所有用户，最多 1,000 个。
API 错误消息
在特定场景下，API 会提供以下错误消息：
页面大小：“请求的页面大小超出了上限（上限为 1,000）”
页面大小（数字输入要求）：“页面大小请求无效；必须是数值”
合并的用户 ID 和分页请求：“不支持合并用户 ID 和分页请求”
User ID (exceeded)：“Exceeded maximum number of user IDs (1,000 is the maximum)”
请求和响应示例
此示例演示了如何检索第一页用户，每页 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"
]
}
]