mcpField
P
pachca-messages

pachca-messages

github.com/pachca生产力1196 次安装今天更新
代码仓库

关于 pachca-messages

pachca-messages 是通过 @pachca/cli 操作 Pachca 消息的技能，涵盖聊天和私信、线程、附件、表情回应及定时草稿，并提供常见沟通任务的操作流程。

主要功能

  1. 01搜索聊天和用户
  2. 02发送、编辑、删除及置顶消息
  3. 03管理线程和表情回应
  4. 04查看消息记录与附件
  5. 05创建定时草稿

适用场景

  1. 01向聊天或频道发送消息
  2. 02回复用户或消息线程
  3. 03发送定时或延迟通知
  4. 04查看阅读者和消息附件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pachca/openapi --skill pachca-messages

安装后在 Claude Code 中输入/pachca-messages确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
list-active-threads-in-a-time-window.md
mention-user.md
reply-to-user-who-messaged-the-bot.md
send-message-with-files.md

详细介绍

pachca-messages

快速开始

向用户索取 Pachca 令牌（机器人：前往「集成 → 机器人」中的机器人 API 选项卡；用户：前往「集成 → 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。

工作流

按名称查找聊天并发送消息

  1. 通过搜索按名称查找聊天：

    pachca search list-chats --query="название"

    如果有多个结果，请根据 name 选择最合适的一个

  2. 在找到的聊天中发送消息：

    pachca messages create --entity-id=<chat_id> --content="Текст сообщения"

entity_type 默认为 "discussion"，可以不指定。

在频道或讨论中发送消息（已知 chat_id 时）
  1. 在聊天中发送消息： 
    pachca messages create --entity-id=<chat_id> --content="Текст сообщения"

"entity_type": "discussion" 为默认值，可以不指定

向用户发送私信

  1. 确定收件人的 user_id：

    pachca search list-users --query="имя"

    或从上下文中获取 user_id（Webhook、先前的请求）

  2. 发送私信：

    pachca messages create --entity-type=user --entity-id=<user_id> --content="Привет!"

无需创建聊天，系统会自动创建

在话题串中回复（评论消息）

  1. 获取或创建话题串，并从响应中取得 thread.id：

    pachca threads add <ID>

    如果话题串已存在，将返回现有话题串

  2. 在话题串中发送消息：

    pachca messages create --entity-type=thread --entity-id=<thread_id> --content="Ответ в тред"

skip_invite_mentions: true — 不自动将被提及的用户添加到话题串中。

发送带按钮的消息

  1. 构造 buttons 数组——一个字符串数组，每个字符串都是一个按钮数组

    每个按钮：{"text": "文本"}，并且要么包含 url（链接），要么包含 data（回调）

  2. 发送带按钮的消息：

    pachca messages create --entity-id=<chat_id> --content="Выбери действие" --buttons='[[{"text":"Подробнее","url":"https://example.com"},{"text":"Отлично!","data":"awesome"}]]'

buttons 是一个嵌套数组（行 × 按钮）。最多 100 个按钮，每行最多 8 个。带 url 的按钮会打开链接，带 data 的按钮会向 Webhook 发送事件。

获取聊天消息历史记录
  1. 分页获取聊天消息： 
    pachca messages list --chat-id=<chat_id>

    limit（1-50）、cursor、sort[id]=asc 或 desc（默认值）

获取话题串中的消息时，请使用话题串的 chat_id（thread.chat_id）。分页基于 cursor，而非 page。

获取消息附件

  1. 获取消息——files[] 中的每个对象都包含 url、name、file_type、size：

    pachca messages get <ID>

  2. 通过 files[].url 下载所需文件

    这是直接链接，无需身份验证

新消息的 Webhook 不包含附件——files 字段不存在。请始终通过 GET /messages/{id} 检查附件。

置顶/取消置顶消息

  1. 置顶消息：

    pachca messages pin <ID>

  2. 取消置顶消息：

    pachca messages unpin <ID> --force

一个聊天中可以有多条置顶消息。

订阅消息话题串

  1. 获取或创建话题串，并从响应中取得 chat_id：

    pachca threads add <ID>

  2. 将机器人添加为话题串聊天的参与者：

    pachca members add <thread_chat_id> --member-ids='[<bot_user_id>]'

  3. 之后，机器人将收到此话题串中新消息的 Webhook 事件

POST /messages/{id}/thread 是幂等操作，可以安全地重复调用。

编辑消息
  1. 更新消息： 
    pachca messages update <ID> --content="Обновлённый текст"

只能编辑自己的消息（或以机器人身份发送的消息）。

Изменить вложения сообщения

  1. Получи текущие вложения из files[]:

    pachca messages get <ID>

    Сохрани нужные объекты (key, name, file_type, size)

  2. Если нужно добавить новый файл — загрузи его:

    pachca files uploads

  3. Обнови сообщение с новым массивом files:

    pachca messages update <ID> --files='[...]'

    files при редактировании — replace-all: присылаемый массив полностью заменяет текущие

