pachca-bots

pachca-bots

クイックスタート

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

ワークフロー

API 経由でボットを作成してトークンを取得する

1. ボットを作成します。ユーザートークンのみ使用できます（ボットのトークンは使用できません）。nickname は必ず _bot で終わる必要があります。Webhook URL、イベント、コマンドなどの Webhook パラメーターは、最初に設定することも、後で設定することもできます。ボットのトークンのスコープは --scopes フラグで制限できます（指定しない場合、ボットにはデフォルトのセットが付与されます）。

   pachca bots create --name="Бот задач" --nickname="tasks_bot" --scopes='["messages:create"]'
   

2. 応答に含まれる access_token を保存します。この値が返されるのは一度だけです。再表示はできず、pachca bots recreate-token <ID> コマンドで再発行することのみ可能です。

3. 応答にはボットの id（user_id）も含まれます。これは、ボットをチャットに追加するなど、以降の呼び出しに必要です。

ボットを作成できるのはユーザートークンのみです。ボットのトークンは使用できません。access_token が返されるのは作成時の一度だけで、再表示はできず、再発行のみ可能です。--empty フラグを指定すると、インターフェースから作成した場合と同様に、トークンと受信 Webhook なしでボットが作成されます。ボットのトークンは pachca bots create-token で発行します。

送信 Webhook を使ってボットを設定する

1. 1 回の呼び出しで Webhook URL とイベントを指定して、ボットを作成します（作成の詳細とトークンの扱いについては、「API 経由でボットを作成してトークンを取得する」のシナリオを参照してください）。

   pachca bots create --name="Бот задач" --nickname="tasks_bot" --outgoing-url="https://example.com/webhook" --events='["message_new"]' --trigger-on=commands --commands='["/task"]'
   

2. 応答に含まれる access_token を保存します（この値が返されるのは一度だけです）。

3. 保存した access_token を使って、ボットとしてメッセージを送信します。

ボットはインターフェースから作成して設定することもできます。Webhook URL とイベントは、PUT /bots/{id} メソッドを使って後から設定することもできます。

ボットの Webhook URL を更新する

1. ユーザートークン（ボットを編集する権限が必要）を使い、ボットの id を指定して URL を更新します。空文字列を指定すると Webhook が無効になります。

   pachca bots update <bot_id> --outgoing-url="https://example.com/webhook"
   

   ボットの id は pachca bots list メソッドで確認できます。

2. または、ボット自身が自分のトークンを使って Webhook を更新します。この方法では id も管理者の操作も必要ありません（bot_self:webhook:write スコープが必要です）。

   pachca bots update-webhook --outgoing-url="https://example.com/webhook"
   

方法は 2 つあります。ユーザートークンを使って id を指定する方法（ボットを編集する権限が必要）と、ボット自身が自分のトークンを使う方法（PUT /bot/webhook）です。空の outgoing_url を指定すると Webhook が無効になります。

ボットのトークンをローテーションする

1. ユーザートークン（ボットの作成者、またはボットが管理者に公開されている場合は管理者）を使い、ボットの id を指定してメイントークンを再発行します。名前のないトークンが対象になり、名前のないトークンがない場合は最も古いトークンが対象になります。以前の値は直ちに無効になります。

   pachca bots recreate-token <bot_id>
   

2. または、ボット自身がメイントークンを再発行します（bot_self:write スコープが必要です）。メイントークンを使ってリクエストした場合、そのトークンは直ちに無効になります。API へのアクセスを失わないよう、応答に含まれる新しい access_token を必ず保存してください。

   pachca bots recreate-token-self
   

3. 個別のボットトークンを再発行するには、pachca bots list-tokens の結果に含まれるそのトークンの id を指定します。値は変わりますが、名前と権限はそのままです。

   pachca bots reissue-token <bot_id> <token_id>
   

新しい値が返されるのは一度だけです。応答に含まれる access_token を保存し、CI またはシークレットストアのシークレットを更新してください。セルフ方式（POST /bot/recreate_token）ではボットのメイントークンが再発行されます。ボットがこのトークンを使用している場合は、同じ操作で応答から新しいトークンを取得してください。

Выпустить боту отдельный токен

1. Пользовательским токеном (создатель бота или администратор, если бот открыт администраторам) получи каталог прав, которые можно выдать этому боту:

   pachca bots list-scopes <bot_id>
   

2. Выпусти токен с именем и правами из каталога. Без --scopes токен выпускается без прав, право не из каталога отклоняется с 400:

   pachca bots create-token <bot_id> --name="Сервер уведомлений" --scopes='["messages:create"]'
   

3. Сохрани token из ответа — полное значение возвращается единственный раз. Дальше в списке pachca bots list-tokens он приходит замаскированным

Отдельный токен удобен на каждый сервис, который работает от имени бота: его отзывают командой pachca bots delete-token, не трогая остальные. Права меняет pachca bots update-token — они действуют сразу, перевыпускать токен не нужно.

Включить боту авторизацию от имени сотрудника

1. Пользовательским токеном (создатель бота или администратор, если бот открыт администраторам) включи авторизацию: где хранится секрет, адреса возврата и права, которые бот попросит у сотрудника. Права бери из pachca bots list-scopes:

   pachca bots update <bot_id> --oauth-client='{"confidential":true,"redirect_uris":["https://example.com/oauth/callback"],"scopes":["messages:read","messages:create"]}'
   

2. Сохрани client_secret из ответа серверного клиента — он возвращается единственный раз. client_id приходит в oauth_client и не секретный

