Pachca Messages

pachca-messages

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 --token $PACHCA_TOKEN

Or set the PACHCA_TOKEN environment variable:

export PACHCA_TOKEN= npx -y @pachca/cli

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.

1. If no profile is configured — ask for a token and use --token:

npx -y @pachca/cli auth status --token $PACHCA_TOKEN

1. If you don't know the parameters — run pachca --help.

Workflows

Найти чат по имени и отправить сообщение

1. Найди чат по названию через поиск:

``bash pachca search list-chats --query="название" ` > Если результатов несколько — выбери наиболее подходящий по name`

1. Отправь сообщение в найденный чат:

``bash pachca messages create --entity-id= --content="Текст сообщения" ``

> entity_type по умолчанию "discussion", можно не указывать.

Отправить сообщение в канал или беседу (если chat_id известен)

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

``bash pachca messages create --entity-id= --content="Текст сообщения" ``

> "entity_type": "discussion" используется по умолчанию, можно не указывать

Отправить личное сообщение пользователю

1. Определи user_id получателя:

``bash pachca search list-users --query="имя" `` > Или возьми user_id из контекста (вебхук, предыдущий запрос)

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

``bash pachca messages create --entity-type=user --entity-id= --content="Привет!" ``

> Создавать чат не требуется — он создаётся автоматически

Ответить в тред (комментарий к сообщению)

1. Получи или создай тред, возьми thread.id из ответа:

``bash pachca thread add `` > Если тред уже существует, вернётся существующий

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

``bash pachca messages create --entity-type=thread --entity-id= --content="Ответ в тред" ``

> skip_invite_mentions: true — не добавлять упомянутых пользователей в тред автоматически.

Отправить сообщение с кнопками

1. Сформируй массив buttons — массив строк, каждая строка — массив кнопок

> Каждая кнопка: {"text": "Текст"} + либо url (ссылка), либо data (callback)

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

``bash pachca messages create --entity-id= --content="Выбери действие" --buttons='[[{"text":"Подробнее","url":"https://example.com"},{"text":"Отлично!","data":"awesome"}]]' ``

> buttons — массив массивов (строки × кнопки). Максимум 100 кнопок, до 8 в строке. Кнопка с url открывает ссылку, с data — отправляет событие на вебхук.

Получить историю сообщений чата

1. Получи сообщения чата с пагинацией:

``bash pachca messages list --chat-id= ` > limit (1-50), cursor, sort[id]=asc или desc` (по умолчанию)

> Для сообщений треда используй chat_id треда (thread.chat_id). Пагинация cursor-based, не page-based.

Получить вложения из сообщения

1. Получи сообщение — в files[] каждый объект содержит url, name, file_type, size:

``bash pachca messages get ``

1. Скачай нужные файлы по files[].url

> Ссылка прямая, авторизация не требуется

> Вебхук о новом сообщении НЕ содержит вложений — поле files отсутствует. Всегда проверяй вложения через GET /messages/{id}.

Закрепить/открепить сообщение

1. Закрепить сообщение:

``bash pachca messages pin ``

1. Открепить сообщение:

``bash pachca messages unpin --force ``

> В чате может быть несколько закреплённых сообщений.

Подписаться на тред сообщения

1. Получи или создай тред, возьми chat_id из ответа:

``bash pachca thread add ``

1. Добавь бота в участники чата треда:

``bash pachca members add --member-ids='[]' ``

1. Теперь бот будет получать вебхук-события о новых сообщениях в этом треде

> POST /messages/{id}/thread идемпотентен — безопасно вызывать повторно.

Отредактировать сообщение

1. Обнови сообщение:

``bash pachca messages update --content="Обновлённый текст" ``

> Редактировать можно только свои сообщения (или от имени бота).

Изменить вложения сообщения

1. Получи текущие вложения из files[]:

``bash pachca messages get ` > Сохрани нужные объекты (key, name, file_type, size`)

1. Если нужно добавить новый файл — загрузи его:

``bash pachca files uploads ``

1. Обнови сообщение с новым массивом files:

``bash pachca messages update --files='[...]' ` > files` при редактировании — replace-all: присылаемый массив полностью заменяет текущие

> files: [] удаляет все вложения. Если поле files не передавать — вложения не меняются.

Удалить сообщение

1. Удали сообщение:

``bash pachca messages delete --force ``

Добавить реакцию на сообщение

1. Добавь реакцию:

``bash pachca reactions add --code="👍" ``

1. Убрать реакцию:

``bash pachca reactions remove --code="👍" --force ``

> code — emoji-символ, не его текстовое название.

Проверить, кто прочитал сообщение

1. Получи массив user_id прочитавших:

``bash pachca read-member list-readers ``

1. При необходимости сопоставь с именами сотрудников:

``bash pachca users list ``

Разослать уведомление нескольким пользователям

1. Определи список user_id получателей:

``bash pachca users list --all `` > Или получи user_id из тега — см. «Получить всех сотрудников тега/департамента»

1. Для каждого: отправь личное сообщение:

``bash pachca messages create --entity-type=user --entity-id= --content="Уведомление" `` > Для каждого получателя

> Соблюдай rate limit: ~4 req/sec для сообщений. Добавляй паузы при большом списке.

Limitations

• Rate limit: ~50 req/sec, messages ~4 req/sec per chat. On 429 — wait and retry.
• message.entity_type: allowed values — discussion (Беседа или канал), thread (Тред), user (Пользователь)
• message.display_avatar_url: max 255 characters
• message.display_name: max 255 characters
• limit: max — 50 (GET /messages), 50 (GET /messages/{id}/reactions), 300 (GET /messages/{id}/readmemberids), 50 (GET /threads)
• Pagination: cursor-based (limit + cursor)

Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /messages | Новое сообщение | | GET | /messages | Список сообщений чата | | GET | /messages/{id} | Информация о сообщении | | PUT | /messages/{id} | Редактирование сообщения | | DELETE | /messages/{id} | Удаление сообщения | | POST | /messages/{id}/linkpreviews | Unfurl (разворачивание ссылок) | | POST | /messages/{id}/pin | Закрепление сообщения | | DELETE | /messages/{id}/pin | Открепление сообщения | | POST | /messages/{id}/reactions | Добавление реакции | | DELETE | /messages/{id}/reactions | Удаление реакции | | GET | /messages/{id}/reactions | Список реакций | | GET | /messages/{id}/readmember_ids | Список прочитавших сообщение | | POST | /messages/{id}/thread | Новый тред | | GET | /threads | Список тредов | | GET | /threads/{id} | Информация о треде |

Advanced workflows

For advanced workflows, read the files in references/: references/reply-to-user-who-messaged-the-bot.md — Reply to user who messaged the bot references/send-message-with-files.md — Send message with files references/list-active-threads-in-a-time-window.md — List active threads in a time window references/mention-user.md — Mention user

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pachca
• Source: pachca/openapi
• License: MIT
• Homepage: https://dev.pachca.com

Install and usage instructions live in the source repository linked above.