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

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

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 update-avatar <ID> --file=<путь_к_файлу>
   

   Файл передается в формате multipart/form-data: jpg, jpeg, png или gif. У личного чата и треда аватара нет — ответ 403

2. Чтобы убрать аватар, удали его:

   pachca chats remove-avatar <ID> --force
   

Доступно тому же, кто может менять название чата. Ссылка на аватар приходит в поле avatar_url чата.

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

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	Архивация чата
PUT	/chats/{id}/avatar	Загрузка аватара чата
DELETE	/chats/{id}/avatar	Удаление аватара чата
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	Разархивация чата
PUT	/chats/{id}/unread	Отметка чата непрочитанным
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/.