files: [] удаляет все вложения. Если поле files не передавать — вложения не меняются.

Удалить сообщение
  1. Удали сообщение: 
    pachca messages delete <ID> --force
Добавить реакцию на сообщение

  1. Добавь реакцию:

    pachca reactions add <ID> --code="👍"

  2. Убрать реакцию:

    pachca reactions remove <ID> --code="👍" --force

code — emoji-символ, не его текстовое название.

Проверить, кто прочитал сообщение

  1. Получи массив user_id прочитавших:

    pachca read-member list-readers <ID>

  2. При необходимости сопоставь с именами сотрудников:

    pachca users list
Разослать уведомление нескольким пользователям

  1. Определи список user_id получателей:

    pachca users list --all

    Или получи user_id из тега — см. «Получить всех сотрудников тега/департамента»

  2. Для каждого: отправь личное сообщение:

    pachca messages create --entity-type=user --entity-id=<user_id> --content="Уведомление"

    Для каждого получателя

Соблюдай rate limit: ~4 req/sec для сообщений. Добавляй паузы при большом списке.

Отправить сообщение позже или по расписанию

  1. Найди чат, в который нужно написать:

    pachca search list-chats --query="название"

  2. Создай отложенное сообщение: schedule.start_date — когда отправить, schedule.repetition.interval — как повторять (once, если один раз):

    pachca drafts create --entity-type=discussion --entity-id=<chat_id> --content="Текст" --schedule='{"start_date":"2026-09-17T09:00:00Z","repetition":{"interval":"once"}}'

    Время без смещения считается UTC: переведи местное время сотрудника сами или пришли со смещением. Повтор по дням недели — interval: "weekly" и days (0 — воскресенье). В ответе next_send_at — ближайшая отправка, сверься с ней.

  3. Чтобы отменить отправку — удали отложенное сообщение:

    pachca drafts delete <ID>

    Другого способа отменить нет: снять расписание правкой нельзя

Метод недоступен токенам ботов — скоупы drafts:read и drafts:write выдаются только людям. Без schedule тот же метод создаёт обычный черновик: он никуда не уйдёт, а будет ждать человека в интерфейсе. Обычный черновик в чате может быть только один, повторный ответит 409, а отложенных бывает до 50 на чат.

Limitations

  • Rate limit: ~50 req/sec, messages ~4 req/sec per chat. On 429 — wait and retry.
  • draft.entity_type: allowed values — discussion (Беседа или канал), thread (Тред), user (Пользователь)
  • draft.schedule.repetition.interval: allowed values — once (Один раз), daily (Каждый день), weekly (Каждую неделю), monthly (Каждый месяц), every_2_months (Раз в два месяца), every_3_months (Раз в три месяца), every_4_months (Раз в четыре месяца), every_6_months (Раз в полгода), yearly (Раз в год)
  • message.entity_type: allowed values — discussion (Беседа или канал), thread (Тред), user (Пользователь)
  • message.display_avatar_url: max 255 characters
  • message.display_name: max 255 characters
  • limit: max — 50 (GET /drafts), 50 (GET /messages), 50 (GET /messages/{id}/reactions), 300 (GET /messages/{id}/read_member_ids), 50 (GET /threads)
  • Pagination: cursor-based (limit + cursor)

端点

MethodPathDescription
POST/direct_url上传文件
POST/drafts新建草稿
GET/drafts草稿列表
GET/drafts/{id}草稿信息
PUT/drafts/{id}编辑草稿
DELETE/drafts/{id}删除草稿
GET/files/{id}下载文件
POST/messages新建消息
GET/messages聊天消息列表
GET/messages/{id}消息信息
PUT/messages/{id}编辑消息
DELETE/messages/{id}删除消息
POST/messages/{id}/link_previews展开链接
POST/messages/{id}/pin置顶消息
DELETE/messages/{id}/pin取消置顶消息
POST/messages/{id}/reactions添加回应
DELETE/messages/{id}/reactions删除回应
GET/messages/{id}/reactions回应列表
GET/messages/{id}/read_member_ids已读消息的用户列表
POST/messages/{id}/thread新建话题串
POST/threads新建独立话题串
GET/threads话题串列表
GET/threads/{id}话题串信息
POST/uploads获取签名、密钥和其他参数

高级工作流

如需了解高级工作流，请阅读 references/ 中的文件： references/reply-to-user-who-messaged-the-bot.md — 回复给机器人发消息的用户 references/send-message-with-files.md — 发送带文件的消息 references/list-active-threads-in-a-time-window.md — 列出指定时间范围内的活跃话题串 references/mention-user.md — 提及用户

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

评论

支持 Markdown