pachca-users

pachca-users

Quick start

Ask the user for a Pachca token (bot: the API tab of the bot in Integrations → Bots, user: Integrations → 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

If the user has a saved profile — check:
```
npx -y @pachca/cli auth status
```
If OK — run commands without --token.
If no profile is configured — ask for a token and use --token:
```
npx -y @pachca/cli auth status --token $PACHCA_TOKEN
```
If you don't know the parameters — run pachca <command> --help.

Workflows

Get an employee by ID

Get information about the employee:
```
pachca users get <ID>
```

Returns all fields, including custom_properties, user_status, list_tags.

Bulk creation of employees with tags

Create a tag (if needed):

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

For each employee: create an account with tags:

pachca users create --first-name="Иван" --last-name="Петров" --email="ivan@example.com" --list-tags='[{"name":"Backend"}]'

Tags are assigned via the field list_tags in the request body

Or update an existing one:

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

Creation is available only to administrators and owners (not bots). There is no separate endpoint to "add a user to a tag".

Create a guest in a chat

Choose the active chat to add the guest to — find out its ID:
```
pachca chats list
```
The chat must be active (not archived) and belong to your company. The token must have the right to add participants to it.
Create a guest: role guest and exactly one chat in --chat-ids:
```
pachca users create --email="guest@example.com" --role=guest --chat-ids='[12345]'
```
For the role guest chat_ids is required and must contain exactly one chat. Violation (not passed, empty, more than one, chat does not exist, archived, or no permissions) → 400 with the element errors, where key — chat_ids.

For the other roles, chat_ids is optional — you can add to several chats at once. Creation is available only to administrators and owners (not bots).

Find an employee by name or email

Search by name/email (partial match):
```
pachca users list --query=Иван
```

Cursor-based pagination: limit и cursor from meta. For an exact email — iterate through the pages.

Onboarding a new employee

Create an account:

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

Add to the required channels:

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

Send a welcome message:

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

Step 1 requires an administrator/owner token. Steps 2-3 can be done by a bot.

Offboarding an employee

Block access:
```
pachca users update <ID> --suspended
```
Optional: delete the account completely:
```
pachca users delete <ID> --force
```

Suspension (suspended) preserves the data, deletion is irreversible.

Get all employees of a tag/department

Find a tag by name, take id:
```
pachca group-tags list --names='["Backend"]'
```
Filter names — server-side filtering by tag name

Get all tag members:

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

Employee status management

Get the current status:
```
pachca users get-status <user_id>
```

Set the status:

pachca users update-status <user_id> --emoji="🏖️" --title="В отпуске" --is-away

is_away: true — “Away” mode. away_message — max 1024 characters

Delete the status:

pachca users remove-status <user_id> --force

Upload an employee avatar

Upload an avatar for the employee:
```
pachca users update-avatar <user_id> --file=<путь_к_файлу>
```
Requires administrator rights. The file is sent in multipart/form-data format

Delete an employee avatar

Delete the employee's avatar:
```
pachca users remove-avatar <user_id> --force
```
Requires administrator rights

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 (Administrator), user (Employee), multi_guest (Multi-guest), 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	New tag
GET	/group_tags	List of tags
GET	/group_tags/{id}	Tag information
PUT	/group_tags/{id}	Editing a tag
DELETE	/group_tags/{id}	Deleting a tag
GET	/group_tags/{id}/users	List of tag employees
POST	/users	New employee
GET	/users	List of employees
GET	/users/{id}	Employee information
PUT	/users/{id}	Editing an employee
DELETE	/users/{id}	Deleting an employee
PUT	/users/{user_id}/avatar	Uploading an employee avatar
DELETE	/users/{user_id}/avatar	Deleting an employee avatar
GET	/users/{user_id}/status	Employee status
PUT	/users/{user_id}/status	New employee status
DELETE	/users/{user_id}/status	Deleting an employee status

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