---
slug: "pachca"
name: "Пачка API"
vendor: "Пачка"
industry: "communications"
docsUrl: "https://dev.pachca.com/"
version: 2
updatedAt: "2026-10-24"
---

# Пачка API

Отрасль: Связь и уведомления. Актуально на 2026-10-24.

REST API корпоративного мессенджера Пачка: отправка и редактирование сообщений, чаты и каналы, треды, участники, сотрудники, реакции, напоминания, поиск, загрузка файлов, боты и вебхуки. Работает от имени пользователя (персональный токен) или бота (токен бота). У API есть официальная OpenAPI-спецификация, SDK для нескольких языков, CLI и документация в формате llms.txt.

## Сценарии

### Отправить уведомление в канал от бота

Новые заказы, ошибки сервера, отчёты — в рабочий канал команды.

1. Создай бота в разделе «Автоматизации» и возьми его токен; передавай в заголовке Authorization: Bearer <token>. Добавь бота в нужный канал (или используй открытый канал).
2. Узнай ID канала: GET /chats — у каждого чата есть id.
3. Отправь сообщение: POST /messages с message.entity_id — ID канала и message.content — текстом. Можно добавить message.buttons (до 8 кнопок в строке) и подменить имя и аватар отправителя через display_name и display_avatar_url.
4. Ответ приходит в объекте data с id сообщения. Чтобы обновить сообщение (например, статус процесса), вызови PUT /messages/{id}.
5. Лимит — примерно 4 сообщения в секунду в один чат. При 429 ответ приходит текстом, а не JSON, с заголовком Retry-After — жди не меньше указанного.

```bash
curl -X POST https://api.pachca.com/api/shared/v1/messages \
  -H "Authorization: Bearer $PACHCA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "message": {
          "entity_id": 334,
          "content": "Новый заказ №1042 на 15 000 ₽",
          "display_name": "Магазин",
          "buttons": [[{"text": "Открыть заказ", "url": "https://example.ru/admin/orders/1042"}]]
        }
      }'
```

### Написать сотруднику в личные сообщения

Персональное уведомление: назначена задача, пришёл ответ клиента, нужно подтверждение.

1. Найди сотрудника: GET /users с query — именем, фамилией или email. Приостановленные сотрудники отмечены полем suspended.
2. Отправь сообщение: POST /messages с message.entity_type = user и message.entity_id — ID сотрудника.
3. Упомянуть коллегу в тексте можно через @nickname или <@user_id>.

```bash
curl -G https://api.pachca.com/api/shared/v1/users \
  -H "Authorization: Bearer $PACHCA_TOKEN" \
  --data-urlencode 'query=ivan@example.ru'

curl -X POST https://api.pachca.com/api/shared/v1/messages \
  -H "Authorization: Bearer $PACHCA_TOKEN" -H 'Content-Type: application/json' \
  -d '{"message": {"entity_type": "user", "entity_id": 12345, "content": "Тебе назначена задача: проверить заказ №1042"}}'
```

### Создать канал и добавить участников

Под новый проект, клиента или инцидент — отдельный канал с нужными людьми.

1. Создай чат: POST /chats с chat.name и chat.member_ids. Для канала передай chat.channel = true, для открытого доступа — chat.public = true. Владельцем станет владелец токена.
2. Добавь участников позже: POST /chats/{id}/members с member_ids. Чтобы не появлялось системное сообщение о добавлении, передай silent = true.
3. ID сотрудников бери из GET /users.

```bash
curl -X POST https://api.pachca.com/api/shared/v1/chats \
  -H "Authorization: Bearer $PACHCA_TOKEN" -H 'Content-Type: application/json' \
  -d '{"chat": {"name": "Инцидент 24.10: оплата не проходит", "member_ids": [12345, 12346], "channel": false}}'
```

### Поставить напоминание сотруднику

Создавать напоминания из своей системы: перезвонить клиенту, подготовить отчёт.

