API messages

Каждое действие имеет отдельную capability. Разрешение на перехват текста не даёт автоматического чтения истории, отправки или удаления сообщений.

Перед отправкой

Нужно messages.intercept / activeComposer.

await api.messages.beforeSend({ id: "replace", priority: 0 }, input => {
  if (input.text === ".hello") return { text: "Привет!" };
  if (input.text === ".cancel") return { cancel: true };
  return {};
});

Обработчики выполняются в определённом порядке. Замена — обычный текст до 4096 UTF-16 единиц. Медиа без текста, слишком большие и неподдерживаемые rich-черновики не входят в этот перехват. При ошибке или изменившемся чате черновик сохраняется, а исходная команда не отправляется скрыто.

Отправить текст

Нужно messages.send / chosenRecipient. Отправка идёт в текущий нативный чат от выбранной в нём send-as идентичности.

const result = await api.messages.send({ text: "Готово" });

Результат { status: "queued" } означает очередь отправки. Это не подтверждение доставки. Платные действия не выполняются этим методом.

Читать выбранные сообщения

Нужно messages.read / selectedChats и явный нативный контекст.

const selected = await api.messages.read();

Это ограниченные выбранные снимки с непрозрачными handles, а не произвольный запрос истории по chat ID.

Изменить выбранное сообщение

Нужно messages.edit / selectedMessages. В команде меню сообщения можно не передавать handle.

await api.messages.edit({ text: "Исправленный текст" });

Проверяются актуальное сообщение и обычные права Telegram. Новый текст простой: форматирование, ссылки как entities и custom emoji не сохраняются.

Удалить для всех

Нужно messages.delete / selectedMessages.

await api.messages.delete();

Хост проверяет право удаления для всех. При отсутствии права он не подменяет действие локальным удалением. Результат deletionRequested означает запрос нативного удаления.

Лимиты

Отправка, изменение и удаление совместно ограничены пятью действиями за десять секунд и двадцатью в минуту на плагин. Handles прочитанных сообщений истекают через 60 секунд и расходуются одной мутацией.

Пример полного набора — message-tools в готовых проектах.