Для разработчиков

Ресурсы и операции

В расширении Пачки каждый узел Pachca работает по модели Resource → Operation: вы выбираете ресурс (например, Message) и операцию над ним (например, Create).

Выбор ресурса в узле Pachca

Для каждого ресурса доступен свой набор операций.

Операции для ресурса Message

Список ресурсов

#РесурсОперацийОписаниеТолько v2
1Message8Сообщения: создание, редактирование, удаление, закрепление, unfurl
2Chat12Чаты: создание, обновление, аватар, архивация, экспорт, отметка непрочитанным
3Chat Member7Участники чата: добавление, удаление, роли, тегида
4User10Сотрудники: CRUD, аватар, статус
5Group Tag6Теги сотрудников: CRUD, список пользователей
6Thread4Треды: создание, получение, список
7Reaction3Реакции: создание, удаление, список
8Profile6Мой профиль: информация, аватар, статус
9OAuth1Информация о токенеда
10Reminder5Напоминания: полный CRUD
11Draft5Черновики и отложенные сообщения: полный CRUDда
12Bot21Боты: создание, получение, список, редактирование, удаление, аватар, вебхук, токены, ротация токена и секрета, события
13File2Загрузка файлов через S3, скачивание защищённых вложений
14Form2Модальные формы: показ формы и ответ на её отправку
15Custom Property1Дополнительные поля
16Read Member1Список прочитавших сообщениеда
17Search3Полнотекстовый поискда
18Security1Журнал безопасностида
19Important Message3Личный раздел «Важное»: список, добавление, удалениеда
20Workspace4Пространство: название и настройки, ссылка-приглашениеда
Для некоторых операций требуются скоупы, которые доступны только определённым ролям (администратор, владелец). При создании персонального токена отображаются только скоупы, доступные вашей роли. Подробнее — в разделе Авторизация.

Message

Сообщения: создание, получение, редактирование, удаление, закрепление, открепление и список закреплённых.

Ключевые параметры Create: Entity Type (Discussion, Thread или User), Entity ID (чат, тред или сотрудник), Content (текст, Markdown), Button Layout с кнопками, а в Additional Fields — Files, Parent Message ID и другие. Как задать кнопки — в разделе Кнопки в сообщениях.

Сортировка в Get Many: поле Sort со значением ID и поле Order (Ascending или Descending, по умолчанию Descending) определяют порядок выдачи сообщений.

Настройка Message → Get Many


Chat

Чаты: создание, получение, обновление, архивация и разархивация, отметка непрочитанным, аватар.

Create возвращает созданный чат и поля not_found_member_ids и not_found_group_tag_ids: идентификаторы из Member IDs, которых не удалось добавить в чат, и идентификаторы из Group Tag IDs, которых нет среди тегов пространства.

Сортировка в Get Many: поля Sort (ID или Last Message At) и Order (Ascending или Descending). Также доступны фильтры Availability, Last Message At After и Last Message At Before.

Get Many Workspace Chats отдаёт беседы и каналы всего пространства, включая закрытые, где владелец токена не состоит. Фильтр Activity оставляет только активные или только архивные. Доступно владельцу пространства на тарифе «Корпорация».

Update Avatar принимает бинарные данные из предыдущего узла, например HTTP Request или Read Binary File. В поле Input Binary Field укажите имя бинарного свойства, по умолчанию data.

Экспорт чата выполняется асинхронно: операция Request Export ставит задачу и сразу возвращает её идентификатор в id, а Download Export скачивает архив по этому номеру, когда он собран. Пока архив собирается, Download Export вместо ссылки возвращает ошибку с кодом export_file_not_found. О готовности может сообщить и вебхук на webhookUrl с тем же номером в export_id. Доступно владельцу на тарифе «Корпорация».


Chat Member

Управление участниками чата: добавление, удаление, изменение ролей, управление тегами.

В v1 эти операции были частью ресурса Chat. В v2 они выделены в отдельный ресурс Chat Member.

User

Сотрудники: полный CRUD, получение и управление статусом.


Group Tag

Теги (группы) сотрудников: создание, обновление, удаление, список пользователей. Как тег держит состав чата — в руководстве Теги.


Thread