3. Чтобы бот появился в витрине, добавь описание и опубликуй страницу:

   pachca bots update <bot_id> --promo='{"description":"Собирает сводку по задачам","published":true}'
   

Включена ли авторизация, показывает oauth_client_enabled: oauth_client может прийти и у бота с выключенной авторизацией. --oauth-client=null выключает её и отзывает выданные сотрудниками авторизации, новый секрет выпускает pachca bots rotate-client-secret. Кнопку сотруднику и обмен кода на его токен описывает сценарий «Получить токен сотрудника по OAuth» в pachca-oauth.

Найти и удалить бота

1. Пользовательским токеном (скоуп bots:read) получи список ботов, доступных тебе для редактирования: созданных тобой и тех, чьи настройки открывают тебе доступ. Фильтруй по имени параметром query. Пока meta.paginate.has_next равен true, следующую страницу бери из meta.paginate.next_page:

   pachca bots list --query="задач"
   

2. Возьми id нужного бота из списка и удали его (скоуп bots:write). Доступно создателю бота и администратору, если бот открыт администраторам, — владельцы чатов удалять бота не могут. Все токены бота инвалидируются сразу, бот исключается из всех чатов, его вебхуки удаляются:

   pachca bots delete <bot_id>
   

Удаление необратимо: токен бота инвалидируется сразу, бот исключается из чатов. Событие фиксируется в журнале аудита как bot_deleted.

Периодический дайджест/отчёт

1. По расписанию (cron/scheduler): собери данные из своей системы

2. Сформируй текст сообщения с нужными метриками или сводкой

3. Отправь сообщение в канал:

   pachca messages create --entity-id=<chat_id> --content="Дайджест за сегодня: ..."
   

Нет встроенного планировщика — используй cron, celery, sidekiq и т.п. на своей стороне.

Инвентаризация всех ботов пространства

1. Получи всех ботов пространства, а не только доступных для редактирования:

   pachca bots list-company --all
   

   Нужен скоуп company_bots:read, роль владельца пространства и тариф «Корпорация», иначе метод отвечает 403. Фильтр по имени — флаг --query

2. Для каждого бота проверь, раскрыты ли настройки: у ботов, недоступных владельцу токена для редактирования, заполнены только name и nickname, остальные поля вебхука приходят null

   Настройки такого бота можно получить только тем токеном, которому доступно его редактирование

Каждый запрос к списку ботов пространства пишется в журнал аудита как company_bots_accessed.

制限事項

• レート制限：およそ50 req/sec。429 が発生した場合は、待ってから再試行してください。
• webhook.name：最大255文字
• webhook.nickname：最大255文字
• webhook.trigger_on：使用できる値 — commands（commands に指定されたコマンド（トリガーワード）のみ）、all_messages（ボットが参加しているチャットのすべてのメッセージ）、unfurl（リンクの展開（リンクプレビュー））
• webhook.template_engine：使用できる値 — liquid（Liquid — 条件、ループ、フィルター）、mustache（Mustache — ロジックなしの単純な置換）
• webhook.who_can_add：使用できる値 — creator（ボットの作成者のみ）、creator_admin（作成者と会社の管理者）、creator_admin_user（作成者、管理者、会社のメンバー）、anyone（公開ボット：ゲストとマルチゲストを除くすべての従業員が追加できます）
• webhook.kind：使用できる値 — simple（独自形式：ボットのテンプレートに従い、リクエスト本文からメッセージを組み立てます）、gitlab（GitLab：Пачка がリクエストを解析してメッセージを組み立てます）、grafana（Grafana：Пачка がリクエストを解析してメッセージを組み立てます）
• name：最大255文字
• limit：最大50
• ページネーション：カーソルベース（limit + cursor）

エンドポイント

Method	Path	Description
POST	/bot/recreate_token	自分のボットトークンをローテーション
PUT	/bot/webhook	ボットのウェブフックを自己登録
GET	/bots	ボットの一覧
POST	/bots	新しいボット
GET	/bots/{id}	ボット情報
PUT	/bots/{id}	ボットの編集
DELETE	/bots/{id}	ボットの削除
PUT	/bots/{id}/avatar	ボットのアバターをアップロード
DELETE	/bots/{id}/avatar	ボットのアバターを削除
POST	/bots/{id}/recreate_token	ボットトークンをローテーション
POST	/bots/{id}/rotate_client_secret	クライアントシークレットをローテーション
GET	/bots/{id}/scopes	ボットの権限一覧
GET	/bots/{id}/tokens	ボットトークンの一覧
POST	/bots/{id}/tokens	新しいボットトークン
PUT	/bots/{id}/tokens/{token_id}	ボットトークンを変更
DELETE	/bots/{id}/tokens/{token_id}	ボットトークンを削除
POST	/bots/{id}/tokens/{token_id}/reissue	ボットトークンを再発行
GET	/company/bots	ワークスペースのボット一覧
GET	/webhooks/events	イベント履歴
DELETE	/webhooks/events/{id}	イベント履歴を削除

高度なワークフロー

高度なワークフローについては、references/ 内のファイルをお読みください。 references/handle-incoming-webhook-event.md — 受信したウェブフックイベントの処理 references/link-unfurling.md — リンクの展開 references/handle-button-click-callback.md — ボタンのクリック処理（コールバック） references/monitoring-and-alerts.md — 監視とアラート references/process-events-via-history-polling.md — 履歴経由でのイベント処理（ポーリング）

references/webhook-events.md — ウェブフックイベントの種類

タスクの完了方法がわからない場合は、references/ 内の該当するファイルをお読みください。