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日あたり最大50通です。上限を超えると、コード daily_invites_limit を含む 422 が返されます。リセット時刻は payload.reset_at にあります。--skip-email-notify を指定するとメールは送信されず、上限にもカウントされません。

チャットにゲストを追加する

1. ゲストを追加するアクティブなチャットを選び、ID を確認します。

   pachca chats list
   

   チャットはアクティブ（アーカイブされていない）で、自社に属している必要があります。トークンには、そのチャットへの参加者追加権限が必要です。

2. ロールを guest に設定し、--chat-ids にチャットを1つだけ指定してゲストを作成します。

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

   ロールが guest の場合、chat_ids は必須で、チャットを1つだけ指定する必要があります。条件を満たさない場合（指定なし、空、複数指定、チャットが存在しない、アーカイブ済み、または権限がない）は、key が chat_ids の要素を含む 400 が返されます。

その他のロールでは chat_ids は任意です。複数のチャットに一度に追加できます。作成できるのは管理者とオーナーのみです（ボットは不可）。

名前またはメールアドレスで従業員を検索する

1. 名前またはメールアドレスで検索します（一部一致）。

   pachca users list --query=Иван
   

ページネーションはカーソルベースです。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/ 内の対応するファイルを読んでください。