pachca-chats

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

Создать канал и пригласить участников

1. Создай канал с участниками:

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

   "channel": true для канала, false (по умолчанию) для беседы. Участников можно передать сразу: member_ids и/или group_tag_ids

2. Или добавь участников позже:

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

channel — boolean, не строка. member_ids и group_tag_ids — опциональны при создании.

Переименовать или обновить чат

1. Обнови чат:

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

   Доступные поля: name, public

Для изменения состава участников используй POST/DELETE /chats/{id}/members.

Создать проектную беседу из шаблона

1. Создай беседу с участниками из тега:

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

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

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

group_tag_ids при создании добавляет всех участников тега сразу.

Найти активные чаты за период

1. Получи чаты с активностью после указанной даты:

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

   Для диапазона добавь --last-message-at-before. Дата в ISO-8601 UTC+0

Найти и заархивировать неактивные чаты

1. Получи чаты без активности с нужной даты:

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

   Архивные чаты в выдачу не попадают, поэтому отсеивать уже заархивированные не нужно. Чтобы получить их вместе с активными, добавь --archived и смотри поле archived каждого чата

2. Для каждого чата: архивируй:

   pachca chats archive <ID>
   

   Проверяй "channel": false — архивация каналов может быть нежелательной

Выгрузить все чаты пространства, включая закрытые

1. Получи беседы и каналы всего пространства, включая закрытые, где владелец токена не состоит:

   pachca chats list-company --all
   

   Возвращаются и активные, и архивные чаты. Оставить одно состояние можно флагом --activity со значением active или archived. Личные переписки и треды метод не отдаёт

2. Если метод ответил 403 — у токена нет скоупа company_chats:read, либо владелец токена не владелец пространства, либо у пространства нет тарифа «Корпорация». Тогда возьми открытые чаты обычным списком:

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

   Закрытые чаты, где токен не участник, в такую выдачу не попадут

Каждый запрос к списку чатов пространства пишется в журнал аудита как company_chats_accessed.

Limitations

• Rate limit: ~50 req/sec. On 429 — wait and retry.
• chat.name: max 255 characters
• role: allowed values — admin (Админ), editor (Редактор (доступно только для каналов)), member (Участник или подписчик)
• limit: max 50
• Pagination: cursor-based (limit + cursor)

Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /chats | Новый чат | | GET | /chats | Список чатов | | POST | /chats/exports | Экспорт сообщений | | GET | /chats/exports/{id} | Скачать архив экспорта | | GET | /chats/{id} | Информация о чате | | PUT | /chats/{id} | Редактирование чата | | PUT | /chats/{id}/archive | Архивация чата | | POST | /chats/{id}/group_tags | Добавление тегов | | DELETE | /chats/{id}/group_tags/{tag_id} | Исключение тега | | DELETE | /chats/{id}/leave | Выход из беседы или канала | | GET | /chats/{id}/members | Список участников чата | | POST | /chats/{id}/members | Добавление пользователей | | DELETE | /chats/{id}/members/{user_id} | Исключение пользователя | | PUT | /chats/{id}/members/{user_id} | Редактирование роли | | PUT | /chats/{id}/unarchive | Разархивация чата | | GET | /company/chats | Список чатов пространства |

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/.