Треды (комментарии к сообщениям): создание, получение, список.


Reaction

Реакции на сообщения: создание, удаление, список.


Profile

Профиль текущего пользователя: информация, статус, аватар.

Загрузка аватара: операция Update Avatar принимает бинарные данные из предыдущего узла (например, HTTP Request или Read Binary File). В поле Input Binary Field укажите имя бинарного свойства (по умолчанию data).


OAuth

Информация о текущем токене: скоупы, даты создания и последнего использования.

ОперацияAPI
Get InfoGETИнформация о токене

Reminder

Напоминания: полный CRUD. В JSON сценария ресурс записан значением task.

Типы напоминаний: call, email, event, meeting, reminder.


Draft

Черновики и отложенные сообщения: полный CRUD.

Отложенное сообщение создаётся полем Schedule у операции Create: в нём задаётся время первой отправки и правило повтора. Без Schedule получается обычный черновик, который никуда не уйдёт. Отменить отправку можно только операцией Delete.

Update снимает ответ на сообщение переключателем Clear Parent Message ID в Additional Fields: он отправляет parent_message_id: null и действует, даже если заполнено поле Parent Message ID.

Ресурс работает только с личным токеном. Скоупы drafts:read и drafts:write токенам ботов не выдаются, поэтому с учётными данными бота операции вернут 403.


Bot

Боты: создание, получение, список, редактирование, удаление, аватар, саморегистрация вебхука, токены бота и их права, ротация токена и секрета клиента, история, поток и удаление событий.

Update меняет настройки бота. Поле Webhook URL задаёт адрес исходящего вебхука, пустое поле оставляет прежний адрес. Источник входящего вебхука задаёт поле Kind в Additional Fields: значения Simple, Gitlab и Grafana включают входящий вебхук, если его не было, а None удаляет его. Адрес удалённого вебхука перестаёт работать, шаблон и настройки сбрасываются, а при следующем включении бот получает новый адрес.

В Update текст null в поле OAuth Client из Additional Fields выключает авторизацию от имени сотрудника: выданные сотрудниками авторизации отзываются, страница бота в витрине удаляется, а собственные токены бота продолжают работать.

Get Many Workspace Bots отдаёт всех ботов пространства, включая недоступных владельцу токена для редактирования. У таких ботов в webhook заполнены только name и nickname, остальные настройки приходят пустыми. Доступно владельцу пространства на тарифе «Корпорация».

Update Avatar принимает бинарные данные из предыдущего узла так же, как у ресурса Chat: в поле Input Binary Field укажите имя бинарного свойства, по умолчанию data.


File

Загрузка файлов через двухшаговый S3 upload и скачивание вложений, у которых нет прямой ссылки.

Get нужен, только когда url вложения ведёт не в хранилище, а на адрес API: так отдаются зашифрованные и защищённые безопасным контуром файлы. Остальные вложения скачиваются по ссылке из url без этой операции.

Подробнее — в разделе Продвинутые функции.


Form

Модальные формы (представления).

Submit Response нужен, только если у бота нет адреса вебхука и отправку формы он забирает из истории событий операцией Bot > Get Many Events или Get Stream, подробнее в разделе Ответ через историю событий. Отправку, которая пришла в Pachca Trigger, Пачка закрывает по ответу узла на вебхук. Узел отвечает сразу, поэтому форма закрывается, а показать сотруднику ошибки под полями из такого workflow нельзя.

Подробнее — в разделе Продвинутые функции и в документации форм.


Custom Property

Дополнительные поля пространства. Поле Entity Type выбирает, чьи поля вернуть: сотрудника (User) или напоминания (Reminder, в JSON сценария значение Task).


Read Member

Список пользователей, прочитавших сообщение.

ОперацияAPI
Get Many Read Member IDsGETСписок прочитавших сообщение

Полнотекстовый поиск по сообщениям, чатам и пользователям.

ОперацияAPI
Get Many ChatsGETПоиск чатов
Get Many MessagesGETПоиск сообщений
Get Many UsersGETПоиск сотрудников

Обязательный параметр: query — строка поиска.


Security

Журнал безопасности: действия сотрудников и ботов в пространстве. Доступно владельцу пространства на тарифе «Корпорация».

