Summary

Telegram's sendPhoto API compresses images, which degrades quality for screenshots, diagrams, and other PNG files. There is currently no way to send an image as a document (uncompressed) via message.send.

This feature adds a --force-document flag to message.send that routes image media through sendDocument instead of sendPhoto, preserving the original file quality.

Use Case

• Sending PNG screenshots without lossy compression
• Sharing diagrams or charts where pixel accuracy matters
• Delivering generated images (e.g. from AI tools) in full quality

Proposed Usage

openclaw message send -t <chat_id> --media screenshot.png --force-document

Implementation Notes

The fix requires changes in two places:

src/channels/plugins/actions/telegram.ts — read forceDocument in readTelegramSendParams:

const forceDocument = readBooleanParam(params, "forceDocument");
return { ..., forceDocument };

src/agents/tools/telegram-actions.ts — pass forceDocument to sendMessageTelegram:

const result = await sendMessageTelegram(to, content, {
  ...
  forceDocument: readBooleanParam(params, "forceDocument") ?? false,
});

src/telegram/send.ts — add forceDocument?: boolean to TelegramSendOpts and update the mediaSender block:

if (kind === "image" && !opts.forceDocument) {
  // sendPhoto (compressed)
} else {
  // sendDocument (uncompressed)
}

src/cli/program/message/register.send.ts — expose the CLI flag:

.option("--force-document", "Send media as document to avoid compression (Telegram only).", false)