pachca-forms

pachca-forms

Quick start

Ask the user for a Pachca token (bot: the API tab of the bot in Integrations → Bots, user: Integrations → 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

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.

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 (Modal window)
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	Opening a view
POST	/views/{view_id}/submit_response	Response to form submission

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