pachca-chats

pachca-chats

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

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

Create a channel and invite participants

1. Create a channel with participants:

   pachca chats create --name="Новый канал" --channel --member-ids='[1,2,3]'
   

   "channel": true for a channel, false (default) for a conversation. Participants can be passed right away: member_ids and/or group_tag_ids

2. Or add participants later:

   pachca members add <chat_id> --member-ids='[1,2,3]'
   

channel — boolean, not a string. member_ids и group_tag_ids — optional when creating.

Rename or update a chat

1. Update the chat:

   pachca chats update <ID> --name="Новое название"
   

   Available fields: name, public

To change the participant list, use POST/DELETE /chats/{id}/members.

Set or remove a chat avatar

1. Upload an avatar for a conversation or channel:

   pachca chats update-avatar <ID> --file=<путь_к_файлу>
   

   The file is sent in multipart/form-data format: jpg, jpeg, png, or gif. A personal chat and a thread have no avatar — response 403

2. To remove the avatar, delete it:

   pachca chats remove-avatar <ID> --force
   

Available to the same person who can change the chat name. The avatar link comes in the field avatar_url of the chat.

Create a project conversation from a template

1. Create a conversation with participants from a tag:

   pachca chats create --name="Проект Alpha" --group-tag-ids='[42]' --member-ids='[186,187]'
   

2. Send a welcome message:

   pachca messages create --entity-id=<chat_id> --content="Добро пожаловать в проект!"
   

group_tag_ids during creation adds all tag participants at once.

Find active chats for a period

1. Get chats with activity after the specified date:

   pachca chats list --last-message-at-after=<дата> --all
   

   For a range, add --last-message-at-before. Date in ISO-8601 UTC+0

Find and archive inactive chats

1. Get chats without activity since the desired date:

   pachca chats list --last-message-at-before=<порог> --all
   

   Archived chats are not included in the output, so there is no need to filter out already archived ones. To get them along with active ones, add --archived and look at the field archived of each chat

2. For each chat: archive:

   pachca chats archive <ID>
   

   Check "channel": false — archiving channels may be undesirable

Export all chats in the space, including closed ones

1. Get the conversations and channels of the entire space, including private ones where the token owner is not a member:

   pachca chats list-company --all
   

   Both active and archived chats are returned. You can keep only one state using the flag --activity with the value active or archived. The method does not return personal conversations and threads

2. If the method responded 403 — the token does not have the scope company_chats:read, or the token owner is not the space owner, or the space does not have the "Corporation" plan. Then get the public chats with a regular list:

   pachca chats list --availability=public --archived --all
   

   Private chats where the token is not a participant will not be included in such a response

Every request to the space chat list is written to the audit log as company_chats_accessed.

Limitations

• Rate limit: ~50 req/sec. On 429 — wait and retry.
• chat.name: max 255 characters
• role: allowed values — admin (Admin), editor (Editor (available only for channels)), member (Member or subscriber)
• limit: max 50
• Pagination: cursor-based (limit + cursor)

Endpoints

Method	Path	Description
POST	/chats	New chat
GET	/chats	Chat list
POST	/chats/exports	Message export
GET	/chats/exports/{id}	Download export archive
GET	/chats/{id}	Chat info
PUT	/chats/{id}	Chat editing
PUT	/chats/{id}/archive	Chat archiving
PUT	/chats/{id}/avatar	Uploading a chat avatar
DELETE	/chats/{id}/avatar	Deleting a chat avatar
POST	/chats/{id}/group_tags	Adding tags
DELETE	/chats/{id}/group_tags/{tag_id}	Removing a tag
DELETE	/chats/{id}/leave	Leaving the chat
GET	/chats/{id}/members	Chat participant list
POST	/chats/{id}/members	Adding users
DELETE	/chats/{id}/members/{user_id}	Removing a user
PUT	/chats/{id}/members/{user_id}	Editing a role
PUT	/chats/{id}/unarchive	Unarchiving a chat
PUT	/chats/{id}/unread	Marking a chat as unread
GET	/company/chats	Space chat list

Advanced workflows

For advanced workflows, read the files in references/: references/archive-and-manage-chat.md — Archive and manage chat references/export-chat-history.md — Export chat history

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