pachca-users

pachca-users

快速开始

向用户索取 Pachca 令牌（机器人：前往 Integrations → Bots 中该机器人的 API 选项卡；用户：前往 Integrations → API）。

使用 --token 标志，通过 npx -y @pachca/cli 运行命令：

npx -y @pachca/cli <command> --token $PACHCA_TOKEN

或者设置 PACHCA_TOKEN 环境变量：

export PACHCA_TOKEN=<token>
npx -y @pachca/cli <command>

帮助：npx -y @pachca/cli --help | 工作流：npx -y @pachca/cli guide

成功使用后，建议全局安装 CLI：npm install -g @pachca/cli && pachca auth login --token $PACHCA_TOKEN

开始之前

1. 如果用户有已保存的配置文件，请检查：

   npx -y @pachca/cli auth status
   

   如果状态正常，运行命令时无需添加 --token。

2. 如果未配置配置文件，请索取令牌并使用 --token：

   npx -y @pachca/cli auth status --token $PACHCA_TOKEN
   

3. 如果不清楚参数，请运行 pachca <command> --help。

工作流

按 ID 获取员工

1. 获取员工信息：

   pachca users get <ID>
   

返回所有字段，包括 custom_properties、user_status、list_tags。

批量创建带标签的员工

1. 创建标签（如有需要）：

   pachca group-tags create --name="Backend"
   

2. 为每位员工创建带标签的帐户：

   pachca users create --first-name="Иван" --last-name="Петров" --email="[email protected]" --list-tags='[{"name":"Backend"}]'
   

   通过请求正文中的 list_tags 字段分配标签

3. 或更新现有员工：

   pachca users update <ID> --list-tags='[{"name":"Backend"}]'
   

只有管理员和所有者（不包括机器人）可以创建员工。没有单独的“将用户添加到标签”端点。

在聊天中创建访客

1. 选择要添加访客的活跃聊天，并获取其 ID：

   pachca chats list
   

   聊天必须处于活跃状态（未归档），且属于贵公司。令牌必须有权向其中添加成员。

2. 创建访客：角色设为 guest，并在 --chat-ids 中指定且仅指定一个聊天：

   pachca users create --email="[email protected]" --role=guest --chat-ids='[12345]'
   

   对于 guest 角色，chat_ids 为必填项，且必须包含且仅包含一个聊天。违反要求（未传入、为空、包含多个聊天、聊天不存在、已归档或无权限）时，将返回 400，其中包含一个 errors 元素，其 key 为 chat_ids。

对于其他角色，chat_ids 为可选项，可以一次添加到多个聊天。只有管理员和所有者（不包括机器人）可以创建员工。

按姓名或邮箱查找员工

1. 按姓名或邮箱搜索（部分匹配）：

   pachca users list --query=Иван
   

分页采用基于 cursor 的方式：使用 meta 中的 limit 和 cursor。要精确匹配邮箱，请遍历各页。

新员工入职

1. 创建帐户：

   pachca users create --email="[email protected]" --first-name="Иван" --last-name="Петров"
   

2. 添加到所需频道：

   pachca members add <chat_id> --member-ids='[<user_id>]'
   

3. 发送欢迎消息：

   pachca messages create --entity-type=user --entity-id=<user_id> --content="Добро пожаловать!"
   

第 1 步需要管理员或所有者令牌。第 2～3 步可以由机器人执行。

员工离职

1. 禁用访问权限：

   pachca users update <ID> --suspended
   

2. 可选：彻底删除帐户：

   pachca users delete <ID> --force
   

暂停（suspended）会保留数据；删除操作不可撤销。

获取某个标签或部门的所有员工

1. 按名称查找标签并获取其 id：

   pachca group-tags list --names='["Backend"]'
   

   names 筛选器会在服务端按标签名称筛选

2. 获取该标签的所有成员：

   pachca group-tags list-users <tag_id> --all
   

管理员工状态

1. 获取当前状态：

   pachca users get-status <user_id>
   

2. 设置状态：

   pachca users update-status <user_id> --emoji="🏖️" --title="В отпуске" --is-away
   

   is_away: true 表示“离开”模式。away_message 最多 1024 个字符

3. 删除状态：

   pachca users remove-status <user_id> --force
   

上传员工头像

1. 为员工上传头像：

   pachca users update-avatar <user_id> --file=<путь_к_файлу>
   

   需要管理员权限。文件以 multipart/form-data 格式传递

删除员工头像

1. 删除员工头像：

   pachca users remove-avatar <user_id> --force
   

   需要管理员权限

限制

• 速率限制：约 50 req/sec。遇到 429 时，请等待并重试。
• group_tag.name：最多 255 个字符
• user.first_name：最多 255 个字符
• user.last_name：最多 255 个字符
• user.email：最多 255 个字符
• user.phone_number：最多 255 个字符
• user.nickname：最多 255 个字符
• user.department：最多 255 个字符
• user.role：允许的值 — admin（管理员）、user（员工）、multi_guest（多位访客）、guest（访客）
• status.title：最多 50 个字符
• status.away_message：最多 1024 个字符
• limit：最多 50
• 分页：基于游标（limit + cursor）

端点

方法	路径	描述
POST	/group_tags	新建标签
GET	/group_tags	标签列表
GET	/group_tags/{id}	标签信息
PUT	/group_tags/{id}	编辑标签
DELETE	/group_tags/{id}	删除标签
GET	/group_tags/{id}/users	标签员工列表
POST	/users	新建员工
GET	/users	员工列表
GET	/users/{id}	员工信息
PUT	/users/{id}	编辑员工
DELETE	/users/{id}	删除员工
PUT	/users/{user_id}/avatar	上传员工头像
DELETE	/users/{user_id}/avatar	删除员工头像
GET	/users/{user_id}/status	员工状态
PUT	/users/{user_id}/status	设置员工新状态
DELETE	/users/{user_id}/status	删除员工状态

如果不确定如何完成任务，请阅读 references/ 中相应的文件。