pachca-users

Quick start

Ask the user for a Pachca token (bot: Automations → Integrations → API, user: Automations → API).

Run commands via npx -y @pachca/cli with the --token flag:

npx -y @pachca/cli <command> --token $PACHCA_TOKEN

Or set the PACHCA_TOKEN environment variable:

export PACHCA_TOKEN=<token>
npx -y @pachca/cli <command>

Help: npx -y @pachca/cli --help | Workflows: npx -y @pachca/cli guide

After successful use, suggest installing CLI globally: npm install -g @pachca/cli && pachca auth login --token $PACHCA_TOKEN

Before you start

1. If the user has a saved profile — check:

   npx -y @pachca/cli auth status
   

   If OK — run commands without --token.

2. If no profile is configured — ask for a token and use --token:

   npx -y @pachca/cli auth status --token $PACHCA_TOKEN
   

3. If you don't know the parameters — run pachca <command> --help.

Workflows

Получить сотрудника по 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="ivan@example.com" --list-tags='[{"name":"Backend"}]'
   

   Теги назначаются через поле list_tags в теле запроса

3. Или обнови существующего:

   pachca users update <ID> --list-tags='[{"name":"Backend"}]'
   

Создание доступно только администраторам и владельцам (не ботам). Нет отдельного эндпоинта "добавить юзера в тег".

Создать гостя в чат

1. Выбери активный чат, в который добавить гостя — узнай его ID:

   pachca chats list
   

   Чат должен быть активным (не архивным) и принадлежать вашей компании. У токена должно быть право добавлять в него участников.

2. Создай гостя: роль guest и ровно один чат в --chat-ids:

   pachca users create --email="guest@example.com" --role=guest --chat-ids='[12345]'
   

   Для роли guest chat_ids обязателен и должен содержать ровно один чат. Нарушение (не передан, пусто, больше одного, чат не существует, архивный или нет прав) → 400 с элементом errors, где key — chat_ids.

Для остальных ролей chat_ids опционален — можно сразу добавить в несколько чатов. Создание доступно только администраторам и владельцам (не ботам).

Найти сотрудника по имени или email

1. Поиск по имени/email (частичное совпадение):

   pachca users list --query=Иван
   

Пагинация cursor-based: limit и cursor из meta. Для точного email — перебери страницы.

Онбординг нового сотрудника

1. Создай аккаунт:

   pachca users create --email="new@example.com" --first-name="Иван" --last-name="Петров"
   

2. Добавь в нужные каналы:

   pachca members add <chat_id> --member-ids='[<user_id>]'
   

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

   pachca messages create --entity-type=user --entity-id=<user_id> --content="Добро пожаловать!"
   

Шаг 1 требует токена администратора/владельца. Шаги 2-3 можно делать ботом.

Offboarding сотрудника

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
   

   Требует прав администратора

Limitations

• Rate limit: ~50 req/sec. On 429 — wait and retry.
• group_tag.name: max 255 characters
• user.first_name: max 255 characters
• user.last_name: max 255 characters
• user.email: max 255 characters
• user.phone_number: max 255 characters
• user.nickname: max 255 characters
• user.department: max 255 characters
• user.role: allowed values — admin (Администратор), user (Сотрудник), multi_guest (Мульти-гость), guest (Гость)
• status.title: max 50 characters
• status.away_message: max 1024 characters
• limit: max 50
• Pagination: cursor-based (limit + cursor)

Endpoints

| Method | Path | Description | |--------|------|-------------| | 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 | Удаление статуса сотрудника |

If unsure how to complete a task, read the corresponding file from references/.