1. Создай напоминание: POST /tasks с task.kind (тип напоминания), task.content, task.due_at в ISO-8601 и task.performer_ids — ответственными. Время без смещения считается UTC — передавай часовой пояс явно.
2. Важность задаёт task.priority: 1 — обычная, 2 — важно, 3 — очень важно. Привязать напоминание к чату можно через task.chat_id.
3. Для напоминания на весь день передай task.all_day = true.

```bash
curl -X POST https://api.pachca.com/api/shared/v1/tasks \
  -H "Authorization: Bearer $PACHCA_TOKEN" -H 'Content-Type: application/json' \
  -d '{"task": {"kind": "call", "content": "Перезвонить Ивану Петрову по заказу №1042", "due_at": "2026-10-25T11:00:00+03:00", "priority": 2, "performer_ids": [12345]}}'
```

### Отвечать на сообщения через вебхук бота

Бот слушает канал и реагирует: подтверждает получение, отвечает в треде.

1. В настройках бота включи исходящий вебхук и укажи адрес своего обработчика. Пачка присылает события POST-запросом.
2. Проверяй подпись: заголовок Pachca-Signature — HMAC-SHA256 от тела запроса с ключом Signing secret бота, в hex. Поле webhook_timestamp должно отличаться от текущего времени не больше чем на минуту.
3. Отметь сообщение реакцией: POST /messages/{id}/reactions с code — символом эмодзи (записи вида :+1: отклоняются).
4. Ответь в треде: POST /messages с message.entity_type = thread и entity_id треда (тред создаётся через POST /threads) или ответом в ленте через message.parent_message_id.

```javascript
import crypto from "node:crypto";

// Express: app.post("/pachca/webhook", express.raw({ type: "*/*" }), handler)
function isValid(rawBody, headers, secret) {
  const signature = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  if (signature !== headers["pachca-signature"]) return false;
  const { webhook_timestamp } = JSON.parse(rawBody);
  return Math.abs(Date.now() / 1000 - webhook_timestamp) < 60;
}
```

## Базовые URL

- Боевой: `https://api.pachca.com/api/shared/v1`

## Авторизация

Тип: Bearer-токен

Токен передаётся в заголовке `Authorization: Bearer <token>`. Два типа токенов:

- **Персональный** — действует от имени пользователя и видит те же чаты, что он в интерфейсе. Выпускается в разделе «Автоматизации» > «API» (бессрочный, показывается один раз) или выдаётся при входе через CLI `pachca auth login` (живёт час и продлевается автоматически).
- **Токен бота** — действует от имени бота: все открытые каналы плюс закрытые чаты и треды, куда бот добавлен.

Почти каждый метод требует определённого скоупа токена; скоупы не расширяют круг доступных данных. Владелец пространства может ограничить, кто создаёт токены.

```
curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message": {
    "entity_id": 334,
    "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)"
  }
}'
```

## Методы

### POST /messages — Новое сообщение

Отправляет сообщение в беседу или канал, личное сообщение сотруднику или комментарий в тред.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `message.entity_type` | body | string | нет | discussion (беседа или канал, по умолчанию), thread (тред), user (пользователь) |
| `message.entity_id` | body | integer | да | ID беседы/канала, треда или сотрудника |
| `message.content` | body | string | да | Текст; упоминания @nickname или <@user_id> |
| `message.files` | body | array | нет | Прикрепляемые файлы |
| `message.buttons` | body | array | нет | Строки кнопок: до 100 кнопок, до 8 в строке |
| `message.parent_message_id` | body | integer | нет | Ответ на сообщение в ленте чата (не в треде) |
| `message.display_avatar_url` | body | string | нет | Аватар отправителя для этого сообщения (только токен бота) |
| `message.display_name` | body | string | нет | Имя отправителя для этого сообщения (только токен бота) |
| `message.skip_invite_mentions` | body | boolean | нет | Не добавлять упомянутых в тред |
| `link_preview` | body | boolean | нет | Показывать предпросмотр первой ссылки |

