# Pachca Forms

> Pachca — интерактивные формы и модальные окна для ботов. Создание форм, модальных окон, опросов, анкет и заявок с полями ввода, выпадающими списками, чекбоксами, выбором даты/времени, загрузкой файлов. Используй, когда пользователь хочет показать форму, открыть модальное окно, создать опрос или анкету, обработать отправку формы (view_submission) или валидацию полей. Также для trigger_id и dropdown/select. Требует токен бота. НЕ для инлайн-кнопок в сообщениях или настройки вебхуков. Use when: показать форму, открыть форму, собрать форму, модальное окно, модалка, отправка формы, обработать форму, валидация формы, валидация поля, view_submission, опрос, анкета, заявка, форма заявки, form, modal, interactive form. NOT for: кнопки в сообщении, настроить бота, вебхук, → pachca-messages, → pachca-bots.

- Skill: `pachca/pachca-forms` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add pachca/pachca-forms`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pachca/pachca-forms/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pachca (https://skillmd.com/u/pachca)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pachca/pachca-forms

---


# pachca-forms

## Quick start

Ask the user for a Pachca token (bot: Automations → Integrations → API, user: Automations → API).
**Bot token only** — user tokens will not work.

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

1. If the user has a saved profile — check:

       npx -y @pachca/cli auth status

   If OK — run commands without `--token`.

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

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

3. If you don't know the parameters — run `pachca <command> --help`.

## Limitations

- Rate limit: ~50 req/sec. On 429 — wait and retry.
- 410: trigger_id expired or not found. trigger_id is valid for 3 seconds. Get a new one via button click (webhook)
- 410: submit_expired on POST /views/{view_id}/submit_response. The response window is 5 seconds from form submission, and a response is accepted once. Read the event history often enough to answer in time
- 404: view_not_found on POST /views/{view_id}/submit_response. Take view_id from the view_submit event payload and respond with the same bot token that opened the view
- `type`: allowed values — `modal` (Модальное окно)
- `private_metadata`: max 3000 characters
- `callback_id`: max 255 characters
- `view.title`: max 24 characters
- `view.close_text`: max 24 characters
- `view.submit_text`: max 24 characters

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /views/open | Открытие представления |
| POST | /views/{view_id}/submit_response | Ответ на отправку формы |

## Advanced workflows

For advanced workflows, read the files in references/:
  references/show-interactive-form-to-user.md — Show interactive form to user
  references/handle-form-submission-viewsubmission.md — Handle form submission (view_submission)
  references/employee-survey-via-form.md — Employee survey via form
  references/requestapplication-form.md — Request/application form

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