Pachca

Pachca API

Pachca is a corporate messenger for teams. The REST API lets you automate communication workflows: send and manage messages, organize chats and channels, manage users and permissions, build interactive bots, handle file uploads, and react to real-time events via webhooks.

Base URL: https://api.pachca.com/api/shared/v1

Accessing Documentation

For detailed endpoint documentation, parameters, and response schemas, fetch /llms-full.txt — or, to avoid loading the whole file, pull just the endpoint you need with npx -y @pachca/cli api <METHOD> <path> --describe (or --spec / --docs; list all endpoints: npx -y @pachca/cli api ls).

CLI (recommended)

# Zero-install
npx -y @pachca/cli <command> --token <TOKEN>

# For regular use
npm install -g @pachca/cli && pachca auth login

Authentication

All requests require a Bearer token. With CLI, use --token flag or PACHCA_TOKEN env var.

For direct API calls, add the Authorization header:

Authorization: Bearer <access_token>

Token types and their permissions:

• Admin token — full access: manage users, tags, delete messages. Get it in Settings → Automations → API.
• Owner token — admin access plus audit events and data export (Corporation plan only).
• Bot token — send messages with custom display name/avatar, receive webhook events, manage webhook settings. Created per-bot in Settings → Automations.

Tokens are long-lived and do not expire. They can be reset by the admin/owner in Settings.

Capabilities

OAuth

• GET /oauth/token/info — Get token info

Chats

• POST /chats — Create chat
• GET /chats — List chats
• POST /chats/exports — Request export
• GET /chats/exports/{id} — Download export
• GET /chats/{id} — Get chat
• PUT /chats/{id} — Update chat
• PUT /chats/{id}/archive — Archive chat
• PUT /chats/{id}/unarchive — Unarchive chat
• GET /company/chats — List company chats

Profile

• GET /profile — Get profile
• PUT /profile/avatar — Update profile avatar
• DELETE /profile/avatar — Delete profile avatar
• GET /profile/status — Get status
• PUT /profile/status — Update status
• DELETE /profile/status — Delete status

Users

• POST /users — Create user
• GET /users — List users
• GET /users/{id} — Get user
• PUT /users/{id} — Update user
• DELETE /users/{id} — Delete user
• PUT /users/{user_id}/avatar — Update user avatar
• DELETE /users/{user_id}/avatar — Delete user avatar
• GET /users/{user_id}/status — Get user status
• PUT /users/{user_id}/status — Update user status
• DELETE /users/{user_id}/status — Delete user status

Group tags

• POST /group_tags — Create tag
• GET /group_tags — List tags
• GET /group_tags/{id} — Get tag
• PUT /group_tags/{id} — Update tag
• DELETE /group_tags/{id} — Delete tag
• GET /group_tags/{id}/users — Get tag users

Members

• POST /chats/{id}/group_tags — Add tags
• DELETE /chats/{id}/group_tags/{tag_id} — Remove tag
• DELETE /chats/{id}/leave — Leave chat
• GET /chats/{id}/members — List members
• POST /chats/{id}/members — Add members
• DELETE /chats/{id}/members/{user_id} — Remove member
• PUT /chats/{id}/members/{user_id} — Update member role

Threads

• POST /messages/{id}/thread — Create thread
• POST /threads — Create standalone thread
• GET /threads — List threads
• GET /threads/{id} — Get thread

Messages

• POST /messages — Create message
• GET /messages — List chat messages
• GET /messages/{id} — Get message
• PUT /messages/{id} — Update message
• DELETE /messages/{id} — Delete message
• POST /messages/{id}/link_previews — Unfurl
• POST /messages/{id}/pin — Pin message
• DELETE /messages/{id}/pin — Unpin message

Read members

• GET /messages/{id}/read_member_ids — List read members

Reactions

• POST /messages/{id}/reactions — Add reaction
• DELETE /messages/{id}/reactions — Remove reaction
• GET /messages/{id}/reactions — List reactions

Search