### GET /messages — Список сообщений чата

Сообщения приходят от новых к старым.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `chat_id` | query | integer | да | ID чата (беседа, канал, диалог или чат треда) |
| `sort` | query | string | нет | Поле сортировки |
| `order` | query | string | нет | Направление сортировки |
| `limit` | query | integer | нет | Количество записей за запрос |
| `cursor` | query | string | нет | Курсор из meta.paginate.next_page или meta.paginate.prev_page |

### PUT /messages/{id} — Редактирование сообщения

Меняет текст, файлы и кнопки отправленного сообщения; в интерфейсе появится пометка о правке.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id` | path | integer | да | ID сообщения |
| `message.content` | body | string | нет | Текст сообщения |
| `message.files` | body | array | нет | Файлы |
| `message.buttons` | body | array | нет | Кнопки |

### POST /messages/{id}/reactions — Добавить реакцию

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id` | path | integer | да | ID сообщения |
| `code` | body | string | да | Символ эмодзи; записи вроде +1 или :+1: отклоняются |
| `name` | body | string | нет | Имя кастомного эмодзи |

### POST /chats — Новый чат

Создаёт беседу или канал; владелец токена становится владельцем чата.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `chat.name` | body | string | да | Название |
| `chat.member_ids` | body | array | нет | ID пользователей-участников |
| `chat.group_tag_ids` | body | array | нет | ID тегов-участников |
| `chat.channel` | body | boolean | нет | Создать канал |
| `chat.public` | body | boolean | нет | Открытый доступ |

### GET /chats — Список чатов

По умолчанию — беседы, каналы и личные переписки владельца токена; с `availability=public` — все открытые.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `availability` | query | string | нет | Выборка чатов по доступности |
| `archived` | query | boolean | нет | Добавить архивные чаты |
| `personal` | query | boolean | нет | Только личные или только групповые |
| `last_message_at_after` | query | string | нет | Последнее сообщение позже даты (ISO-8601) |
| `last_message_at_before` | query | string | нет | Последнее сообщение раньше даты (ISO-8601) |
| `sort` | query | string | нет | Поле сортировки |
| `order` | query | string | нет | Направление сортировки |
| `limit` | query | integer | нет | Количество записей |
| `cursor` | query | string | нет | Курсор пагинации |

### POST /chats/{id}/members — Добавить участников

