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

# 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`.

## Form blocks

Eleven block types: `header`, `plain_text`, `markdown`, `divider`, `input`, `select`, `radio`, `checkbox`, `date`, `time`, `file_input`. Field-level reference — parameters, limits and defaults for each — lives at https://dev.pachca.com/guides/forms/blocks.md and is the only place it is maintained.

> A file uploaded through `file_input` is reachable by the URL in `data.<field>[].url` for two hours, and the file itself is kept for a day. Download it when the submission arrives, not later.

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