pachca-messages

pachca-messages

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

If the user has a saved profile — check:
```
npx -y @pachca/cli auth status
```
If OK — run commands without --token.
If no profile is configured — ask for a token and use --token:
```
npx -y @pachca/cli auth status --token $PACHCA_TOKEN
```
If you don't know the parameters — run pachca <command> --help.

Workflows

Find a chat by name and send a message

Find the chat by name via search:
```
pachca search list-chats --query="название"
```
If there are several results — choose the most relevant one by name

Send the message to the found chat:

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

entity_type default "discussion", it can be omitted.

Send a message to a channel or conversation (if chat_id is known)

Send the message to the chat:

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

"entity_type": "discussion" is used by default, it can be omitted

Send a direct message to a user

Determine the user_id recipient:
```
pachca search list-users --query="имя"
```
Or take the user_id from the context (webhook, previous request)

Send the direct message:

pachca messages create --entity-type=user --entity-id=<user_id> --content="Привет!"

No need to create a chat — it is created automatically

Reply in a thread (a comment on a message)

Get or create a thread, take thread.id from the response:
```
pachca threads add <ID>
```
If the thread already exists, the existing one will be returned

Send the message to the thread:

pachca messages create --entity-type=thread --entity-id=<thread_id> --content="Ответ в тред"

skip_invite_mentions: true — do not add the mentioned users to the thread automatically.

Send a message with buttons

Build the array buttons — an array of rows, each row is an array of buttons

Each button: {"text": "Текст"} + either url (a link), or data (callback)

Send the message with buttons:

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

buttons — an array of arrays (rows × buttons). Maximum of 100 buttons, up to 8 per row. A button with url opens a link, with data — sends an event to the webhook.

Get the message history of a chat

Get the chat messages with pagination:
```
pachca messages list --chat-id=<chat_id>
```
limit (1-50), cursor, sort[id]=asc or desc (default)

For thread messages use chat_id of the thread (thread.chat_id). Pagination is cursor-based, not page-based.

Get attachments from a message

Get the message — in files[] each object contains url, name, file_type, size:
```
pachca messages get <ID>
```
Download the required files via files[].url

Direct link, authorization is not required

The webhook about a new message does NOT contain attachments — the field files is absent. Always check attachments via GET /messages/{id}.

Pin/unpin a message

Pin a message:
```
pachca messages pin <ID>
```
Unpin a message:
```
pachca messages unpin <ID> --force
```

A chat can have several pinned messages.

Subscribe to a message thread

Get or create a thread, take chat_id from the response:
```
pachca threads add <ID>
```

Add the bot to the thread chat participants:

pachca members add <thread_chat_id> --member-ids='[<bot_user_id>]'

Now the bot will receive webhook events about new messages in this thread

POST /messages/{id}/thread is idempotent — it is safe to call it repeatedly.

Edit a message

Update the message:

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

You can only edit your own messages (or on behalf of the bot).

Change message attachments

Get the current attachments from files[]:
```
pachca messages get <ID>
```
Save the needed objects (key, name, file_type, size)
If you need to add a new file — upload it:
```
pachca files uploads
```
Update the message with a new array of files:
```
pachca messages update <ID> --files='[...]'
```
files when editing — replace-all: the array you send completely replaces the current one

files: [] deletes all attachments. If the field files is not passed — attachments are not changed.

Delete a message

Delete the message:
```
pachca messages delete <ID> --force
```

Add a reaction to a message

Add a reaction:

pachca reactions add <ID> --code="👍"

Remove a reaction:

pachca reactions remove <ID> --code="👍" --force

code — an emoji character, not its text name.

Check who has read the message

Get the array of user_id who have read:
```
pachca read-member list-readers <ID>
```
If necessary, match with employee names:
```
pachca users list
```

Send a notification to several users

Determine the list of user_id recipients:
```
pachca users list --all
```
Or get user_id from the tag — see "Get all employees of a tag/department"

For each one: send a personal message:

pachca messages create --entity-type=user --entity-id=<user_id> --content="Уведомление"

For each recipient

Observe the rate limit: ~4 req/sec for messages. Add pauses for a large list.

Send a message later or on a schedule

Find the chat you need to write to:

pachca search list-chats --query="название"

Create a scheduled message: schedule.start_date — when to send, schedule.repetition.interval — how to repeat (once, if once):
```
pachca drafts create --entity-type=discussion --entity-id=<chat_id> --content="Текст" --schedule='{"start_date":"2026-09-17T09:00:00Z","repetition":{"interval":"once"}}'
```
Time without an offset is considered UTC: convert the employee's local time yourself or send it with an offset. Repeat by days of the week — interval: "weekly" и days (0 — Sunday). In the response next_send_at — the nearest send time, check against it.
To cancel the send — delete the scheduled message:
```
pachca drafts delete <ID>
```
There is no other way to cancel: you cannot remove the schedule by editing

The method is unavailable to bot tokens — scopes drafts:read и drafts:write are issued only to people. Without schedule the same method creates an ordinary draft: it will not go anywhere, but will wait for a person in the interface. There can be only one ordinary draft in a chat; a repeat response will return 409, while there can be up to 50 scheduled messages per chat.

Limitations

Rate limit: ~50 req/sec, messages ~4 req/sec per chat. On 429 — wait and retry.
draft.entity_type: allowed values — discussion (Conversation or channel), thread (Thread), user (User)
draft.schedule.repetition.interval: allowed values — once (Once), daily (Every day), weekly (Every week), monthly (Every month), every_2_months (Once every two months), every_3_months (Once every three months), every_4_months (Once every four months), every_6_months (Once every six months), yearly (Once a year)
message.entity_type: allowed values — discussion (Conversation or channel), thread (Thread), user (User)
message.display_avatar_url: max 255 characters
message.display_name: max 255 characters
limit: max — 50 (GET /drafts), 50 (GET /messages), 50 (GET /messages/{id}/reactions), 300 (GET /messages/{id}/read_member_ids), 50 (GET /threads)
Pagination: cursor-based (limit + cursor)

Endpoints

Method	Path	Description
POST	/direct_url	File upload
POST	/drafts	New draft
GET	/drafts	List of drafts
GET	/drafts/{id}	Draft information
PUT	/drafts/{id}	Editing a draft
DELETE	/drafts/{id}	Deleting a draft
GET	/files/{id}	Downloading a file
POST	/messages	New message
GET	/messages	List of chat messages
GET	/messages/{id}	Message information
PUT	/messages/{id}	Editing a message
DELETE	/messages/{id}	Deleting a message
POST	/messages/{id}/link_previews	Unfurl (link expansion)
POST	/messages/{id}/pin	Pinning a message
DELETE	/messages/{id}/pin	Unpinning a message
POST	/messages/{id}/reactions	Adding a reaction
DELETE	/messages/{id}/reactions	Deleting a reaction
GET	/messages/{id}/reactions	List of reactions
GET	/messages/{id}/read_member_ids	List of those who read the message
POST	/messages/{id}/thread	New thread
POST	/threads	New standalone thread
GET	/threads	List of threads
GET	/threads/{id}	Thread information
POST	/uploads	Getting the signature, key and other parameters

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