pachca-messages

pachca-messages

クイックスタート

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 を実行します。

ワークフロー

名前でチャットを検索してメッセージを送信する

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="имя"
   

   または、コンテキスト（Webhook、前回のリクエスト）から user_id を取得します。

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 個で、1 行あたり最大 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）を使用します。ページネーションは page ベースではなく cursor ベースです。

メッセージから添付ファイルを取得する

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)

エンドポイント

Method	Path	Description
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/ 内の該当するファイルをお読みください。