Добавляет сотрудников и ботов в беседу, канал или тред.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id` | path | integer | да | ID чата |
| `member_ids` | body | array | да | ID пользователей |
| `silent` | body | boolean | нет | Не создавать системное сообщение о добавлении |

### GET /users — Список сотрудников

Все сотрудники пространства, кроме удалённых; приостановленные отмечены полем `suspended`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `query` | query | string | нет | Поиск по имени, фамилии, email и др. |
| `limit` | query | integer | нет | Количество записей |
| `cursor` | query | string | нет | Курсор пагинации |

### GET /profile — Свой профиль

Карточка владельца токена (для токена бота — карточка бота). Параметров нет.

### GET /search/messages — Поиск сообщений

Ищет по тексту сообщений и именам файлов только в чатах владельца токена.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `query` | query | string | нет | Текст запроса |
| `chat_ids` | query | array | нет | Фильтр по чатам |
| `user_ids` | query | array | нет | Фильтр по авторам |
| `created_from` | query | string | нет | Дата создания от |
| `created_to` | query | string | нет | Дата создания до |
| `active` | query | boolean | нет | Фильтр по активности чата |
| `limit` | query | integer | нет | Количество результатов |
| `cursor` | query | string | нет | Курсор из meta.paginate.next_page |

### POST /tasks — Новое напоминание

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `task.kind` | body | string | да | Тип напоминания |
| `task.content` | body | string | нет | Описание |
| `task.due_at` | body | string | нет | Срок (ISO-8601); время без смещения считается UTC |
| `task.priority` | body | integer | нет | 1, 2 (важно) или 3 (очень важно) |
| `task.performer_ids` | body | array | нет | Ответственные |
| `task.chat_id` | body | integer | нет | Привязка к чату |
| `task.all_day` | body | boolean | нет | На весь день |

### POST /threads — Новый самостоятельный тред

Создаёт тред, не привязанный к сообщению.

Пример ответа:

```json
{"data": {"id": 265142, "chat_id": 2637266155, "message_id": null, "message_chat_id": null, "updated_at": "2023-02-01T19:20:47.204Z"}}
```

### POST /uploads — Параметры загрузки файла

Первый шаг загрузки: возвращает адрес хранилища и подписанные поля формы. Полученный ключ файла затем передают в `message.files`.

## Нюансы

- Ответы на создание оборачиваются в объект `data`; пагинация — курсорная, курсор в `meta.paginate.next_page`.
- Лимиты частоты возвращают `429` с текстом `text/plain`, а не JSON, и заголовком `Retry-After` — ждать нужно не меньше указанного.
- Превышение суточного предела сообщений в один чат приостанавливает отправку на час, и каждая попытка во время паузы удваивает её (до 24 часов).
- При частых `429` без паузы токен может быть заблокирован на час (порог около 22 000 отправок в час).
- `403` может прийти в двух видах: `OAuthError` с `insufficient_scope` (у токена нет скоупа) или `ApiError` (запрет бизнес-логики).
- Исходящие вебхуки подписываются HMAC-SHA256 от тела запроса в заголовке `Pachca-Signature` (ключ — Signing secret бота); поле `webhook_timestamp` стоит проверять на расхождение не больше минуты. IP Пачки: `37.200.70.177`.
- Документация доступна для LLM: `https://dev.pachca.com/llms.txt` и `llms-full.txt`.

## Примеры кода

### Проверка подписи вебхука на Node.js

```javascript
const signature = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (signature !== request.headers['pachca-signature']) {
    throw "Invalid signature"
}
```

## Ошибки

| Код | Описание |
|---|---|
| `400` | Неприемлемый запрос, часто нет обязательного параметра |
| `401` | Недействительный токен доступа |
| `402` | Работа пространства приостановлена: израсходован лимит сообщений тарифа |
| `403` | У токена нет прав на запрос |
| `404` | Ресурс не существует |
| `409` | Объект с такими данными уже существует |
| `410` | Ресурс больше не доступен |
| `422` | Правила сервиса не позволяют обработать запрос |
| `429` | Слишком много запросов |

## Ограничения

- Входящие вебхуки — ~10 запросов в секунду на идентификатор вебхука.
- Отправка сообщений (`POST /messages`) — ~4 запроса в секунду на каждый `entity_id` и не больше 30 запросов за 5 секунд по всем адресатам.
- Чтение сообщений — ~10 запросов в секунду на токен.
- Остальные методы — ~50 запросов в секунду на токен.
- `GET /webhooks/events` — ~5 запросов за 2 секунды.
- `GET /company/chats` и `GET /company/bots` — ~30 запросов в минуту.
- Сообщения в один чат — 7 500 за скользящие 24 часа на пару «отправитель и чат».
- Кнопки — до 100 на сообщение, до 8 в строке.

## Источники

- [OpenAPI-спецификация (GitHub)](https://github.com/pachca/openapi/blob/main/packages/spec/openapi.yaml)
- [Авторизация](https://dev.pachca.com/api/authorization)
- [Лимиты](https://dev.pachca.com/api/limits)
- [Ошибки](https://dev.pachca.com/api/errors)
- [Новое сообщение](https://dev.pachca.com/api/messages/create)
- [Обработка вебхуков](https://dev.pachca.com/guides/webhook/handler)
- [llms.txt](https://dev.pachca.com/llms.txt)

---

Если этого недостаточно — официальная документация: https://dev.pachca.com/
JSON: https://mcp-everything.ru/api/integrations/pachca. MCP: https://mcp-everything.ru/mcp