---
name: pachca-forms
description: >
  Интерактивные формы с полями ввода и кнопками для ботов. Используй когда нужно:
  показать форму, обработать submit формы, валидировать поля формы, создать
  модальное окно, опрос сотрудников. НЕ используй для: обычных кнопок в сообщениях
  (→ pachca-messages), настройки бота (→ pachca-bots).
---

# pachca-forms

Base URL: `https://api.pachca.com/api/shared/v1`
Авторизация: `Authorization: Bearer <ACCESS_TOKEN>`
Токен: **только бот** (Автоматизации → Интеграции → API). Пользовательский токен не подойдёт — формы требуют исходящий вебхук.
Если токен неизвестен — спроси у пользователя перед выполнением запросов.

## Когда использовать

- показать форму
- интерактивная форма
- модальное окно
- modal
- submit формы
- обработать отправку формы
- валидация формы
- view_submission
- опрос
- заявка через форму

## Когда НЕ использовать

- получить профиль, мой профиль, установить статус → **pachca-profile**
- найти сотрудника, создать пользователя, список сотрудников → **pachca-users**
- создать канал, создать беседу, создать чат → **pachca-chats**
- отправить сообщение, ответить в тред, прикрепить файл → **pachca-messages**
- настроить бота, вебхук, webhook → **pachca-bots**
- создать задачу, список задач, напоминание → **pachca-tasks**
- аудит, журнал событий, безопасность → **pachca-security**

## Пошаговые сценарии

### Показать интерактивную форму пользователю

1. Заранее подготовь объект формы: `view` с `title`, `blocks` (типы: `input`, `select`, `radio`, `checkbox`, `date`, `time`, `file_input`, `header`, `plain_text`, `markdown`, `divider`), опционально `callback_id` (идентификатор формы) и `private_metadata` (контекст, например id сообщения)
2. Отправь сообщение с кнопкой (POST /messages с `buttons`, в `data` кнопки передай идентификатор формы)
3. При нажатии кнопки — получи вебхук-событие с `trigger_id`
4. Немедленно отправь POST /views/open с `trigger_id` и готовым объектом формы
5. Пользователь заполняет форму → при отправке получи вебхук — обработай по сценарию «Обработать отправку формы»

```bash
curl "https://api.pachca.com/api/shared/v1/views/open" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"modal","trigger_id":"abc123","view":{"title":"Заявка на отпуск","callback_id":"vacation_form","private_metadata":"{\"msg_id\":154332686}","blocks":[{"type":"input","name":"date_start","label":"Дата начала"},{"type":"input","name":"date_end","label":"Дата окончания"},{"type":"select","name":"reason","label":"Причина","options":[{"text":"Отпуск","value":"vacation"},{"text":"Больничный","value":"sick"}]}]}}'
```

> `trigger_id` живёт 3 секунды — за это время нужно успеть отправить POST /views/open. Формируй объект формы заранее, а не после получения события. Формы работают только от бота.

### Обработать отправку формы (view_submission)

1. Получи вебхук с `"type": "view"`, `"event": "submit"` — содержит `callback_id`, `user_id`, `private_metadata` и `data` (значения полей, ключи совпадают с полем `name` каждого блока)
2. Извлеки значения из `data`: например, для блока с `"name": "comment"` значение в `data.comment`
3. Если форма содержит `file_input` — скачай файлы по `data.field_name[].url` немедленно: ссылки истекают через 1 час
4. Если данные валидны → ответь HTTP 200 (пустое тело) — форма закроется у пользователя
5. Если есть ошибки → ответь HTTP 400 с `{"errors": {"field_name": "текст ошибки"}}` — пользователь увидит ошибки в форме и сможет исправить и отправить повторно

> Ответ должен быть дан в течение 3 секунд — иначе пользователь увидит ошибку отправки, но все значения сохранятся и он повторит попытку. `callback_id` — идентифицирует какая форма отправлена (если ботов несколько). `private_metadata` — контекст, переданный при открытии (до 3000 символов).

### Опрос сотрудников через форму

1. Отправь сообщение с кнопкой «Пройти опрос» в канал или ЛС: POST /messages с `"data": "survey_start"` в кнопке
2. При нажатии кнопки получи вебхук с `trigger_id` и `user_id` нажавшего
3. Немедленно отправь POST /views/open с формой (поля: `input`, `select`, `radio` и т.д.)
4. При отправке формы получи вебхук с `"event": "submit"` — значения полей в `data`
5. Обработай ответы: сохрани в базу или отправь итоговым сообщением в канал
6. Ответь HTTP 200 — форма закроется

> Каждый пользователь должен нажать кнопку сам — у каждого свой `trigger_id`. Нельзя открыть форму принудительно.

### Форма заявки/запроса

1. Размести в канале сообщение с кнопкой «Создать заявку» (`"data": "new_request"`)
2. При нажатии открой форму с полями: тема, описание, приоритет (`select`)
3. При submit-вебхуке: создай задачу (POST /tasks) или отправь уведомление ответственному (POST /messages с `"entity_type": "user"`)
4. Отправь подтверждение автору: POST /messages с `"entity_type": "user"`, `"entity_id": user_id` из вебхука
5. Ответь HTTP 200 — форма закроется

## Обработка ошибок

| Код | Причина | Что делать |
|-----|---------|------------|
| 422 | Неверные параметры | Проверь обязательные поля, типы данных, допустимые значения enum |
| 429 | Rate limit | Подожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec |
| 403 | Нет доступа | Недостаточно скоупов (`insufficient_scope`), бот не в чате, или endpoint только для админов/владельцев |
| 404 | Не найдено | Неверный id. Проверь что сущность существует |
| 401 | Не авторизован | Проверь токен в заголовке Authorization |
| 410 | trigger_id истёк или не найден | trigger_id действует 3 секунды. Получи новый через нажатие кнопки (вебхук) |

## Доступные операции

### Открытие представления

`POST /views/open`

> скоуп: `views:write`

```json
{
  "type": "modal",
  "trigger_id": "",
  "view": {
    "title": "",
    "blocks": []
  }
}
```

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

- `type`: допустимые значения — `modal` (Модальное окно)
- `private_metadata`: максимум 3000 символов
- `callback_id`: максимум 255 символов
- `view.title`: максимум 24 символов
- `view.close_text`: максимум 24 символов
- `view.submit_text`: максимум 24 символов
- Пагинация: cursor-based (limit + cursor), НЕ page-based

## Подробнее

см. [references/endpoints.md](references/endpoints.md)