• GET /search/chats — Search chats
• GET /search/messages — Search messages
• GET /search/users — Search users

Tasks

• POST /tasks — Create task
• GET /tasks — List tasks
• GET /tasks/{id} — Get task
• PUT /tasks/{id} — Update task
• DELETE /tasks/{id} — Delete task

Views

• POST /views/open — Open view
• POST /views/{view_id}/submit_response — Submit view response

Bots

• POST /bot/recreate_token — Self recreate bot token
• PUT /bot/webhook — Self update bot webhook
• GET /bots — List bots
• POST /bots — Create bot
• GET /bots/{id} — Get bot
• PUT /bots/{id} — Update bot
• DELETE /bots/{id} — Delete bot
• POST /bots/{id}/recreate_token — Recreate bot token
• GET /company/bots — List company bots
• GET /webhooks/events — Get webhook events
• DELETE /webhooks/events/{id} — Delete webhook event

Security

• GET /audit_events — Get audit events

Custom Properties

• GET /custom_properties — List properties

Files

• POST /direct_url — Upload file
• POST /uploads — Get upload params

Common Workflows

CLI Quick Start

npx -y @pachca/cli <command> --token <TOKEN>

Find chat by name and send message

1. List all chats, find by name field: pachca chats list --all

   GET /chats does not support name search — paginate through all

2. Send message to the chat: pachca messages create --entity-id=<chat_id> --content="Hello"

Find active chats in a date range

1. List chats with activity after a date: pachca chats list --last-message-at-after=<date> --all

   Add --last-message-at-before for range. Date in ISO-8601 UTC

Set up a bot with outgoing webhook

1. Create bot in Pachca UI: Automations → Integrations → Webhook
2. Get access_token from bot API settings tab
3. Set Webhook URL to receive events

Show interactive form to user

1. Send message with button: pachca messages create --entity-id=<chat_id> --content="Fill the form" --buttons='[[{"text":"Open","data":"open_form"}]]'
2. On button click — receive webhook event with trigger_id
3. Open form immediately: pachca views open --type=modal --trigger-id=<trigger_id> --title="Request" --blocks='[...]'

   trigger_id expires in 3 seconds — prepare form object in advance

4. On form submit — receive webhook, process data

Constraints

Rate Limits

• Message send/edit/delete: ~4 req/sec per chat (burst: 30/sec for 5s)
• Message read: ~10 req/sec
• Other endpoints: ~50 req/sec
• Webhooks: ~4 req/sec per webhook ID
• On 429 response, respect the Retry-After header.

Pagination

• Cursor-based (preferred): use limit (1–50) and cursor parameters. Response includes meta.paginate with next_page, prev_page, has_next, has_prev.
• Use has_next / has_prev to detect end of data. Use prev_page to poll for new records "above" the list.
• Search endpoints (/search/users, /search/chats, /search/messages) return only next_page and total.
• Offset-based (legacy): use per (1–50) and page parameters.

Permissions

• User management, tag management, and message deletion require an admin token.
• Audit events and data export require an owner token and Corporation pricing plan.
• Link preview (unfurling) requires a dedicated unfurling bot token with whitelisted domains.
• POST /direct_url is the only endpoint that does not require authentication.

Error Handling

• 400 — validation error
• 401 — missing or invalid token
• 403 — insufficient permissions
• 404 — resource not found
• 429 — rate limited (check Retry-After)

Error response body: { "errors": [{ "key": "field", "value": "description" }] }

Guides

Detailed documentation on specific topics is available at:

