diff --git a/README.md b/README.md index b920c44b..8853f184 100644 --- a/README.md +++ b/README.md @@ -414,16 +414,18 @@ description: Краткое описание для SEO ### Обновление API (changelog) -В `content/updates.mdx`: +Создайте файл `content/updates/<ГГГГ-ММ-ДД>.md` (один файл на дату) с frontmatter и markdown-телом: ```md - -## Название обновления +--- +date: "2025-12-01" +title: "Название обновления" +--- - [Новый метод](POST /messages) ``` -Badge «Новое» показывается < 7 дней. Попадает в RSS feed. +Badge «Новое» показывается < 7 дней. Попадает в RSS feed. Полные правила — [docs/updates-format.md](docs/updates-format.md). ### Кастомная схема для гайда diff --git a/apps/docs/content/api/models.mdx b/apps/docs/content/api/models.mdx index 606be86e..315a924b 100644 --- a/apps/docs/content/api/models.mdx +++ b/apps/docs/content/api/models.mdx @@ -23,7 +23,7 @@ hideTableOfContents: true - + @@ -153,6 +153,8 @@ hideTableOfContents: true ## Параметры бота +- [Создание бота](POST /bots) +- [Получение бота](GET /bots/{id}) - [Редактирование бота](PUT /bots/{id}) diff --git a/apps/docs/content/guides/bots/setup.mdx b/apps/docs/content/guides/bots/setup.mdx index 96fdc974..79625317 100644 --- a/apps/docs/content/guides/bots/setup.mdx +++ b/apps/docs/content/guides/bots/setup.mdx @@ -10,10 +10,15 @@ related: # Создание и настройка -## Создание бота +Бота можно создать двумя способами: + +- **Через интерфейс** — больше настроек (тип бота, аватар, доступы, шаблоны входящего вебхука) и наглядная пошаговая форма. Подходит для разовой ручной настройки. +- **Через API** ([Создание бота](POST /bots)) — программно, без интерфейса. Подходит для автоматизации: завести бота из своего сервиса или скрипта и сразу получить `access_token`. + +## Создание бота через интерфейс - Создание и настройка ботов доступны в веб-версии и десктопном приложении Пачки. В мобильных приложениях (iOS и Android) эта возможность недоступна. + Создание и настройка ботов через интерфейс доступны в веб-версии и десктопном приложении Пачки. В мобильных приложениях (iOS и Android) эта возможность недоступна. Для создания бота перейдите в **Автоматизации** > **Интеграции** > **Чат-боты и Вебхуки** и нажмите кнопку **«+»**. @@ -43,6 +48,21 @@ related: +## Создание бота через API + +Бота можно создать программно методом [Создание бота](POST /bots) — без интерфейса. Это удобно, когда нужно завести бота из своего сервиса или скрипта. + + + + Передайте параметры бота в объекте `bot.webhook`: имя, никнейм, Webhook URL, список событий и команды. Никнейм должен заканчиваться на `_bot`. + + + В ответе вы получите `access_token` бота — сразу сохраните его. Повторно получить токен вы сможете только через интерфейс (вкладка **API** настроек бота), там же его можно перевыпустить. Вместе с токеном придёт `id` бота (его `user_id`). + + + +Получить параметры существующего бота можно методом [Получение бота](GET /bots/{id}), а изменить — методом [Редактирование бота](PUT /bots/{id}). + ## Профиль бота Бот, как и любой участник пространства, имеет свой профиль. В нём отображаются имя, аватар, никнейм, статус и список общих чатов с ботом. Профиль бота можно редактировать — изменить имя, никнейм и другие поля. diff --git a/apps/docs/content/guides/cli/installation.mdx b/apps/docs/content/guides/cli/installation.mdx index fe2c810e..2b134e32 100644 --- a/apps/docs/content/guides/cli/installation.mdx +++ b/apps/docs/content/guides/cli/installation.mdx @@ -67,7 +67,7 @@ pachca doctor # ✔ Конфиг ~/.config/pachca/config.toml (права: 600) # ✔ Профиль personal (user: Иван Иванов) # ✔ Токен действителен (11 скоупов) -# ✔ CLI v2026.5.2 (актуальная версия) +# ✔ CLI v2026.6.0 (актуальная версия) ``` ## Обновление diff --git a/apps/docs/content/updates/2026-06-15.md b/apps/docs/content/updates/2026-06-15.md new file mode 100644 index 00000000..eba5f303 --- /dev/null +++ b/apps/docs/content/updates/2026-06-15.md @@ -0,0 +1,19 @@ +--- +date: "2026-06-15" +title: "Создание ботов через API, голосовые сообщения" +--- + +Теперь бота можно создать и получить через API, а не только в интерфейсе. При создании вы получите `access_token` бота — сразу сохраните его, повторно получить токен можно только через интерфейс. + +Новые и обновлённые методы для ботов: + +- [Создание бота](POST /bots) +- [Получение бота](GET /bots/{id}) +- [Редактирование бота](PUT /bots/{id}) + +Появилась поддержка голосовых сообщений. В сообщении возвращается объект `voice_content` с длительностью, формой волны и расшифровкой, а при отправке файла с `file_type` = `voice` принимаются параметры `duration_ms` и `waveform`. + +- [Отправка нового сообщения](POST /messages) +- [Редактирование сообщения](PUT /messages/{id}) + +В payload вебхука реакции поле `created_at` теперь приходит и при удалении реакции. Также в деталях события аудита DLP поле `action_message` может быть `null`, если у действия правила не задан текст. diff --git a/apps/docs/data/releases.json b/apps/docs/data/releases.json index 6f932b52..46def14a 100644 --- a/apps/docs/data/releases.json +++ b/apps/docs/data/releases.json @@ -1,4 +1,60 @@ [ + { + "product": "cli", + "version": "2026.6.0", + "date": "2026-06-15", + "changes": [ + { + "type": "+", + "command": "bots create", + "description": "Новая команда — создание бота и получение его access_token" + }, + { + "type": "+", + "command": "bots get", + "description": "Новая команда — получение параметров бота" + }, + { + "type": "~", + "command": "bots update", + "description": "Расширены поля редактирования бота: name, nickname, events, trigger_on, commands" + }, + { + "type": "+", + "description": "В сообщениях появилось поле voice_content и параметры файлов duration_ms / waveform для голосовых сообщений" + } + ] + }, + { + "product": "n8n", + "version": "2.0.10", + "date": "2026-06-15", + "changes": [ + { + "type": "+", + "description": "Создание и получение ботов через API (POST /bots, GET /bots/{id})" + }, + { + "type": "+", + "description": "Поддержка голосовых сообщений: поле voice_content и параметры duration_ms / waveform" + } + ] + }, + { + "product": "sdk", + "version": "1.0.22", + "date": "2026-06-15", + "changes": [ + { + "type": "+", + "description": "Методы создания и получения ботов: POST /bots, GET /bots/{id}" + }, + { + "type": "+", + "description": "Поле voice_content в сообщении и параметры файлов duration_ms / waveform для голосовых сообщений" + } + ] + }, { "product": "sdk", "version": "1.0.21", diff --git a/apps/docs/lib/code-generators/cli.ts b/apps/docs/lib/code-generators/cli.ts index fd7565b9..c8b18f08 100644 --- a/apps/docs/lib/code-generators/cli.ts +++ b/apps/docs/lib/code-generators/cli.ts @@ -123,9 +123,15 @@ function valueToFlag( } } else if (typeof value === 'object') { parts.push(`--${flag}='${JSON.stringify(value)}'`); + } else if (typeof value === 'number' || typeof value === 'bigint') { + parts.push(`--${flag}=${value}`); } else { const strValue = String(value); - if (strValue.includes(' ')) { + // Квотируем только если в значении есть пробел или shell-метасимвол. + // Простые URL, идентификаторы, enum-значения и slug-и остаются без кавычек + // (по соглашению gh / Vercel / Heroku / AWS). Реальные URL с `?...&...` + // пользователь сам должен взять в кавычки при копировании. + if (/[\s&|;()<>*?$`\\'"#]/.test(strValue)) { parts.push(`--${flag}="${strValue}"`); } else { parts.push(`--${flag}=${strValue}`); @@ -190,9 +196,9 @@ function extractUnwrappedBodyFields( if (s.readOnly) continue; if (options?.requiredOnly && !innerRequired.includes(name)) continue; const example = generateExample(s, 0, options); - if (example !== undefined) { - fields.push({ name, example, schemaType: s.type, format: s.format }); - } + if (example === undefined) continue; + if (isRedundantDefault(s, innerRequired.includes(name), example)) continue; + fields.push({ name, example, schemaType: s.type, format: s.format }); } } @@ -204,9 +210,9 @@ function extractUnwrappedBodyFields( if (s.readOnly) continue; if (options?.requiredOnly && !topRequired.includes(key)) continue; const example = generateExample(s, 0, options); - if (example !== undefined) { - fields.push({ name: key, example, schemaType: s.type, format: s.format }); - } + if (example === undefined) continue; + if (isRedundantDefault(s, topRequired.includes(key), example)) continue; + fields.push({ name: key, example, schemaType: s.type, format: s.format }); } return fields; @@ -220,9 +226,14 @@ function extractUnwrappedBodyFields( if (s.readOnly) continue; if (options?.requiredOnly && !topRequired.includes(name)) continue; const example = generateExample(s, 0, options); - if (example !== undefined) { - fields.push({ name, example, schemaType: s.type, format: s.format }); - } + if (example === undefined) continue; + if (isRedundantDefault(s, topRequired.includes(name), example)) continue; + fields.push({ name, example, schemaType: s.type, format: s.format }); } return fields; } + +/** Шум: опциональное поле, у которого пример равен дефолту схемы. Тождественно «не передавать поле». */ +function isRedundantDefault(schema: Schema, isRequired: boolean, example: unknown): boolean { + return !isRequired && schema.default !== undefined && example === schema.default; +} diff --git a/apps/docs/lib/openapi/example-generator.ts b/apps/docs/lib/openapi/example-generator.ts index 0d7c7a32..35e6c5d0 100644 --- a/apps/docs/lib/openapi/example-generator.ts +++ b/apps/docs/lib/openapi/example-generator.ts @@ -82,8 +82,21 @@ export function generateExample( } const propExample = generateExample(ps, depth + 1, options); + const isRequired = requiredFields.includes(propName); + + // Шум: опциональное поле, у которого сгенерированный пример равен дефолту, + // — это эквивалент «не передавать поле». Не засоряем им примеры. + if ( + !isRequired && + ps.default !== undefined && + propExample !== undefined && + propExample === ps.default + ) { + continue; + } + // Включаем свойство если оно обязательное или имеет пример - if (propExample !== undefined || requiredFields.includes(propName)) { + if (propExample !== undefined || isRequired) { example[propName] = propExample !== undefined ? propExample : null; } } diff --git a/apps/docs/public/.well-known/agent-skills/index.json b/apps/docs/public/.well-known/agent-skills/index.json index 5b9cbece..ae6e51dd 100644 --- a/apps/docs/public/.well-known/agent-skills/index.json +++ b/apps/docs/public/.well-known/agent-skills/index.json @@ -34,7 +34,7 @@ "type": "skill-md", "description": "Pachca — управление ботами, вебхуки и превью ссылок. Используй этот скилл, когда пользователь хочет настроить бота, создать бота, настроить вебхуки, обработать вебхук, проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки, создать дайджест-бота или настроить превью ссылок. НЕ для отправки обычных сообщений, показа форм или модальных окон.", "url": "/.well-known/skills/pachca-bots/SKILL.md", - "digest": "sha256:b04158006849498930d6fdba9448e6b05c09f3fc94ea6cab42b66a0fd22d96a5" + "digest": "sha256:cc703087c03b52896deff06ee4d4d63d4d1bb7ffdd2fde94a16da4563dfca45b" }, { "name": "pachca-forms", diff --git a/apps/docs/public/.well-known/skills/index.json b/apps/docs/public/.well-known/skills/index.json index 5b9cbece..ae6e51dd 100644 --- a/apps/docs/public/.well-known/skills/index.json +++ b/apps/docs/public/.well-known/skills/index.json @@ -34,7 +34,7 @@ "type": "skill-md", "description": "Pachca — управление ботами, вебхуки и превью ссылок. Используй этот скилл, когда пользователь хочет настроить бота, создать бота, настроить вебхуки, обработать вебхук, проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки, создать дайджест-бота или настроить превью ссылок. НЕ для отправки обычных сообщений, показа форм или модальных окон.", "url": "/.well-known/skills/pachca-bots/SKILL.md", - "digest": "sha256:b04158006849498930d6fdba9448e6b05c09f3fc94ea6cab42b66a0fd22d96a5" + "digest": "sha256:cc703087c03b52896deff06ee4d4d63d4d1bb7ffdd2fde94a16da4563dfca45b" }, { "name": "pachca-forms", diff --git a/apps/docs/public/.well-known/skills/pachca-bots/SKILL.md b/apps/docs/public/.well-known/skills/pachca-bots/SKILL.md index 57adf99b..43a09ea8 100644 --- a/apps/docs/public/.well-known/skills/pachca-bots/SKILL.md +++ b/apps/docs/public/.well-known/skills/pachca-bots/SKILL.md @@ -47,15 +47,32 @@ Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide` ## Workflows +### Создать бота через API и получить токен + +1. Создай бота. Только пользовательским токеном (не токеном бота); `nickname` обязан заканчиваться на `_bot`. Параметры вебхука (Webhook URL, события, команды) можно задать сразу или позже: + ```bash + pachca bots create --bot='{"webhook":{"name":"Бот задач","nickname":"tasks_bot"}}' + ``` + +2. Сохрани `access_token` из ответа — он возвращается единственный раз. Повторно получить токен можно только через интерфейс (вкладка «API» настроек бота) + +3. В ответе также придёт `id` бота (его `user_id`) — он нужен для дальнейших вызовов, например чтобы добавить бота в чат + +> Создавать ботов можно только пользовательским токеном — токеном бота нельзя. `access_token` отдаётся один раз при создании, дальше его можно посмотреть и скопировать в интерфейсе. + + ### Настроить бота с исходящим вебхуком -1. Создай бота в интерфейсе Пачки: Автоматизации → Интеграции → Webhook +1. Создай бота, сразу указав Webhook URL и события в одном вызове (детали создания и работы с токеном — в сценарии «Создать бота через API и получить токен»): + ```bash + pachca bots create --bot='{"webhook":{"name":"Бот задач","nickname":"tasks_bot","outgoing_url":"https://example.com/webhook","events":["message_new"],"trigger_on":"commands","commands":["/task"]}}' + ``` -2. Получи `access_token` бота во вкладке «API» настроек бота +2. Сохрани `access_token` из ответа (возвращается единственный раз) -3. Укажи Webhook URL для получения событий +3. Используй сохранённый `access_token` для отправки сообщений от имени бота -> Бот создаётся через UI, не через API. Единственный эндпоинт для ботов — PUT /bots/{id} (обновление webhook URL). API используется для отправки сообщений от имени бота. +> Альтернатива — создать и настроить бота в интерфейсе. Webhook URL и события можно задать и позже методом PUT /bots/{id}. ### Обновить Webhook URL бота @@ -86,6 +103,7 @@ Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide` ## Limitations - Rate limit: ~50 req/sec. On 429 — wait and retry. +- `bot.webhook.trigger_on`: allowed values — `commands` (Только на команды (триггер-слова) из commands), `all_messages` (На все сообщения в чатах, где есть бот), `unfurl` (На развёртывание ссылок (link previews)) - `limit`: max 50 - Pagination: cursor-based (limit + cursor) @@ -93,6 +111,8 @@ Help: `npx -y @pachca/cli --help` | Workflows: `npx -y @pachca/cli guide` | Method | Path | Description | |--------|------|-------------| +| POST | /bots | Создание бота | +| GET | /bots/{id} | Получение бота | | PUT | /bots/{id} | Редактирование бота | | POST | /messages/{id}/link_previews | Unfurl (разворачивание ссылок) | | GET | /webhooks/events | История событий | diff --git a/apps/docs/public/api/bots/create.md b/apps/docs/public/api/bots/create.md new file mode 100644 index 00000000..a637eb37 --- /dev/null +++ b/apps/docs/public/api/bots/create.md @@ -0,0 +1,214 @@ +> Расположение: Методы API → Боты и Webhook +> Краткое содержание: Метод для создания бота и получения его accesstoken. +> Это Markdown-версия конкретной страницы. Для контекста за её пределами (правила API, полный перечень методов, авторизация) ОБЯЗАТЕЛЬНО открой [llms.txt](https://dev.pachca.com/llms.txt) перед ответом — это сэкономит токены и предотвратит неполный ответ. + +# Создание бота + +**Метод**: `POST` + +**Путь**: `/bots` + +> **Скоуп:** `bots:write` + +Метод для создания бота и получения его `access_token`. + +При создании вы получите `access_token` бота — сразу сохраните его. Повторно получить токен вы сможете только через интерфейс (вкладка «API» настроек бота). + +## Тело запроса + +**Обязательно** + +Формат: `application/json` + +### Схема + +- `bot: object` (required) — Собранный объект параметров создаваемого бота + - `webhook: object` (required) — Объект параметров вебхука бота + - `name: string` (required) — Имя бота. Пример: `"Бот задач"` + - `nickname: string` — Никнейм бота. Должен заканчиваться на `_bot`.. Пример: `"tasks_bot"` + - `outgoing_url: string` — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `events: array of string` — События, на которые подписан бот. Пример: `["message_new"]` + - `trigger_on: string` — Условие срабатывания исходящего вебхука + Значения: `commands` — Только на команды (триггер-слова) из commands, `all_messages` — На все сообщения в чатах, где есть бот, `unfurl` — На развёртывание ссылок (link previews) + - `commands: array of string` — Команды бота (триггер-слова), на которые он реагирует при trigger_on = commands. Пример: `["/task","/help"]` + +### Пример + +```json +{ + "bot": { + "webhook": { + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task", + "/help" + ] + } + } +} +``` + +## Пример запроса + +```bash +curl "https://api.pachca.com/api/shared/v1/bots" \ + -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "bot": { + "webhook": { + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task", + "/help" + ] + } + } +}' +``` + +## Ответы + +### 201: The request has succeeded and a new resource has been created as a result. + +**Схема ответа:** + +- `data: object` (required) — Параметры созданного бота + - `id: integer, int32` (required) — Идентификатор бота (совпадает с `user_id` бота). Пример: `1738816` + - `webhook: object` (required) — Объект параметров вебхука + - `name: string` (required) — Имя бота. Пример: `"Бот задач"` + - `nickname: string` (required) — Никнейм бота. Пример: `"tasks_bot"` + - `outgoing_url: string` (required) — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `events: array of string` (required) — События, на которые подписан бот. Пример: `["message_new"]` + - `trigger_on: string` (required) — Условие срабатывания исходящего вебхука + Значения: `commands` — Только на команды (триггер-слова) из commands, `all_messages` — На все сообщения в чатах, где есть бот, `unfurl` — На развёртывание ссылок (link previews) + - `commands: array of string` (required) — Команды бота (триггер-слова). Пример: `["/task"]` + - `access_token: string` (required) — Токен доступа бота. Выдаётся только при создании. Повторно получить токен можно только через интерфейс (вкладка «API» настроек бота).. Пример: `"bm90X2FfcmVhbF90b2tlbg"` + +**Пример ответа:** + +```json +{ + "data": { + "id": 1738816, + "webhook": { + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task" + ] + }, + "access_token": "bm90X2FfcmVhbF90b2tlbg" + } +} +``` + +### 400: The server could not understand the request due to invalid syntax. + +**Схема ответа при ошибке:** + +- `errors: array of object` (required) — Массив ошибок + - `key: string` (required) — Ключ поля с ошибкой. Пример: `"field.name"` + - `value: string` (required) — Значение поля, которое вызвало ошибку. Пример: `"invalid_value"` + - `message: string` (required) — Сообщение об ошибке. Пример: `"Поле не может быть пустым"` + - `code: string` (required) — Код ошибки + Значения: `blank` — Обязательное поле (не может быть пустым), `too_long` — Слишком длинное значение (пояснения вы получите в поле message), `invalid` — Поле не соответствует правилам (пояснения вы получите в поле message), `inclusion` — Поле имеет непредусмотренное значение, `exclusion` — Поле имеет недопустимое значение, `taken` — Название для этого поля уже существует, `wrong_emoji` — Emoji статуса не может содержать значения отличные от Emoji символа, `not_found` — Объект не найден, `already_exists` — Объект уже существует (пояснения вы получите в поле message), `personal_chat` — Ошибка личного чата (пояснения вы получите в поле message), `displayed_error` — Отображаемая ошибка (пояснения вы получите в поле message), `not_authorized` — Действие запрещено, `invalid_date_range` — Выбран слишком большой диапазон дат, `invalid_webhook_url` — Некорректный URL вебхука, `rate_limit` — Достигнут лимит запросов, `licenses_limit` — Превышен лимит активных сотрудников (пояснения вы получите в поле message), `user_limit` — Превышен лимит количества реакций, которые может добавить пользователь (20 уникальных реакций), `unique_limit` — Превышен лимит количества уникальных реакций, которые можно добавить на сообщение (30 уникальных реакций), `general_limit` — Превышен лимит количества реакций, которые можно добавить на сообщение (1000 реакций), `unhandled` — Ошибка выполнения запроса (пояснения вы получите в поле message), `trigger_not_found` — Не удалось найти идентификатор события, `trigger_expired` — Время жизни идентификатора события истекло, `required` — Обязательный параметр не передан, `in` — Недопустимое значение (не входит в список допустимых), `not_applicable` — Значение неприменимо в данном контексте (пояснения вы получите в поле message), `self_update` — Нельзя изменить свои собственные данные, `owner_protected` — Нельзя изменить данные владельца, `already_assigned` — Значение уже назначено, `forbidden` — Недостаточно прав для выполнения действия (пояснения вы получите в поле message), `permission_denied` — Доступ запрещён (недостаточно прав), `access_denied` — Доступ запрещён, `wrong_params` — Некорректные параметры запроса (пояснения вы получите в поле message), `payment_required` — Требуется оплата, `min_length` — Значение слишком короткое (пояснения вы получите в поле message), `max_length` — Значение слишком длинное (пояснения вы получите в поле message), `use_of_system_words` — Использовано зарезервированное системное слово (here, all) + - `payload: Record` (required) — Дополнительные данные об ошибке. Содержимое зависит от кода ошибки: `{id: number}` — при ошибке кастомного свойства (идентификатор свойства), `{record: {type: string, id: number}, query: string}` — при ошибке авторизации. В большинстве случаев `null`. Пример: `null` + **Структура значений Record:** + - Тип значения: `any` + +**Пример ответа:** + +```json +{ + "errors": [ + { + "key": "field.name", + "value": "invalid_value", + "message": "Поле не может быть пустым", + "code": "blank", + "payload": null + } + ] +} +``` + +### 401: Access is unauthorized. + +**Схема ответа при ошибке:** + +- `error: string` (required) — Код ошибки. Пример: `"invalid_token"` +- `error_description: string` (required) — Описание ошибки. Пример: `"Access token is missing"` + +**Пример ответа:** + +```json +{ + "error": "invalid_token", + "error_description": "Access token is missing" +} +``` + +### 402: Client error + +**Схема ответа при ошибке:** + +- `errors: array of object` (required) — Массив ошибок + - `key: string` (required) — Ключ поля с ошибкой. Пример: `"field.name"` + - `value: string` (required) — Значение поля, которое вызвало ошибку. Пример: `"invalid_value"` + - `message: string` (required) — Сообщение об ошибке. Пример: `"Поле не может быть пустым"` + - `code: string` (required) — Код ошибки + Значения: `blank` — Обязательное поле (не может быть пустым), `too_long` — Слишком длинное значение (пояснения вы получите в поле message), `invalid` — Поле не соответствует правилам (пояснения вы получите в поле message), `inclusion` — Поле имеет непредусмотренное значение, `exclusion` — Поле имеет недопустимое значение, `taken` — Название для этого поля уже существует, `wrong_emoji` — Emoji статуса не может содержать значения отличные от Emoji символа, `not_found` — Объект не найден, `already_exists` — Объект уже существует (пояснения вы получите в поле message), `personal_chat` — Ошибка личного чата (пояснения вы получите в поле message), `displayed_error` — Отображаемая ошибка (пояснения вы получите в поле message), `not_authorized` — Действие запрещено, `invalid_date_range` — Выбран слишком большой диапазон дат, `invalid_webhook_url` — Некорректный URL вебхука, `rate_limit` — Достигнут лимит запросов, `licenses_limit` — Превышен лимит активных сотрудников (пояснения вы получите в поле message), `user_limit` — Превышен лимит количества реакций, которые может добавить пользователь (20 уникальных реакций), `unique_limit` — Превышен лимит количества уникальных реакций, которые можно добавить на сообщение (30 уникальных реакций), `general_limit` — Превышен лимит количества реакций, которые можно добавить на сообщение (1000 реакций), `unhandled` — Ошибка выполнения запроса (пояснения вы получите в поле message), `trigger_not_found` — Не удалось найти идентификатор события, `trigger_expired` — Время жизни идентификатора события истекло, `required` — Обязательный параметр не передан, `in` — Недопустимое значение (не входит в список допустимых), `not_applicable` — Значение неприменимо в данном контексте (пояснения вы получите в поле message), `self_update` — Нельзя изменить свои собственные данные, `owner_protected` — Нельзя изменить данные владельца, `already_assigned` — Значение уже назначено, `forbidden` — Недостаточно прав для выполнения действия (пояснения вы получите в поле message), `permission_denied` — Доступ запрещён (недостаточно прав), `access_denied` — Доступ запрещён, `wrong_params` — Некорректные параметры запроса (пояснения вы получите в поле message), `payment_required` — Требуется оплата, `min_length` — Значение слишком короткое (пояснения вы получите в поле message), `max_length` — Значение слишком длинное (пояснения вы получите в поле message), `use_of_system_words` — Использовано зарезервированное системное слово (here, all) + - `payload: Record` (required) — Дополнительные данные об ошибке. Содержимое зависит от кода ошибки: `{id: number}` — при ошибке кастомного свойства (идентификатор свойства), `{record: {type: string, id: number}, query: string}` — при ошибке авторизации. В большинстве случаев `null`. Пример: `null` + **Структура значений Record:** + - Тип значения: `any` + +**Пример ответа:** + +```json +{ + "errors": [ + { + "key": "field.name", + "value": "invalid_value", + "message": "Поле не может быть пустым", + "code": "blank", + "payload": null + } + ] +} +``` + +### 403: Access is forbidden. + +**Схема ответа при ошибке:** + +- `error: string` (required) — Код ошибки. Пример: `"invalid_token"` +- `error_description: string` (required) — Описание ошибки. Пример: `"Access token is missing"` + +**Пример ответа:** + +```json +{ + "error": "invalid_token", + "error_description": "Access token is missing" +} +``` + diff --git a/apps/docs/public/api/bots/get.md b/apps/docs/public/api/bots/get.md new file mode 100644 index 00000000..05ad52b7 --- /dev/null +++ b/apps/docs/public/api/bots/get.md @@ -0,0 +1,159 @@ +> Расположение: Методы API → Боты и Webhook +> Краткое содержание: Метод для получения параметров бота по его userid. +> Это Markdown-версия конкретной страницы. Для контекста за её пределами (правила API, полный перечень методов, авторизация) ОБЯЗАТЕЛЬНО открой [llms.txt](https://dev.pachca.com/llms.txt) перед ответом — это сэкономит токены и предотвратит неполный ответ. + +# Получение бота + +**Метод**: `GET` + +**Путь**: `/bots/{id}` + +> **Скоуп:** `bots:read` + +Метод для получения параметров бота по его `user_id`. + +## Параметры + +### Path параметры + +- `id: integer, int32` (required) — Идентификатор бота + + +## Пример запроса + +```bash +curl "https://api.pachca.com/api/shared/v1/bots/1738816" \ + -H "Authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +## Ответы + +### 200: The request has succeeded. + +**Схема ответа:** + +- `data: object` (required) — Параметры бота + - `id: integer, int32` (required) — Идентификатор бота (совпадает с `user_id` бота). Пример: `1738816` + - `webhook: object` (required) — Объект параметров вебхука + - `name: string` (required) — Имя бота. Пример: `"Бот задач"` + - `nickname: string` (required) — Никнейм бота. Пример: `"tasks_bot"` + - `outgoing_url: string` (required) — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `events: array of string` (required) — События, на которые подписан бот. Пример: `["message_new"]` + - `trigger_on: string` (required) — Условие срабатывания исходящего вебхука + Значения: `commands` — Только на команды (триггер-слова) из commands, `all_messages` — На все сообщения в чатах, где есть бот, `unfurl` — На развёртывание ссылок (link previews) + - `commands: array of string` (required) — Команды бота (триггер-слова). Пример: `["/task"]` + +**Пример ответа:** + +```json +{ + "data": { + "id": 1738816, + "webhook": { + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task" + ] + } + } +} +``` + +### 401: Access is unauthorized. + +**Схема ответа при ошибке:** + +- `error: string` (required) — Код ошибки. Пример: `"invalid_token"` +- `error_description: string` (required) — Описание ошибки. Пример: `"Access token is missing"` + +**Пример ответа:** + +```json +{ + "error": "invalid_token", + "error_description": "Access token is missing" +} +``` + +### 402: Client error + +**Схема ответа при ошибке:** + +- `errors: array of object` (required) — Массив ошибок + - `key: string` (required) — Ключ поля с ошибкой. Пример: `"field.name"` + - `value: string` (required) — Значение поля, которое вызвало ошибку. Пример: `"invalid_value"` + - `message: string` (required) — Сообщение об ошибке. Пример: `"Поле не может быть пустым"` + - `code: string` (required) — Код ошибки + Значения: `blank` — Обязательное поле (не может быть пустым), `too_long` — Слишком длинное значение (пояснения вы получите в поле message), `invalid` — Поле не соответствует правилам (пояснения вы получите в поле message), `inclusion` — Поле имеет непредусмотренное значение, `exclusion` — Поле имеет недопустимое значение, `taken` — Название для этого поля уже существует, `wrong_emoji` — Emoji статуса не может содержать значения отличные от Emoji символа, `not_found` — Объект не найден, `already_exists` — Объект уже существует (пояснения вы получите в поле message), `personal_chat` — Ошибка личного чата (пояснения вы получите в поле message), `displayed_error` — Отображаемая ошибка (пояснения вы получите в поле message), `not_authorized` — Действие запрещено, `invalid_date_range` — Выбран слишком большой диапазон дат, `invalid_webhook_url` — Некорректный URL вебхука, `rate_limit` — Достигнут лимит запросов, `licenses_limit` — Превышен лимит активных сотрудников (пояснения вы получите в поле message), `user_limit` — Превышен лимит количества реакций, которые может добавить пользователь (20 уникальных реакций), `unique_limit` — Превышен лимит количества уникальных реакций, которые можно добавить на сообщение (30 уникальных реакций), `general_limit` — Превышен лимит количества реакций, которые можно добавить на сообщение (1000 реакций), `unhandled` — Ошибка выполнения запроса (пояснения вы получите в поле message), `trigger_not_found` — Не удалось найти идентификатор события, `trigger_expired` — Время жизни идентификатора события истекло, `required` — Обязательный параметр не передан, `in` — Недопустимое значение (не входит в список допустимых), `not_applicable` — Значение неприменимо в данном контексте (пояснения вы получите в поле message), `self_update` — Нельзя изменить свои собственные данные, `owner_protected` — Нельзя изменить данные владельца, `already_assigned` — Значение уже назначено, `forbidden` — Недостаточно прав для выполнения действия (пояснения вы получите в поле message), `permission_denied` — Доступ запрещён (недостаточно прав), `access_denied` — Доступ запрещён, `wrong_params` — Некорректные параметры запроса (пояснения вы получите в поле message), `payment_required` — Требуется оплата, `min_length` — Значение слишком короткое (пояснения вы получите в поле message), `max_length` — Значение слишком длинное (пояснения вы получите в поле message), `use_of_system_words` — Использовано зарезервированное системное слово (here, all) + - `payload: Record` (required) — Дополнительные данные об ошибке. Содержимое зависит от кода ошибки: `{id: number}` — при ошибке кастомного свойства (идентификатор свойства), `{record: {type: string, id: number}, query: string}` — при ошибке авторизации. В большинстве случаев `null`. Пример: `null` + **Структура значений Record:** + - Тип значения: `any` + +**Пример ответа:** + +```json +{ + "errors": [ + { + "key": "field.name", + "value": "invalid_value", + "message": "Поле не может быть пустым", + "code": "blank", + "payload": null + } + ] +} +``` + +### 403: Access is forbidden. + +**Схема ответа при ошибке:** + +- `error: string` (required) — Код ошибки. Пример: `"invalid_token"` +- `error_description: string` (required) — Описание ошибки. Пример: `"Access token is missing"` + +**Пример ответа:** + +```json +{ + "error": "invalid_token", + "error_description": "Access token is missing" +} +``` + +### 404: The server cannot find the requested resource. + +**Схема ответа при ошибке:** + +- `errors: array of object` (required) — Массив ошибок + - `key: string` (required) — Ключ поля с ошибкой. Пример: `"field.name"` + - `value: string` (required) — Значение поля, которое вызвало ошибку. Пример: `"invalid_value"` + - `message: string` (required) — Сообщение об ошибке. Пример: `"Поле не может быть пустым"` + - `code: string` (required) — Код ошибки + Значения: `blank` — Обязательное поле (не может быть пустым), `too_long` — Слишком длинное значение (пояснения вы получите в поле message), `invalid` — Поле не соответствует правилам (пояснения вы получите в поле message), `inclusion` — Поле имеет непредусмотренное значение, `exclusion` — Поле имеет недопустимое значение, `taken` — Название для этого поля уже существует, `wrong_emoji` — Emoji статуса не может содержать значения отличные от Emoji символа, `not_found` — Объект не найден, `already_exists` — Объект уже существует (пояснения вы получите в поле message), `personal_chat` — Ошибка личного чата (пояснения вы получите в поле message), `displayed_error` — Отображаемая ошибка (пояснения вы получите в поле message), `not_authorized` — Действие запрещено, `invalid_date_range` — Выбран слишком большой диапазон дат, `invalid_webhook_url` — Некорректный URL вебхука, `rate_limit` — Достигнут лимит запросов, `licenses_limit` — Превышен лимит активных сотрудников (пояснения вы получите в поле message), `user_limit` — Превышен лимит количества реакций, которые может добавить пользователь (20 уникальных реакций), `unique_limit` — Превышен лимит количества уникальных реакций, которые можно добавить на сообщение (30 уникальных реакций), `general_limit` — Превышен лимит количества реакций, которые можно добавить на сообщение (1000 реакций), `unhandled` — Ошибка выполнения запроса (пояснения вы получите в поле message), `trigger_not_found` — Не удалось найти идентификатор события, `trigger_expired` — Время жизни идентификатора события истекло, `required` — Обязательный параметр не передан, `in` — Недопустимое значение (не входит в список допустимых), `not_applicable` — Значение неприменимо в данном контексте (пояснения вы получите в поле message), `self_update` — Нельзя изменить свои собственные данные, `owner_protected` — Нельзя изменить данные владельца, `already_assigned` — Значение уже назначено, `forbidden` — Недостаточно прав для выполнения действия (пояснения вы получите в поле message), `permission_denied` — Доступ запрещён (недостаточно прав), `access_denied` — Доступ запрещён, `wrong_params` — Некорректные параметры запроса (пояснения вы получите в поле message), `payment_required` — Требуется оплата, `min_length` — Значение слишком короткое (пояснения вы получите в поле message), `max_length` — Значение слишком длинное (пояснения вы получите в поле message), `use_of_system_words` — Использовано зарезервированное системное слово (here, all) + - `payload: Record` (required) — Дополнительные данные об ошибке. Содержимое зависит от кода ошибки: `{id: number}` — при ошибке кастомного свойства (идентификатор свойства), `{record: {type: string, id: number}, query: string}` — при ошибке авторизации. В большинстве случаев `null`. Пример: `null` + **Структура значений Record:** + - Тип значения: `any` + +**Пример ответа:** + +```json +{ + "errors": [ + { + "key": "field.name", + "value": "invalid_value", + "message": "Поле не может быть пустым", + "code": "blank", + "payload": null + } + ] +} +``` + diff --git a/apps/docs/public/api/bots/list-events.md b/apps/docs/public/api/bots/list-events.md index 9b3329b7..011bb9e8 100644 --- a/apps/docs/public/api/bots/list-events.md +++ b/apps/docs/public/api/bots/list-events.md @@ -73,7 +73,7 @@ curl "https://api.pachca.com/api/shared/v1/webhooks/events?limit=1" \ - `code: string` (required) — Emoji символ реакции. Пример: `"👍"` - `name: string` (required) — Название реакции. Пример: `"thumbsup"` - `user_id: integer, int32` (required) — Идентификатор пользователя, который добавил или удалил реакцию. Пример: `2345` - - `created_at: date-time` (required) — Дата и время создания сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. Пример: `"2025-05-15T14:30:00.000Z"` + - `created_at: date-time` (required) — Дата и время добавления реакции (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. Поле присутствует и для события удаления реакции.. Пример: `"2025-05-15T14:30:00.000Z"` - `webhook_timestamp: integer, int32` (required) — Дата и время отправки вебхука (UTC+0) в формате UNIX. Пример: `1747574400` - **ButtonWebhookPayload**: Структура исходящего вебхука о нажатии кнопки - `type: string` (required) — Тип объекта. Пример: `"button"` @@ -93,9 +93,9 @@ curl "https://api.pachca.com/api/shared/v1/webhooks/events?limit=1" \ Значения: `submit` — Отправка формы - `callback_id: string` (required) — Идентификатор обратного вызова, указанный при открытии представления. Пример: `"timeoff_request_form"` - `private_metadata: string` (required) — Приватные метаданные, указанные при открытии представления. Пример: `"{'timeoff_id':4378}"` - - `chat_id: integer, int32` (required) — Идентификатор чата, в котором было нажатие кнопки, открывшей форму. Значение фиксируется в момент **открытия** формы, а не отправки — если форма провисела открытой длительное время, `chat_id` всё равно ссылается на чат с кнопкой. Поле всегда присутствует в payload. Для форм, открытых до выкатки этого изменения, `chat_id` придёт как `null` — такие формы постепенно вымоются по TTL сохранённого представления (30 дней).. Пример: `9012` + - `chat_id: integer, int32` (required) — Идентификатор чата, в котором была нажата кнопка, открывшая форму. Поле может быть `null` для форм, открытых до выкатки этого поля.. Пример: `9012` - `user_id: integer, int32` (required) — Идентификатор пользователя, который отправил форму. Пример: `1235523` - - `data: Record` (required) — Данные заполненных полей представления. Ключ — `action_id` поля, значение — введённые данные + - `data: Record` (required) — Данные заполненных полей представления. Ключ — `name` блока, значение — введённые данные **Структура значений Record:** - Тип значения: `any` - `webhook_timestamp: integer, int32` (required) — Дата и время отправки вебхука (UTC+0) в формате UNIX. Пример: `1755075544` diff --git a/apps/docs/public/api/bots/update.md b/apps/docs/public/api/bots/update.md index 98c73fb4..75d88f6b 100644 --- a/apps/docs/public/api/bots/update.md +++ b/apps/docs/public/api/bots/update.md @@ -12,7 +12,7 @@ Метод для редактирования бота. -Для редактирования бота вам необходимо знать его `user_id` и указать его в `URL` запроса. Все редактируемые параметры бота указываются в теле запроса. Узнать `user_id` бота можно в настройках бота во вкладке «API». +Для редактирования бота вам необходимо знать его `user_id` и указать его в `URL` запроса. Все редактируемые параметры бота указываются в теле запроса. Вы не можете редактировать бота, настройки которого вам недоступны (поле «Кто может редактировать настройки бота» находится во вкладке «Основное» в настройках бота). @@ -33,7 +33,13 @@ - `bot: object` (required) — Собранный объект параметров редактируемого бота - `webhook: object` (required) — Объект параметров вебхука - - `outgoing_url: string` (required) — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `name: string` — Имя бота. Пример: `"Бот задач"` + - `nickname: string` — Никнейм бота. Должен заканчиваться на `_bot`.. Пример: `"tasks_bot"` + - `outgoing_url: string` — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `events: array of string` — События, на которые подписан бот. Пример: `["message_new"]` + - `trigger_on: string` — Условие срабатывания исходящего вебхука + Значения: `commands` — Только на команды (триггер-слова) из commands, `all_messages` — На все сообщения в чатах, где есть бот, `unfurl` — На развёртывание ссылок (link previews) + - `commands: array of string` — Команды бота (триггер-слова), на которые он реагирует при trigger_on = commands. Пример: `["/task","/help"]` ### Пример @@ -41,7 +47,17 @@ { "bot": { "webhook": { - "outgoing_url": "https://www.website.com/tasks/new" + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task", + "/help" + ] } } } @@ -56,7 +72,17 @@ curl -X PUT "https://api.pachca.com/api/shared/v1/bots/1738816" \ -d '{ "bot": { "webhook": { - "outgoing_url": "https://www.website.com/tasks/new" + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task", + "/help" + ] } } }' @@ -69,9 +95,15 @@ curl -X PUT "https://api.pachca.com/api/shared/v1/bots/1738816" \ **Схема ответа:** - `data: object` (required) — Параметры бота - - `id: integer, int32` (required) — Идентификатор бота. Пример: `1738816` + - `id: integer, int32` (required) — Идентификатор бота (совпадает с `user_id` бота). Пример: `1738816` - `webhook: object` (required) — Объект параметров вебхука + - `name: string` (required) — Имя бота. Пример: `"Бот задач"` + - `nickname: string` (required) — Никнейм бота. Пример: `"tasks_bot"` - `outgoing_url: string` (required) — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `events: array of string` (required) — События, на которые подписан бот. Пример: `["message_new"]` + - `trigger_on: string` (required) — Условие срабатывания исходящего вебхука + Значения: `commands` — Только на команды (триггер-слова) из commands, `all_messages` — На все сообщения в чатах, где есть бот, `unfurl` — На развёртывание ссылок (link previews) + - `commands: array of string` (required) — Команды бота (триггер-слова). Пример: `["/task"]` **Пример ответа:** @@ -80,7 +112,16 @@ curl -X PUT "https://api.pachca.com/api/shared/v1/bots/1738816" \ "data": { "id": 1738816, "webhook": { - "outgoing_url": "https://www.website.com/tasks/new" + "name": "Бот задач", + "nickname": "tasks_bot", + "outgoing_url": "https://www.website.com/tasks/new", + "events": [ + "message_new" + ], + "trigger_on": "commands", + "commands": [ + "/task" + ] } } } diff --git a/apps/docs/public/api/chats/create.md b/apps/docs/public/api/chats/create.md index 2476941f..5644e31b 100644 --- a/apps/docs/public/api/chats/create.md +++ b/apps/docs/public/api/chats/create.md @@ -45,8 +45,7 @@ 86, 18 ], - "channel": true, - "public": false + "channel": true } } ``` @@ -68,8 +67,7 @@ curl "https://api.pachca.com/api/shared/v1/chats" \ 86, 18 ], - "channel": true, - "public": false + "channel": true } }' ``` diff --git a/apps/docs/public/api/llms.txt b/apps/docs/public/api/llms.txt index 710279bc..f1b8ce8f 100644 --- a/apps/docs/public/api/llms.txt +++ b/apps/docs/public/api/llms.txt @@ -107,6 +107,8 @@ - [Открытие представления](https://dev.pachca.com/api/views/open.md): POST /views/open ## Bots +- [Создание бота](https://dev.pachca.com/api/bots/create.md): POST /bots +- [Получение бота](https://dev.pachca.com/api/bots/get.md): GET /bots/{id} - [Редактирование бота](https://dev.pachca.com/api/bots/update.md): PUT /bots/{id} - [История событий](https://dev.pachca.com/api/bots/list-events.md): GET /webhooks/events - [Удаление события](https://dev.pachca.com/api/bots/remove-event.md): DELETE /webhooks/events/{id} diff --git a/apps/docs/public/api/messages/create.md b/apps/docs/public/api/messages/create.md index 6ec58dd3..45f188a9 100644 --- a/apps/docs/public/api/messages/create.md +++ b/apps/docs/public/api/messages/create.md @@ -33,10 +33,12 @@ - `key: string` (required) — Путь к файлу, полученный в результате [загрузки файла](POST /direct_url). Пример: `"attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/logo.png"` - `name: string` (required) — Название файла, которое вы хотите отображать пользователю (рекомендуется писать вместе с расширением). Пример: `"logo.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `size: integer, int32` (required) — Размер файла в байтах, отображаемый пользователю. Пример: `12345` - `width: integer, int32` — Ширина изображения в px (используется в случае, если file_type указан как image). Пример: `800` - `height: integer, int32` — Высота изображения в px (используется в случае, если file_type указан как image). Пример: `600` + - `duration_ms: integer, int32` (min: 1) — Длительность в миллисекундах. Обязательно для голосовых сообщений (`file_type` — `voice`), для других типов не используется.. Пример: `5400` + - `waveform: string` (max length: 256) — Форма волны для визуализации голосового сообщения. Обязательно для голосовых сообщений (`file_type` — `voice`), для других типов не используется.. Пример: `"4,8,12,20,16,10,6,3"` - `buttons: array of array` — Массив строк, каждая из которых представлена массивом кнопок. Максимум 100 кнопок у сообщения, до 8 кнопок в строке.. Пример: `[[{"text":"Подробнее","url":"https://example.com/details"},{"text":"Отлично!","data":"awesome"}]]` - `parent_message_id: integer, int32` — Идентификатор сообщения. Указывается в случае, если вы отправляете ответ на другое сообщение.. Пример: `194270` - `display_avatar_url: string` (max length: 255) — Ссылка на специальную аватарку отправителя для этого сообщения. Использование этого поля возможно только с access_token бота.. Пример: `"https://example.com/avatar.png"` @@ -49,7 +51,6 @@ ```json { "message": { - "entity_type": "discussion", "entity_id": 334, "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)", "files": [ @@ -59,7 +60,9 @@ "file_type": "image", "size": 12345, "width": 800, - "height": 600 + "height": 600, + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3" } ], "buttons": [ @@ -76,10 +79,8 @@ ], "parent_message_id": 194270, "display_avatar_url": "https://example.com/avatar.png", - "display_name": "Бот Поддержки", - "skip_invite_mentions": false - }, - "link_preview": false + "display_name": "Бот Поддержки" + } } ``` @@ -91,7 +92,6 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ -H "Content-Type: application/json" \ -d '{ "message": { - "entity_type": "discussion", "entity_id": 334, "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)", "files": [ @@ -101,7 +101,9 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ "file_type": "image", "size": 12345, "width": 800, - "height": 600 + "height": 600, + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3" } ], "buttons": [ @@ -118,10 +120,8 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ ], "parent_message_id": 194270, "display_avatar_url": "https://example.com/avatar.png", - "display_name": "Бот Поддержки", - "skip_invite_mentions": false - }, - "link_preview": false + "display_name": "Бот Поддержки" + } }' ``` @@ -147,10 +147,14 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ - `key: string` (required) — Путь к файлу. Пример: `"attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png"` - `name: string` (required) — Название файла с расширением. Пример: `"congrat.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `url: string` (required) — Прямая ссылка на скачивание файла. Пример: `"https://pachca-prod-uploads.s3.storage.selcloud.ru/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?response-cache-control=max-age%3D3600%3B&response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=142155_staply%2F20231107%2Fru-1a%2Fs3%2Faws4_request&X-Amz-Date=20231107T160412&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8"` - `width: integer, int32` — Ширина изображения в пикселях. Пример: `1920` - `height: integer, int32` — Высота изображения в пикселях. Пример: `1080` + - `voice_content: object` (required) — Данные голосового сообщения. Заполняется только для голосовых сообщений (`file_type` файла — `voice`), иначе `null`. + - `duration_ms: integer, int32` (required) — Длительность голосового сообщения в миллисекундах. Пример: `5400` + - `waveform: string` (required) — Форма волны (амплитуды) для визуализации голосового сообщения. Пример: `"4,8,12,20,16,10,6,3"` + - `transcript: string` (required) — Расшифровка голосового сообщения в текст. `null`, пока расшифровка не готова или недоступна.. Пример: `"Привет, посмотри пожалуйста последний отчёт"` - `buttons: array of array` (required) — Массив строк, каждая из которых представлена массивом кнопок - `thread: object` (required) — Тред сообщения - `id: integer, int64` (required) — Идентификатор треда. Пример: `265142` @@ -194,6 +198,11 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ "height": 1080 } ], + "voice_content": { + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3", + "transcript": "Привет, посмотри пожалуйста последний отчёт" + }, "buttons": [ [ { diff --git a/apps/docs/public/api/messages/get.md b/apps/docs/public/api/messages/get.md index 3d53d6b5..39e7c655 100644 --- a/apps/docs/public/api/messages/get.md +++ b/apps/docs/public/api/messages/get.md @@ -50,10 +50,14 @@ curl "https://api.pachca.com/api/shared/v1/messages/194275" \ - `key: string` (required) — Путь к файлу. Пример: `"attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png"` - `name: string` (required) — Название файла с расширением. Пример: `"congrat.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `url: string` (required) — Прямая ссылка на скачивание файла. Пример: `"https://pachca-prod-uploads.s3.storage.selcloud.ru/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?response-cache-control=max-age%3D3600%3B&response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=142155_staply%2F20231107%2Fru-1a%2Fs3%2Faws4_request&X-Amz-Date=20231107T160412&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8"` - `width: integer, int32` — Ширина изображения в пикселях. Пример: `1920` - `height: integer, int32` — Высота изображения в пикселях. Пример: `1080` + - `voice_content: object` (required) — Данные голосового сообщения. Заполняется только для голосовых сообщений (`file_type` файла — `voice`), иначе `null`. + - `duration_ms: integer, int32` (required) — Длительность голосового сообщения в миллисекундах. Пример: `5400` + - `waveform: string` (required) — Форма волны (амплитуды) для визуализации голосового сообщения. Пример: `"4,8,12,20,16,10,6,3"` + - `transcript: string` (required) — Расшифровка голосового сообщения в текст. `null`, пока расшифровка не готова или недоступна.. Пример: `"Привет, посмотри пожалуйста последний отчёт"` - `buttons: array of array` (required) — Массив строк, каждая из которых представлена массивом кнопок - `thread: object` (required) — Тред сообщения - `id: integer, int64` (required) — Идентификатор треда. Пример: `265142` @@ -97,6 +101,11 @@ curl "https://api.pachca.com/api/shared/v1/messages/194275" \ "height": 1080 } ], + "voice_content": { + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3", + "transcript": "Привет, посмотри пожалуйста последний отчёт" + }, "buttons": [ [ { diff --git a/apps/docs/public/api/messages/list.md b/apps/docs/public/api/messages/list.md index a49b15a5..edb3dd71 100644 --- a/apps/docs/public/api/messages/list.md +++ b/apps/docs/public/api/messages/list.md @@ -55,10 +55,14 @@ curl "https://api.pachca.com/api/shared/v1/messages?chat_id=198&sort=id&order=de - `key: string` (required) — Путь к файлу. Пример: `"attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png"` - `name: string` (required) — Название файла с расширением. Пример: `"congrat.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `url: string` (required) — Прямая ссылка на скачивание файла. Пример: `"https://pachca-prod-uploads.s3.storage.selcloud.ru/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?response-cache-control=max-age%3D3600%3B&response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=142155_staply%2F20231107%2Fru-1a%2Fs3%2Faws4_request&X-Amz-Date=20231107T160412&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8"` - `width: integer, int32` — Ширина изображения в пикселях. Пример: `1920` - `height: integer, int32` — Высота изображения в пикселях. Пример: `1080` + - `voice_content: object` (required) — Данные голосового сообщения. Заполняется только для голосовых сообщений (`file_type` файла — `voice`), иначе `null`. + - `duration_ms: integer, int32` (required) — Длительность голосового сообщения в миллисекундах. Пример: `5400` + - `waveform: string` (required) — Форма волны (амплитуды) для визуализации голосового сообщения. Пример: `"4,8,12,20,16,10,6,3"` + - `transcript: string` (required) — Расшифровка голосового сообщения в текст. `null`, пока расшифровка не готова или недоступна.. Пример: `"Привет, посмотри пожалуйста последний отчёт"` - `buttons: array of array` (required) — Массив строк, каждая из которых представлена массивом кнопок - `thread: object` (required) — Тред сообщения - `id: integer, int64` (required) — Идентификатор треда. Пример: `265142` @@ -109,6 +113,11 @@ curl "https://api.pachca.com/api/shared/v1/messages?chat_id=198&sort=id&order=de "height": 1080 } ], + "voice_content": { + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3", + "transcript": "Привет, посмотри пожалуйста последний отчёт" + }, "buttons": [ [ { diff --git a/apps/docs/public/api/messages/update.md b/apps/docs/public/api/messages/update.md index 92f70aff..9c3c1b61 100644 --- a/apps/docs/public/api/messages/update.md +++ b/apps/docs/public/api/messages/update.md @@ -34,10 +34,13 @@ - `files: array of object` — Прикрепляемые файлы - `key: string` (required) — Путь к файлу, полученный в результате [загрузки файла](POST /direct_url). Пример: `"attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/logo.png"` - `name: string` (required) — Название файла, которое вы хотите отображать пользователю (рекомендуется писать вместе с расширением). Пример: `"logo.png"` - - `file_type: string` — Тип файла: файл (file), изображение (image). Пример: `"image"` + - `file_type: string` — Тип файла + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `size: integer, int32` — Размер файла в байтах, отображаемый пользователю. Пример: `12345` - `width: integer, int32` — Ширина изображения в px (используется в случае, если file_type указан как image). Пример: `800` - `height: integer, int32` — Высота изображения в px (используется в случае, если file_type указан как image). Пример: `600` + - `duration_ms: integer, int32` (min: 1) — Длительность в миллисекундах. Обязательно для голосовых сообщений (`file_type` — `voice`), для других типов не используется.. Пример: `5400` + - `waveform: string` (max length: 256) — Форма волны для визуализации голосового сообщения. Обязательно для голосовых сообщений (`file_type` — `voice`), для других типов не используется.. Пример: `"4,8,12,20,16,10,6,3"` - `buttons: array of array` — Массив строк, каждая из которых представлена массивом кнопок. Максимум 100 кнопок у сообщения, до 8 кнопок в строке. Для удаления кнопок пришлите пустой массив.. Пример: `[[{"text":"Подробнее","url":"https://example.com/details"}]]` - `display_avatar_url: string` — Ссылка на специальную аватарку отправителя для этого сообщения. Использование этого поля возможно только с access_token бота.. Пример: `"https://example.com/avatar.png"` - `display_name: string` — Полное специальное имя отправителя для этого сообщения. Использование этого поля возможно только с access_token бота.. Пример: `"Бот Поддержки"` @@ -55,7 +58,9 @@ "file_type": "image", "size": 12345, "width": 800, - "height": 600 + "height": 600, + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3" } ], "buttons": [ @@ -88,7 +93,9 @@ curl -X PUT "https://api.pachca.com/api/shared/v1/messages/194275" \ "file_type": "image", "size": 12345, "width": 800, - "height": 600 + "height": 600, + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3" } ], "buttons": [ @@ -127,10 +134,14 @@ curl -X PUT "https://api.pachca.com/api/shared/v1/messages/194275" \ - `key: string` (required) — Путь к файлу. Пример: `"attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png"` - `name: string` (required) — Название файла с расширением. Пример: `"congrat.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `url: string` (required) — Прямая ссылка на скачивание файла. Пример: `"https://pachca-prod-uploads.s3.storage.selcloud.ru/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?response-cache-control=max-age%3D3600%3B&response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=142155_staply%2F20231107%2Fru-1a%2Fs3%2Faws4_request&X-Amz-Date=20231107T160412&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8"` - `width: integer, int32` — Ширина изображения в пикселях. Пример: `1920` - `height: integer, int32` — Высота изображения в пикселях. Пример: `1080` + - `voice_content: object` (required) — Данные голосового сообщения. Заполняется только для голосовых сообщений (`file_type` файла — `voice`), иначе `null`. + - `duration_ms: integer, int32` (required) — Длительность голосового сообщения в миллисекундах. Пример: `5400` + - `waveform: string` (required) — Форма волны (амплитуды) для визуализации голосового сообщения. Пример: `"4,8,12,20,16,10,6,3"` + - `transcript: string` (required) — Расшифровка голосового сообщения в текст. `null`, пока расшифровка не готова или недоступна.. Пример: `"Привет, посмотри пожалуйста последний отчёт"` - `buttons: array of array` (required) — Массив строк, каждая из которых представлена массивом кнопок - `thread: object` (required) — Тред сообщения - `id: integer, int64` (required) — Идентификатор треда. Пример: `265142` @@ -174,6 +185,11 @@ curl -X PUT "https://api.pachca.com/api/shared/v1/messages/194275" \ "height": 1080 } ], + "voice_content": { + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3", + "transcript": "Привет, посмотри пожалуйста последний отчёт" + }, "buttons": [ [ { diff --git a/apps/docs/public/api/models.md b/apps/docs/public/api/models.md index 956ff68a..2de758d6 100644 --- a/apps/docs/public/api/models.md +++ b/apps/docs/public/api/models.md @@ -213,10 +213,14 @@ - `key: string` (required) — Путь к файлу. Пример: `"attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png"` - `name: string` (required) — Название файла с расширением. Пример: `"congrat.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `url: string` (required) — Прямая ссылка на скачивание файла. Пример: `"https://pachca-prod-uploads.s3.storage.selcloud.ru/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?response-cache-control=max-age%3D3600%3B&response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=142155_staply%2F20231107%2Fru-1a%2Fs3%2Faws4_request&X-Amz-Date=20231107T160412&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8"` - `width: integer, int32` — Ширина изображения в пикселях. Пример: `1920` - `height: integer, int32` — Высота изображения в пикселях. Пример: `1080` +- `voice_content: object` (required) — Данные голосового сообщения. Заполняется только для голосовых сообщений (`file_type` файла — `voice`), иначе `null`. + - `duration_ms: integer, int32` (required) — Длительность голосового сообщения в миллисекундах. Пример: `5400` + - `waveform: string` (required) — Форма волны (амплитуды) для визуализации голосового сообщения. Пример: `"4,8,12,20,16,10,6,3"` + - `transcript: string` (required) — Расшифровка голосового сообщения в текст. `null`, пока расшифровка не готова или недоступна.. Пример: `"Привет, посмотри пожалуйста последний отчёт"` - `buttons: array of array` (required) — Массив строк, каждая из которых представлена массивом кнопок - `thread: object` (required) — Тред сообщения - `id: integer, int64` (required) — Идентификатор треда. Пример: `265142` @@ -294,7 +298,7 @@ - `callback_id: string` (max length: 255) — Необязательный идентификатор для распознавания этого представления, который будет отправлен в ваше приложение при отправке пользователем заполненной формы. Используйте это поле, например, для понимания, какую форму должен был заполнить пользователь.. Пример: `"timeoff_reguest_form"` - `view: object` (required) — Собранный объект представления - `title: string` (required, max length: 24) — Заголовок представления. Пример: `"Уведомление об отпуске"` - - `close_text: string` (default: Отменить, max length: 24) — Текст кнопки закрытия представления. Пример: `"Закрыть"` + - `close_text: string` (default: Отменить, max length: 24) — Текст кнопки закрытия представления. Отображается только в десктоп-вебе. В мобильных приложениях (iOS/Android) кнопка закрытия — это крестик в шапке, и заданный текст там не показывается.. Пример: `"Закрыть"` - `submit_text: string` (default: Отправить, max length: 24) — Текст кнопки отправки формы. Пример: `"Отправить заявку"` - `blocks: array (union)` (required, max items: 100) — Массив блоков представления **Возможные типы элементов:** @@ -334,7 +338,6 @@ - `options: array of object` (max items: 100) — Массив доступных пунктов в выпадающем списке - `text: string` (required, max length: 75) — Отображаемый текст - `value: string` (required, max length: 150) — Уникальное строковое значение, которое будет передано в ваше приложение при выборе этого пункта - - `description: string` (max length: 75) — Пояснение, которое будет указано серым цветом в этом пункте под отображаемым текстом - `selected: boolean` — Изначально выбранный пункт. Только один пункт может быть выбран. - `required: boolean` — Обязательность - `hint: string` (max length: 2000) — Подсказка, которая отображается под выпадающим списком серым цветом @@ -391,13 +394,21 @@ ## Параметры бота +- [Создание бота](POST /bots) +- [Получение бота](GET /bots/{id}) - [Редактирование бота](PUT /bots/{id}) Параметры бота -- `id: integer, int32` (required) — Идентификатор бота. Пример: `1738816` +- `id: integer, int32` (required) — Идентификатор бота (совпадает с `user_id` бота). Пример: `1738816` - `webhook: object` (required) — Объект параметров вебхука + - `name: string` (required) — Имя бота. Пример: `"Бот задач"` + - `nickname: string` (required) — Никнейм бота. Пример: `"tasks_bot"` - `outgoing_url: string` (required) — URL исходящего вебхука. Пример: `"https://www.website.com/tasks/new"` + - `events: array of string` (required) — События, на которые подписан бот. Пример: `["message_new"]` + - `trigger_on: string` (required) — Условие срабатывания исходящего вебхука + Значения: `commands` — Только на команды (триггер-слова) из commands, `all_messages` — На все сообщения в чатах, где есть бот, `unfurl` — На развёртывание ссылок (link previews) + - `commands: array of string` (required) — Команды бота (триггер-слова). Пример: `["/task"]` ## Событие исходящего вебхука @@ -441,7 +452,7 @@ - `code: string` (required) — Emoji символ реакции. Пример: `"👍"` - `name: string` (required) — Название реакции. Пример: `"thumbsup"` - `user_id: integer, int32` (required) — Идентификатор пользователя, который добавил или удалил реакцию. Пример: `2345` - - `created_at: date-time` (required) — Дата и время создания сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. Пример: `"2025-05-15T14:30:00.000Z"` + - `created_at: date-time` (required) — Дата и время добавления реакции (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. Поле присутствует и для события удаления реакции.. Пример: `"2025-05-15T14:30:00.000Z"` - `webhook_timestamp: integer, int32` (required) — Дата и время отправки вебхука (UTC+0) в формате UNIX. Пример: `1747574400` - **ButtonWebhookPayload**: Структура исходящего вебхука о нажатии кнопки - `type: string` (required) — Тип объекта. Пример: `"button"` @@ -461,9 +472,9 @@ Значения: `submit` — Отправка формы - `callback_id: string` (required) — Идентификатор обратного вызова, указанный при открытии представления. Пример: `"timeoff_request_form"` - `private_metadata: string` (required) — Приватные метаданные, указанные при открытии представления. Пример: `"{'timeoff_id':4378}"` - - `chat_id: integer, int32` (required) — Идентификатор чата, в котором было нажатие кнопки, открывшей форму. Значение фиксируется в момент **открытия** формы, а не отправки — если форма провисела открытой длительное время, `chat_id` всё равно ссылается на чат с кнопкой. Поле всегда присутствует в payload. Для форм, открытых до выкатки этого изменения, `chat_id` придёт как `null` — такие формы постепенно вымоются по TTL сохранённого представления (30 дней).. Пример: `9012` + - `chat_id: integer, int32` (required) — Идентификатор чата, в котором была нажата кнопка, открывшая форму. Поле может быть `null` для форм, открытых до выкатки этого поля.. Пример: `9012` - `user_id: integer, int32` (required) — Идентификатор пользователя, который отправил форму. Пример: `1235523` - - `data: Record` (required) — Данные заполненных полей представления. Ключ — `action_id` поля, значение — введённые данные + - `data: Record` (required) — Данные заполненных полей представления. Ключ — `name` блока, значение — введённые данные **Структура значений Record:** - Тип значения: `any` - `webhook_timestamp: integer, int32` (required) — Дата и время отправки вебхука (UTC+0) в формате UNIX. Пример: `1755075544` @@ -554,7 +565,7 @@ - `message_id: integer, int32` (required) — Идентификатор сообщения - `chat_id: integer, int32` (required) — Идентификатор чата - `user_id: integer, int32` (required) — Идентификатор пользователя - - `action_message: string` (required) — Описание действия + - `action_message: string` (required) — Описание действия. `null`, если у действия правила текст не задан. - `conditions_matched: boolean` (required) — Результат проверки условий правила (true — условия сработали) - **AuditDetailsSearch**: При: search_users_api, search_chats_api, search_messages_api - `search_type: string` (required) — Тип поиска diff --git a/apps/docs/public/api/search/list-messages.md b/apps/docs/public/api/search/list-messages.md index 15e00bd4..7c5e9b08 100644 --- a/apps/docs/public/api/search/list-messages.md +++ b/apps/docs/public/api/search/list-messages.md @@ -58,10 +58,14 @@ curl "https://api.pachca.com/api/shared/v1/search/messages?query=футболк - `key: string` (required) — Путь к файлу. Пример: `"attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png"` - `name: string` (required) — Название файла с расширением. Пример: `"congrat.png"` - `file_type: string` (required) — Тип файла - Значения: `file` — Обычный файл, `image` — Изображение + Значения: `file` — Обычный файл, `image` — Изображение, `audio` — Аудиофайл, `voice` — Голосовое сообщение - `url: string` (required) — Прямая ссылка на скачивание файла. Пример: `"https://pachca-prod-uploads.s3.storage.selcloud.ru/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?response-cache-control=max-age%3D3600%3B&response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=142155_staply%2F20231107%2Fru-1a%2Fs3%2Faws4_request&X-Amz-Date=20231107T160412&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8"` - `width: integer, int32` — Ширина изображения в пикселях. Пример: `1920` - `height: integer, int32` — Высота изображения в пикселях. Пример: `1080` + - `voice_content: object` (required) — Данные голосового сообщения. Заполняется только для голосовых сообщений (`file_type` файла — `voice`), иначе `null`. + - `duration_ms: integer, int32` (required) — Длительность голосового сообщения в миллисекундах. Пример: `5400` + - `waveform: string` (required) — Форма волны (амплитуды) для визуализации голосового сообщения. Пример: `"4,8,12,20,16,10,6,3"` + - `transcript: string` (required) — Расшифровка голосового сообщения в текст. `null`, пока расшифровка не готова или недоступна.. Пример: `"Привет, посмотри пожалуйста последний отчёт"` - `buttons: array of array` (required) — Массив строк, каждая из которых представлена массивом кнопок - `thread: object` (required) — Тред сообщения - `id: integer, int64` (required) — Идентификатор треда. Пример: `265142` @@ -110,6 +114,11 @@ curl "https://api.pachca.com/api/shared/v1/search/messages?query=футболк "height": 1080 } ], + "voice_content": { + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3", + "transcript": "Привет, посмотри пожалуйста последний отчёт" + }, "buttons": [ [ { diff --git a/apps/docs/public/api/security/list.md b/apps/docs/public/api/security/list.md index 6200cd05..7ffff11b 100644 --- a/apps/docs/public/api/security/list.md +++ b/apps/docs/public/api/security/list.md @@ -91,7 +91,7 @@ curl "https://api.pachca.com/api/shared/v1/audit_events?start_time=2025-05-01T09 - `message_id: integer, int32` (required) — Идентификатор сообщения - `chat_id: integer, int32` (required) — Идентификатор чата - `user_id: integer, int32` (required) — Идентификатор пользователя - - `action_message: string` (required) — Описание действия + - `action_message: string` (required) — Описание действия. `null`, если у действия правила текст не задан. - `conditions_matched: boolean` (required) — Результат проверки условий правила (true — условия сработали) - **AuditDetailsSearch**: При: search_users_api, search_chats_api, search_messages_api - `search_type: string` (required) — Тип поиска diff --git a/apps/docs/public/api/views/open.md b/apps/docs/public/api/views/open.md index 37e34cd4..1eebce1f 100644 --- a/apps/docs/public/api/views/open.md +++ b/apps/docs/public/api/views/open.md @@ -29,7 +29,7 @@ - `callback_id: string` (max length: 255) — Необязательный идентификатор для распознавания этого представления, который будет отправлен в ваше приложение при отправке пользователем заполненной формы. Используйте это поле, например, для понимания, какую форму должен был заполнить пользователь.. Пример: `"timeoff_reguest_form"` - `view: object` (required) — Собранный объект представления - `title: string` (required, max length: 24) — Заголовок представления. Пример: `"Уведомление об отпуске"` - - `close_text: string` (default: Отменить, max length: 24) — Текст кнопки закрытия представления. Пример: `"Закрыть"` + - `close_text: string` (default: Отменить, max length: 24) — Текст кнопки закрытия представления. Отображается только в десктоп-вебе. В мобильных приложениях (iOS/Android) кнопка закрытия — это крестик в шапке, и заданный текст там не показывается.. Пример: `"Закрыть"` - `submit_text: string` (default: Отправить, max length: 24) — Текст кнопки отправки формы. Пример: `"Отправить заявку"` - `blocks: array (union)` (required, max items: 100) — Массив блоков представления **Возможные типы элементов:** @@ -69,7 +69,6 @@ - `options: array of object` (max items: 100) — Массив доступных пунктов в выпадающем списке - `text: string` (required, max length: 75) — Отображаемый текст - `value: string` (required, max length: 150) — Уникальное строковое значение, которое будет передано в ваше приложение при выборе этого пункта - - `description: string` (max length: 75) — Пояснение, которое будет указано серым цветом в этом пункте под отображаемым текстом - `selected: boolean` — Изначально выбранный пункт. Только один пункт может быть выбран. - `required: boolean` — Обязательность - `hint: string` (max length: 2000) — Подсказка, которая отображается под выпадающим списком серым цветом @@ -171,7 +170,6 @@ { "text": "Ничего", "value": "nothing", - "description": "Каждый день бот будет присылать список новых задач в вашей команде", "selected": true } ], @@ -293,7 +291,6 @@ curl "https://api.pachca.com/api/shared/v1/views/open" \ { "text": "Ничего", "value": "nothing", - "description": "Каждый день бот будет присылать список новых задач в вашей команде", "selected": true } ], diff --git a/apps/docs/public/guides/bots/setup.md b/apps/docs/public/guides/bots/setup.md index 281a640d..07948dec 100644 --- a/apps/docs/public/guides/bots/setup.md +++ b/apps/docs/public/guides/bots/setup.md @@ -5,9 +5,14 @@ # Создание и настройка -## Создание бота +Бота можно создать двумя способами: -> **Внимание:** Создание и настройка ботов доступны в веб-версии и десктопном приложении Пачки. В мобильных приложениях (iOS и Android) эта возможность недоступна. +- **Через интерфейс** — больше настроек (тип бота, аватар, доступы, шаблоны входящего вебхука) и наглядная пошаговая форма. Подходит для разовой ручной настройки. +- **Через API** ([Создание бота](POST /bots)) — программно, без интерфейса. Подходит для автоматизации: завести бота из своего сервиса или скрипта и сразу получить `access_token`. + +## Создание бота через интерфейс + +> **Внимание:** Создание и настройка ботов через интерфейс доступны в веб-версии и десктопном приложении Пачки. В мобильных приложениях (iOS и Android) эта возможность недоступна. Для создания бота перейдите в **Автоматизации** > **Интеграции** > **Чат-боты и Вебхуки** и нажмите кнопку **«+»**. @@ -44,6 +49,23 @@ Для получения событий от Пачки перейдите на вкладку **Исходящий Webhook**: укажите **Webhook URL**, на который будут приходить уведомления, и выберите типы событий (новые сообщения, реакции, нажатия кнопок и другие). Подробнее — в разделе [Исходящие вебхуки](/guides/webhook/overview). +## Создание бота через API + +Бота можно создать программно методом [Создание бота](POST /bots) — без интерфейса. Это удобно, когда нужно завести бота из своего сервиса или скрипта. + + + ### Шаг 1. Отправьте запрос на создание + +Передайте параметры бота в объекте `bot.webhook`: имя, никнейм, Webhook URL, список событий и команды. Никнейм должен заканчиваться на `_bot`. + + + ### Шаг 2. Сохраните access_token + +В ответе вы получите `access_token` бота — сразу сохраните его. Повторно получить токен вы сможете только через интерфейс (вкладка **API** настроек бота), там же его можно перевыпустить. Вместе с токеном придёт `id` бота (его `user_id`). + + +Получить параметры существующего бота можно методом [Получение бота](GET /bots/{id}), а изменить — методом [Редактирование бота](PUT /bots/{id}). + ## Профиль бота Бот, как и любой участник пространства, имеет свой профиль. В нём отображаются имя, аватар, никнейм, статус и список общих чатов с ботом. Профиль бота можно редактировать — изменить имя, никнейм и другие поля. diff --git a/apps/docs/public/guides/buttons.md b/apps/docs/public/guides/buttons.md index 137f332c..99ce5843 100644 --- a/apps/docs/public/guides/buttons.md +++ b/apps/docs/public/guides/buttons.md @@ -76,7 +76,6 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ -H "Content-Type: application/json" \ -d '{ "message": { - "entity_type": "discussion", "entity_id": 334, "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)", "files": [ @@ -86,7 +85,9 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ "file_type": "image", "size": 12345, "width": 800, - "height": 600 + "height": 600, + "duration_ms": 5400, + "waveform": "4,8,12,20,16,10,6,3" } ], "buttons": [ @@ -103,10 +104,8 @@ curl "https://api.pachca.com/api/shared/v1/messages" \ ], "parent_message_id": 194270, "display_avatar_url": "https://example.com/avatar.png", - "display_name": "Бот Поддержки", - "skip_invite_mentions": false - }, - "link_preview": false + "display_name": "Бот Поддержки" + } }' ``` diff --git a/apps/docs/public/guides/cli/commands.md b/apps/docs/public/guides/cli/commands.md index 5d11e2fc..fc723f13 100644 --- a/apps/docs/public/guides/cli/commands.md +++ b/apps/docs/public/guides/cli/commands.md @@ -29,6 +29,8 @@ dev.pachca.com/api/members/add → pachca members add | `pachca auth logout` | Удаление сохранённого профиля | | `pachca auth status` | Статус текущего профиля | | `pachca auth switch` | Переключение активного профиля | +| `pachca bots create` | `POST` Создание бота | +| `pachca bots get` | `GET` Получение бота | | `pachca bots list-events` | `GET` История событий | | `pachca bots remove-event` | `DELETE` Удаление события | | `pachca bots update` | `PUT` Редактирование бота | diff --git a/apps/docs/public/guides/cli/installation.md b/apps/docs/public/guides/cli/installation.md index 44797b9c..92d42470 100644 --- a/apps/docs/public/guides/cli/installation.md +++ b/apps/docs/public/guides/cli/installation.md @@ -64,7 +64,7 @@ pachca doctor # ✔ Конфиг ~/.config/pachca/config.toml (права: 600) # ✔ Профиль personal (user: Иван Иванов) # ✔ Токен действителен (11 скоупов) -# ✔ CLI v2026.5.2 (актуальная версия) +# ✔ CLI v2026.6.0 (актуальная версия) ``` ## Обновление diff --git a/apps/docs/public/guides/dlp.md b/apps/docs/public/guides/dlp.md index a12b4f7d..e0a097c2 100644 --- a/apps/docs/public/guides/dlp.md +++ b/apps/docs/public/guides/dlp.md @@ -193,7 +193,7 @@ - `message_id: integer, int32` (required) — Идентификатор сообщения - `chat_id: integer, int32` (required) — Идентификатор чата - `user_id: integer, int32` (required) — Идентификатор пользователя -- `action_message: string` (required) — Описание действия +- `action_message: string` (required) — Описание действия. `null`, если у действия правила текст не задан. - `conditions_matched: boolean` (required) — Результат проверки условий правила (true — условия сработали) diff --git a/apps/docs/public/guides/forms/blocks.md b/apps/docs/public/guides/forms/blocks.md index 1bc25473..4982ac72 100644 --- a/apps/docs/public/guides/forms/blocks.md +++ b/apps/docs/public/guides/forms/blocks.md @@ -102,7 +102,6 @@ - `options: array of object` (max items: 100) — Массив доступных пунктов в выпадающем списке - `text: string` (required, max length: 75) — Отображаемый текст. Пример: `"Ничего"` - `value: string` (required, max length: 150) — Уникальное строковое значение, которое будет передано в ваше приложение при выборе этого пункта. Пример: `"nothing"` - - `description: string` (max length: 75) — Пояснение, которое будет указано серым цветом в этом пункте под отображаемым текстом. Пример: `"Каждый день бот будет присылать список новых задач в вашей команде"` - `selected: boolean` — Изначально выбранный пункт. Только один пункт может быть выбран.. Пример: `true` - `required: boolean` — Обязательность. Пример: `false` - `hint: string` (max length: 2000) — Подсказка, которая отображается под выпадающим списком серым цветом. Пример: `"Выберите одну из команд"` diff --git a/apps/docs/public/guides/forms/handling.md b/apps/docs/public/guides/forms/handling.md index e135e2ca..82a41af4 100644 --- a/apps/docs/public/guides/forms/handling.md +++ b/apps/docs/public/guides/forms/handling.md @@ -35,9 +35,9 @@ Значения: `submit` — Отправка формы - `callback_id: string` (required) — Идентификатор обратного вызова, указанный при открытии представления. Пример: `"timeoff_request_form"` - `private_metadata: string` (required) — Приватные метаданные, указанные при открытии представления. Пример: `"{'timeoff_id':4378}"` -- `chat_id: integer, int32` (required) — Идентификатор чата, в котором было нажатие кнопки, открывшей форму. Значение фиксируется в момент **открытия** формы, а не отправки — если форма провисела открытой длительное время, `chat_id` всё равно ссылается на чат с кнопкой. Поле всегда присутствует в payload. Для форм, открытых до выкатки этого изменения, `chat_id` придёт как `null` — такие формы постепенно вымоются по TTL сохранённого представления (30 дней).. Пример: `9012` +- `chat_id: integer, int32` (required) — Идентификатор чата, в котором была нажата кнопка, открывшая форму. Поле может быть `null` для форм, открытых до выкатки этого поля.. Пример: `9012` - `user_id: integer, int32` (required) — Идентификатор пользователя, который отправил форму. Пример: `1235523` -- `data: Record` (required) — Данные заполненных полей представления. Ключ — `action_id` поля, значение — введённые данные +- `data: Record` (required) — Данные заполненных полей представления. Ключ — `name` блока, значение — введённые данные **Структура значений Record:** - Тип значения: `any` - `webhook_timestamp: integer, int32` (required) — Дата и время отправки вебхука (UTC+0) в формате UNIX. Пример: `1755075544` diff --git a/apps/docs/public/guides/quickstart.md b/apps/docs/public/guides/quickstart.md index 99bedee4..37bcc90a 100644 --- a/apps/docs/public/guides/quickstart.md +++ b/apps/docs/public/guides/quickstart.md @@ -60,8 +60,7 @@ curl "https://api.pachca.com/api/shared/v1/chats" \ 86, 18 ], - "channel": true, - "public": false + "channel": true } }' ``` diff --git a/apps/docs/public/guides/sdk/csharp.md b/apps/docs/public/guides/sdk/csharp.md index e304b1f2..70d7eb8d 100644 --- a/apps/docs/public/guides/sdk/csharp.md +++ b/apps/docs/public/guides/sdk/csharp.md @@ -130,6 +130,8 @@ using var client = new PachcaClient("YOUR_TOKEN", "https://custom-api.example.co | `client.Tasks.UpdateTaskAsync()` | [Редактирование напоминания](/api/tasks/update) | | `client.Tasks.DeleteTaskAsync()` | [Удаление напоминания](/api/tasks/delete) | | `client.Views.OpenViewAsync()` | [Открытие представления](/api/views/open) | +| `client.Bots.CreateBotAsync()` | [Создание бота](/api/bots/create) | +| `client.Bots.GetBotAsync()` | [Получение бота](/api/bots/get) | | `client.Bots.GetWebhookEventsAsync()` | [История событий](/api/bots/list-events) | | `client.Bots.UpdateBotAsync()` | [Редактирование бота](/api/bots/update) | | `client.Bots.DeleteWebhookEventAsync()` | [Удаление события](/api/bots/remove-event) | @@ -402,7 +404,9 @@ var request = new MessageCreateRequest FileType = FileType.Image, Size = 12345, Width = 800, - Height = 600 + Height = 600, + DurationMs = 5400, + Waveform = "4,8,12,20,16,10,6,3" } }, Buttons = new List> { new List