Фильтры в Additional Fields: Event Key, Actor ID, Actor Type, Entity ID, Entity Type, Start Time, End Time. Что в них указывать — в разделе Журнал безопасности.

Подробнее — в документации журнала аудита.


Important Message

Личный раздел «Важное» владельца токена: список, добавление и удаление сообщений.

Ресурс работает только с личным токеном. Скоупы important_messages:read и important_messages:write токенам ботов не выдаются, поэтому с учётными данными бота операции вернут 403. Отметка личная и в отличие от закрепления видна только самому сотруднику. Отмечено ли сообщение, показывает поле important в ответах о сообщениях.


Workspace

Пространство: название, владелец, тариф и настройки, а также ссылка-приглашение. В JSON сценария ресурс записан значением company.

Update, Get Invite Link и Reissue Invite Link доступны владельцу и администраторам. Update меняет название, показ личных данных и сквозные треды. Reissue Invite Link выпускает новую ссылку, и прежняя ссылка этого администратора сразу перестаёт работать.


Пагинация

Все операции Get Many поддерживают автоматическую курсорную пагинацию:

  • Return All = true — получить все результаты автоматически, переключаясь между страницами
  • Return All = false — получить не более Limit результатов (по умолчанию 50)

Limit не больше 50, у Search > Get Many Chats до 100, у Get Many Messages и Get Many Users в Search до 200, у Read Member до 300. Чтобы получить больше, включите Return All.

Return All и Limit для операции Get Many

n8n автоматически отправляет повторные запросы с курсором до получения всех данных.

Для операций со списками (Get Many) рекомендуется использовать Return All = false с разумным Limit, чтобы избежать долгих запросов при большом объёме данных.

Simplify

Операции получения данных (Get, Get Many) поддерживают переключатель Simplify (включён по умолчанию). Когда Simplify включён, из ответа API возвращаются только ключевые поля — остальные отбрасываются.

РесурсКлючевые поля
Messageid, entity_id, chat_id, content, user_id, created_at
Chatid, name, channel, public, member_ids, created_at
Userid, first_name, last_name, nickname, email, role, suspended
Reminderid, content, kind, status, priority, due_at, created_at
BotБоты: id и webhook, в котором лежат имя и никнейм. Токены в Get Many Tokens: id, name, scopes, created_at, last_used_at. События в Get Many Events: id, event_type, payload, created_at.
Group TagТеги: id, name, users_count. Сотрудники тега в Get Many Users: те же поля, что у User.
Reactioncode, name, user_id, created_at

У остальных ресурсов переключатель есть, но ответ приходит полностью. Выражения в следующих узлах, которые ссылаются на поля вне этого списка, при включённом Simplify получат пустые значения. Чтобы получить все поля ответа, выключите Simplify.

Simplify доступен только в v2. В v1 workflow всегда возвращают полный ответ API.

Поисковые выпадающие списки

Поиск чата по имени в поле Chat ID

Поля чата и сотрудника с режимом From list показывают список и ищут по названию или имени: начните вводить текст, и n8n покажет подходящие результаты из пространства.

ПолеЧто в списке
Chat ID в Message > Get Many, ID в операциях Chat и Chat MemberЧаты
ID и User ID в операциях User, User ID в Chat MemberСотрудники
Entity ID в Message > CreateЧаты при Entity Type = Discussion, сотрудники при User

Без введённого текста список приходит из методов GETСписок чатов и GETСписок сотрудников, с текстом — из GETПоиск чатов и GETПоиск сотрудников. Поэтому в списке только то, что доступно токену из Credentials, и токену нужны права на эти методы, например chats:read и search:chats для чатов. При Entity Type = Thread список пуст: укажите id треда в режиме By ID. Как найти идентификатор без списка — в разделе Где взять идентификаторы.

В полях чата и сотрудника, кроме Entity ID, есть и режим By URL: вставьте ссылку из веб-приложения, и узел возьмёт из неё id. Ссылку на чат копирует пункт Скопировать ссылку в меню чата: https://app.pachca.com/chats/12345. Ссылку на сотрудника копирует такой же пункт в меню его профиля: https://app.pachca.com/chats?user_id=12345.