• Быстрый старт — Первый запрос к API Пачки за 5 минут: получение персонального токена, проверка авторизации и отправка сообщения через cURL, Postman или официальный CLI
• AI агенты, Обзор — Готовность Пачки к AI-агентам: агент как участник тредов и способы подключения — llms.txt, CLI как основной путь, Agent Skills, OpenAPI, Arazzo, Context7
• AI агенты, Взаимодействие с агентом — Как агент в Пачке получает события через вебхук, собирает контекст треда, выполняет действия и отвечает. Реакция-индикатор и таймер agent-thinking
• AI агенты, Оформление ответов — Агент присылает отчёты, ревью и сводки в Markdown — Пачка рендерит .md оформленной карточкой: таблицы, чеклисты, подсветка кода, diff, диаграммы Mermaid. Файлы .html открываются просмотром прямо в переписке
• Треды — Треды в Пачке для разработчиков: сквозные и самостоятельные треды как уникальная особенность, создание у сообщения (POST /messages/{id}/thread) и без привязки к сообщению (POST /threads), отправка комментариев, добавление участников, видимость родительского чата, нюансы API и поля Message.thread/root_chat_id
• Боты, Обзор — Боты в Пачке: что это, типы ботов, доступность в чатах и подмена имени и аватара отправителя в сообщениях
• Боты, Создание и настройка — Как создать бота в Пачке: выбор типа, копирование токена, настройка имени и аватара, настройка доступов и вкладок вебхуков и API
• Боты, Доступы к чатам и сообщениям — Как бот получает доступ к закрытым каналам и беседам, тредам и личным сообщениям в Пачке
• Боты, Готовые примеры реализации — Открытые примеры ботов для Пачки: Welcome Bot для приветствия новых сотрудников, Review Bot для интеграции с GitHub Pull Requests и Unfurl-бот для предпросмотра ссылок
• Входящие вебхуки — Входящие вебхуки в Пачке: отправка сообщений от имени бота одним HTTP POST без API, шаблонизатор для форматирования, интеграции с CI/CD и мониторингом
• Исходящие вебхуки, Обзор — Исходящие вебхуки в Пачке: что это, как настроить и какие настройки доступны на вкладке Исходящий Webhook в боте
• Исходящие вебхуки, Настройка и типы событий — Настройки исходящих вебхуков Пачки и список доступных типов событий: сообщения, реакции, нажатия кнопок, заполнение форм, изменение участников чатов и пространства, отправка ссылок
• Исходящие вебхуки, Безопасность и обработчик — Безопасность исходящих вебхуков Пачки: подпись HMAC-SHA256, проверка timestamp, IP-адрес отправителя, примеры обработчика на TypeScript и Python, идемпотентная обработка и доставка
• Исходящие вебхуки, Поллинг — Поллинг исходящих вебхуков Пачки через SDK: получение новых событий без публичного webhook URL, дедупликация доставок и пример воркера для локальной разработки
• Кнопки в сообщениях — Интерактивные кнопки в сообщениях ботов Пачки: ссылки и действия, обработка нажатий через исходящий вебхук, открытие форм и переходы на внешние ресурсы
• Формы, Обзор — Модальные формы ботов в Пачке: поля ввода, списки, даты и кнопки, жизненный цикл представления — от нажатия кнопки до валидации и закрытия модального окна
• Формы, Блоки представления — 10 типов блоков представлений в формах ботов Пачки: заголовок, текст, поля ввода, выбор из списка, дата, кнопки. До 100 блоков в одном представлении
• Формы, Обработка форм — Обработка форм в Пачке: открытие представлений по trigger_id (3 секунды), приём результатов через исходящий вебхук или журнал событий, валидация полей и отображение ошибок
• Разворачивание ссылок — Unfurl в Пачке: превью ссылок внутренних сервисов прямо в чатах — бот ловит URL, подтягивает заголовок, описание, изображение и отправляет обратно в чат
• Экспорт сообщений — Экспорт сообщений из чатов Пачки: запрос архива за период до 45 дней, скачивание JSON-файлов, структура архива и ограничения по чатам. Тариф «Корпорация»
• DLP-система — DLP-система Пачки для защиты от утечек конфиденциальной информации: правила с условиями и действиями, приоритеты, контексты применения. Тариф «Корпорация»
• Журнал аудита событий — Журнал аудита событий Пачки для команд безопасности: структура записи, типы событий и состав деталей, фильтры и пагинация, хранение. Тариф «Корпорация»
• Права и роли — Как устроены права в API Пачки: роль в пространстве (Владелец, Администратор, Сотрудник, гости) и роль в чате (Создатель, Админ, Редактор, Участник, Подписчик), единственная точка их связи, видимость закрытых бесед и каналов, инвентаризация чатов и ботов пространства, управление чужими чатами и чаты уволенных сотрудников
• Форматирование текста — Какой markdown понимает Пачка в тексте сообщений, входящих вебхуках и блоках форм: жирный, курсив, зачёркнутый, ссылки, строчный код и блоки кода. Списки, цитаты и заголовки остаются обычным текстом.
• Сценарии — Пошаговые сценарии для типичных задач с API Пачки: какие методы вызывать и в каком порядке. Основа Agent Skills для AI-агентов и команды pachca guide в CLI
• CLI, Обзор — Официальный CLI для Pachca API: все методы API как команды терминала с автодополнением, типизированными флагами и интерактивными подсказками. Node.js 20+
• CLI, Установка — Установка @pachca/cli: глобально через npm или без установки через npx (для агентов и CI). Автодополнение, настройки по умолчанию, диагностика и обновление.
• CLI, Авторизация — Авторизация Pachca CLI: профили для нескольких токенов, приоритет источников токена, headless-режим для CI и агентов.
• CLI, Вывод — Форматы вывода Pachca CLI (table, json, yaml, csv), выбор колонок, плоский TSV-режим, пайпы и перенаправление, курсорная пагинация.
• CLI, Флаги и скрипты — Глобальные флаги Pachca CLI, сортировка, kebab-case, boolean-флаги, dry-run, деструктивные операции, exit codes, таксономия ошибок, переменные окружения, неинтерактивный режим.
• CLI, Сценарии — Готовые пошаговые сценарии Pachca CLI через pachca guide: поиск рецептов по задаче, последовательности команд с комментариями.
• CLI, Файлы — Загрузка файлов через Pachca CLI: pachca upload автоматически получает подпись и загружает на S3 одной командой.
• CLI, Прямые запросы — Команда pachca api: прямые HTTP-запросы к любому методу (поля -f/-F, инлайн JSON, stdin) и встроенный справочник по API (ls, --describe, --spec, --docs) прямо в терминале, без сайта документации.
• CLI, Команды — Справочник всех команд Pachca CLI: каждый метод API как команда, паттерн pachca [секция] [действие] [--флаги]. Параметры каждой команды — по клику.
• SDK, Обзор — Типизированные SDK для Pachca API на TypeScript, Python, Go, Kotlin, Swift и C#: автодополнение, retry и пагинация. Или свой клиент через OpenAPI-генератор
• SDK, TypeScript — Типизированный клиент для Pachca API на TypeScript: Node.js 18+ или любое окружение с fetch. Автодополнение, автопагинация и retry. npm-пакет @pachca/sdk
• SDK, Python — Асинхронный типизированный клиент для Pachca API на Python: httpx, type hints, dataclass-модели, автопагинация и retry. PyPI-пакет, требуется Python 3.10+
• SDK, Go — Типизированный клиент для Pachca API на Go: синхронный, с context.Context, автопагинацией и обработкой retry. Установка через go get, требуется Go 1.24+
• SDK, Kotlin — Типизированный клиент для Pachca API на Kotlin: Ktor с корутинами, kotlinx.serialization и встроенным retry. JitPack, требуется Kotlin 2.2+ и Java 11+
• SDK, Swift — Типизированный клиент для Pachca API на Swift: URLSession, async throws, Codable и встроенный retry. Swift Package, Swift 5.9+, macOS 13+ или iOS 16+
• SDK, C# — Типизированный клиент для Pachca API на C#: .NET 8+ с async/await, CancellationToken, автопагинацией и обработкой retry. NuGet-пакет Pachca.Sdk
• n8n, Обзор — Расширение Пачки для n8n со статусом verified by n8n: 18 ресурсов, триггер событий и AI-агент. Визуальные workflow без кода для CRM, CI/CD и уведомлений
• n8n, Начало работы — Установка расширения Пачки для n8n из официальной витрины: верифицированная нода, установка через Nodes panel, n8n Cloud и self-hosted, настройка Credentials и первый workflow
• n8n, Ресурсы и операции — 18 ресурсов и более 60 операций расширения Пачки для n8n: сообщения, чаты, задачи, сотрудники, боты, теги и вебхуки в модели Resource → Operation
• n8n, Триггер — Триггер Pachca Trigger для n8n: 16 типов событий Пачки, автоматическая и ручная регистрация вебхука, проверка подписи запроса и IP-фильтр для безопасности
• n8n, Тестирование — Тестирование n8n-узлов Пачки: Listen for test event, Pin Data и Execute Step для экшн-узлов, защита webhook-слота бота и локальная разработка через туннель
• n8n, Примеры workflow — Готовые сценарии автоматизации Пачки в n8n: приветствие сотрудника, пересылка сообщений, задачи из обсуждений, согласование, мониторинг и заявки на отпуск
• n8n, Продвинутые функции — Продвинутые функции n8n-расширения Пачки: загрузка файлов через S3, интерактивные кнопки, формы, AI-агент, разворачивание ссылок и журнал безопасности
• n8n, Устранение ошибок — Частые ошибки при работе с Пачкой в n8n: неверный Access Token, 401 Unauthorized, 403 Forbidden, 429 Too Many Requests и проблемы с доставкой вебхука
• n8n, Миграция с v1 — Обновление расширения Пачки для n8n с v1 на v2: таблицы переименований, новые возможности и полная обратная совместимость для существующих workflow
• Последние обновления — История изменений API Пачки, CLI, SDK и расширения для n8n. Новые методы, параметры и возможности. RSS-лента и markdown-версия для AI-агентов и интеграций
• Основы API, Обзор — Обзор REST API Пачки: базовый URL, авторизация по Bearer-токену, формат запросов и ответов, клиенты и SDK для CLI, TypeScript, Python, Go, Kotlin, Swift и C#
• Основы API, Авторизация — Авторизация в API Пачки: персональный токен и токен бота, скоупы методов, headless-интеграции для агентов, настройка доступа для администраторов и сотрудников, смена владельца пространства
• Основы API, Запросы и ответы — Формат запросов и ответов API Пачки: базовый URL, заголовки Authorization и Content-Type, структура JSON-тела, коллекции Postman и Bruno для тестирования
• Основы API, Пагинация — Пагинация в API Пачки по курсору: две группы методов (списочные и поиск) с разной структурой meta, поля next_page, prev_page, has_next, has_prev, обход всех записей и polling новых данных через prev_page
• Основы API, Загрузка файлов — Трёхшаговая загрузка файлов в API Пачки через presigned URL S3: получение подписи, отправка multipart/form-data и прикрепление к сообщению или задаче
• Основы API, Ошибки — Коды ошибок HTTP в API Пачки и структуры тела ответа: ApiError (400/402/403/404/409/410/422) и OAuthError (401/403) с описанием полей и кодов
• Основы API, Лимиты — Лимиты запросов (rate limits) в API Пачки: числа по типам операций, поведение ответа 429, заголовок Retry-After, готовые примеры экспоненциального backoff на TypeScript и Python
• Основы API, Модели — Справочник моделей данных Pachca API: свойства и методы, возвращающие каждый объект — сотрудники, чаты, сообщения, задачи, теги, вебхуки и другие сущности

Modular Skills

For AI agents that support modular skills, install specialized skills for better context efficiency:

npx skills add pachca/openapi

Skills index: https://dev.pachca.com/.well-known/skills/index.json API catalog (RFC 9727): https://dev.pachca.com/.well-known/api-catalog — single JSON with all API descriptions (OpenAPI, Postman, Arazzo), docs (HTML, llms.txt) and metadata.