pachca-chats

pachca-chats

快速开始

请向用户索取 Pachca 令牌（机器人：进入 Integrations → Bots，打开机器人的 API 选项卡；用户：进入 Integrations → API）。

使用 npx -y @pachca/cli 运行命令，并添加 --token 标志：

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。

工作流

创建频道并邀请成员

1. 创建包含成员的频道：

   pachca chats create --name="Новый канал" --channel --member-ids='[1,2,3]'
   

   "channel": true 表示频道，false（默认值）表示对话。创建时可直接传入成员：member_ids 和／或 group_tag_ids

2. 或稍后再添加成员：

   pachca members add <chat_id> --member-ids='[1,2,3]'
   

channel 是布尔值，不是字符串。创建时 member_ids 和 group_tag_ids 均为可选项。

重命名或更新聊天

1. 更新聊天：

   pachca chats update <ID> --name="Новое название"
   

   可用字段：name、public

要更改成员，请使用 POST/DELETE /chats/{id}/members。

设置或移除聊天头像

1. 上传对话或频道的头像：

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

   文件以 multipart/form-data 格式传输：jpg、jpeg、png 或 gif。私人聊天和线程没有头像 — 响应为 403

2. 要移除头像，请将其删除：

   pachca chats remove-avatar <ID> --force
   

有权限更改聊天名称的用户也可以执行此操作。头像链接会通过聊天的 avatar_url 字段返回。

从模板创建项目对话

1. 创建包含标签成员的对话：

   pachca chats create --name="Проект Alpha" --group-tag-ids='[42]' --member-ids='[186,187]'
   

2. 发送欢迎消息：

   pachca messages create --entity-id=<chat_id> --content="Добро пожаловать в проект!"
   

创建时使用 group_tag_ids 会立即添加该标签的所有成员。

查找一段时间内活跃的聊天

1. 获取指定日期之后有活动的聊天：

   pachca chats list --last-message-at-after=<дата> --all
   

   要指定时间范围，请添加 --last-message-at-before。日期使用 ISO-8601 UTC+0

查找并归档不活跃的聊天

1. 获取自指定日期以来没有活动的聊天：

   pachca chats list --last-message-at-before=<порог> --all
   

   结果不包含已归档的聊天，因此无需再筛除已归档项。要同时获取归档和活跃聊天，请添加 --archived，并查看每个聊天的 archived 字段

2. 对每个聊天执行归档：

   pachca chats archive <ID>
   

   请检查 "channel": false — 归档频道可能并不合适

导出空间中的所有聊天，包括已关闭的聊天

1. 获取整个空间的对话和频道，包括令牌所有者未加入的已关闭聊天：

   pachca chats list-company --all
   

   返回活跃和归档聊天。要只保留一种状态，可使用值为 active 或 archived 的 --activity 标志。该方法不会返回私人对话和线程

2. 如果该方法返回 403 — 令牌缺少 company_chats:read 范围，或令牌所有者不是空间所有者，或空间没有「Корпорация」套餐。此时请通过普通列表获取开放聊天：

   pachca chats list --availability=public --archived --all
   

   令牌未加入的已关闭聊天不会出现在此结果中

每次请求空间聊天列表都会以 company_chats_accessed 记录在审计日志中。

限制

• 速率限制：约 50 req/sec。遇到 429 时，请等待后重试。
• chat.name：最多 255 个字符
• role：允许的值 — admin（管理员）、editor（编辑者（仅适用于频道））、member（成员或订阅者）
• limit：最多 50
• 分页：基于游标（limit + cursor）

端点

Method	Path	Description
POST	/chats	新建聊天
GET	/chats	聊天列表
POST	/chats/exports	导出消息
GET	/chats/exports/{id}	下载导出归档
GET	/chats/{id}	聊天信息
PUT	/chats/{id}	编辑聊天
PUT	/chats/{id}/archive	归档聊天
PUT	/chats/{id}/avatar	上传聊天头像
DELETE	/chats/{id}/avatar	删除聊天头像
POST	/chats/{id}/group_tags	添加标签
DELETE	/chats/{id}/group_tags/{tag_id}	从聊天中移除标签
DELETE	/chats/{id}/leave	退出聊天
GET	/chats/{id}/members	聊天参与者列表
POST	/chats/{id}/members	添加参与者
DELETE	/chats/{id}/members/{user_id}	移除参与者
PUT	/chats/{id}/members/{user_id}	编辑参与者角色
PUT	/chats/{id}/unarchive	取消归档聊天
PUT	/chats/{id}/unread	将聊天标记为未读
GET	/company/chats	空间聊天列表

高级工作流

有关高级工作流，请阅读 references/ 中的文件： references/archive-and-manage-chat.md — 归档和管理聊天 references/export-chat-history.md — 导出聊天记录

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