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.

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

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

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

Workflows

Получить сотрудника по ID

1. Получи информацию о сотруднике:

``bash pachca users get <ID> ``

Возвращает все поля, включая customproperties, userstatus, list_tags.

Массовое создание сотрудников с тегами

1. Создай тег (если нужен):

``bash pachca group-tags create --name="Backend" ``

1. Для каждого сотрудника: создай аккаунт с тегами:

``bash pachca users create --first-name="Иван" --last-name="Петров" --email="[email protected]" --list-tags='[{"name":"Backend"}]' ` > Теги назначаются через поле list_tags` в теле запроса

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

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

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

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

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

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

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

``bash pachca users create --email="[email protected]" --role=guest --chat-ids='[12345]' ` > Для роли guest chatids обязателен и должен содержать ровно один чат. Нарушение (не передан, пусто, больше одного, чат не существует, архивный или нет прав) → 400 с элементом errors, где key — chatids`.

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

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

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

``bash pachca users list --query=Иван ``

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

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

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

``bash pachca users create --email="[email protected]" --first-name="Иван" --last-name="Петров" ``

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

``bash pachca members add <chatid> --member-ids='[<userid>]' ``

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

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

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

Offboarding сотрудника

1. Заблокировать доступ:

``bash pachca users update <ID> --suspended ``

1. Опционально: удалить аккаунт полностью:

``bash pachca users delete <ID> --force ``

Приостановка (suspended) сохраняет данные, удаление — необратимо.

Получить всех сотрудников тега/департамента

1. Найди тег по названию, возьми id:

``bash pachca group-tags list --names='["Backend"]' ` > Фильтр names` — серверная фильтрация по названию тега

1. Получи всех участников тега:

``bash pachca group-tags list-users <tag_id> --all ``

Управление статусом сотрудника

1. Получить текущий статус:

``bash pachca users get-status <user_id> ``

1. Установить статус:

``bash pachca users update-status <userid> --emoji="🏖️" --title="В отпуске" --is-away ` > isaway: true — режим «Нет на месте». away_message` — макс 1024 символа

1. Удалить статус:

``bash pachca users remove-status <user_id> --force ``

Загрузить аватар сотрудника

1. Загрузи аватар сотруднику:

``bash pachca users update-avatar <userid> --file=<путьк_файлу> `` > Требует прав администратора. Файл передается в формате multipart/form-data

Удалить аватар сотрудника

1. Удали аватар сотрудника:

``bash 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

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