Три неточности в документации, найденные при живом тестировании бота

[Prontsevich]

Мы пишем бота на Python поверх Shared API (не через @pachca/cli) и вендорим
скиллы из этого репозитория к себе, поэтому читаем их внимательно. При
тестировании против живого API 2026-08-07 нашлись три расхождения между
документацией и поведением. Всё проверено против main сегодня, 2026-08-10.

Пункты независимы — если удобнее для трекинга, с радостью разнесём на отдельные
issues.

---

1. Лимит длины content нигде не задокументирован

POST /messages (MessageOperations_createMessage) отклоняет длинное сообщение,
но ни спека, ни документация не называют предела.

Лимит — 40 000 байт. Само приложение о нём знает: клиент Пачки показывает
уведомление с этим числом. В документации для интеграторов его нет.

Проверено на живом API 2026-08-07:

Размер content	Ответ
39 998 байт	201
40 002 байта	422, errors[].key = "message.content"

Единица измерения — байты, не символы. Для UTF-8 это значит, что кириллица
упирается в предел примерно на 20 000 символах, а эмодзи — примерно на 10 000.
Любая проверка на стороне клиента должна мерить len(text.encode()), и об этом
невозможно догадаться из документации.

Где сейчас пусто:

• MessageCreateRequest.content и MessageUpdateRequest.content в
  openapi.yaml — type: string без maxLength. Для сравнения, у кнопок
  text и data maxLength: 255 проставлен, то есть механизм в спеке есть и
  применяется избирательно.
• Страница https://dev.pachca.com/api/messages/create — предела не называет.
  Лимит 100 кнопок и 8 в строке там описан, а этот нет.

Почему это заметно на практике: у нас бот пересылает в чат ответ языковой
модели. Ответ иногда выходит длиннее предела, вызов к модели при этом успешный и
уже оплачен, а пользователь видит «не получилось обработать» — потому что
единственный способ узнать о лимите заранее был бы наткнуться на него в бою.
Мы и наткнулись.

Просьба: проставить maxLength в спеке и назвать лимит в описании поля.

---

2. pachca-bots/SKILL.md называет заголовок подписи X-Signature

Во фронтматтере skills/pachca-bots/SKILL.md:

проверить подпись вебхука (X-Signature), обработать callback нажатия кнопки или

Правильное имя — Pachca-Signature. Так говорят три источника, включая ваши
собственные:

• skills/pachca-bots/references/webhook-events.md — дважды,
  в том числе в рабочем примере: request.headers['pachca-signature']
• https://dev.pachca.com/guides/webhook/handler — «передаётся в заголовке
  Pachca-Signature»
• живой API: наш обработчик матчит Pachca-Signature и принимает боевые вебхуки

Опечатка стоит дороже, чем кажется, именно из-за формата. Фронтматтер скилла —
это то, что агент читает первым, а часто и единственным: описание попадает в
контекст при выборе скилла, а references/ подтягиваются уже по необходимости.
Агент, написавший верификацию подписи по описанию, получит код, который молча не
проверяет ничего — худший вид отказа для проверки подписи.

Правка в одно слово, но skills/** у вас генерируется
(apps/docs/scripts/skills/generate.ts), а где живёт исходная строка, снаружи не
видно.

---

3. Рецепт ответа в личку умалчивает про parent_message_id

В skills/pachca-messages/references/reply-to-user-who-messaged-the-bot.md
parent_message_id показан для thread и discussion, но не для DM:

2. DM (`entity_type: "user"`): ответь личным сообщением:
   pachca messages create --entity-type=user --entity-id=<user_id> --content="Ответ"

Читается как «в личке привязать ответ к сообщению нельзя». На самом деле Пачка
это принимает: проверено живьём 2026-08-07 — с entity_type: "user" и
parent_message_id API отвечает 2xx, ответ визуально привязан к родительскому
сообщению. Тред при этом не создаётся, сообщение возвращается с thread: null.

Само описание поля на https://dev.pachca.com/api/messages/create нейтрально и
ничего не запрещает — расхождение только в рецепте.

Просьба: добавить --parent-message-id в пример для DM или явно сказать, что он
там тоже работает.

---

Спасибо за то, что спека и скиллы вообще существуют и лежат открыто, — с ними
интеграция получилась заметно быстрее, чем обычно бывает.