What token and chat details are required?

Provide the Telegram Bot API token (read from OpenClaw config) and the target chat_id and message_id from the message context.

What media types are supported?

Photos, documents, videos, animations (GIFs), stickers, voice messages, video notes, and audio files represented by placeholders.

What are the main limitations?

The bot must be a member of the target chat, and files over 20MB cannot be downloaded via the Bot API; use --forward-to to keep forwards private in groups.

Telegram Media Resolver

@kurinzo

npx machina-cli add skill @kurinzo/tg-media-resolve --openclaw

Files (1)

SKILL.md

2.7 KB

Telegram Media Resolver

Resolves <media:*> placeholders from Telegram messages into downloadable files.

When to use

When you see <media:image>, <media:document>, <media:video>, <media:sticker>, <media:voice>, or <media:animation> in a Telegram message (especially in reply-quoted context or group history) and need to actually see/analyze the content.

How it works

Temporarily forwards the target message via Bot API to get file metadata
Downloads the file from Telegram servers
Deletes the forwarded copy (cleanup)
Returns local file path for use with image tool or exec

Usage

python3 scripts/fetch_media.py \
  --bot-token "$BOT_TOKEN" \
  --chat-id CHAT_ID \
  --message-id MESSAGE_ID \
  [--out /tmp] \
  [--forward-to SELF_CHAT_ID]

Parameters

--bot-token — Telegram Bot API token (read from OpenClaw config: channels.telegram.botToken)
--chat-id — Chat where the message lives (from message context, e.g. -1001234567890)
--message-id — ID of the message containing media (from [id:XXXXX] in message context)
--out — Output directory (default: /tmp)
--forward-to — Chat ID for temporary forward (default: same as --chat-id). Use bot owner's DM chat ID to avoid visible forwards in groups.

Extracting parameters from message context

OpenClaw formats Telegram messages like:

[Telegram GroupName id:CHAT_ID topic:N ...] User (USER_ID): <media:image> [id:MSG_ID chat:CHAT_ID]

Extract CHAT_ID and MSG_ID from this format.

Workflow

Extract chat_id and message_id from the message context
Read bot token: cat ~/.openclaw/openclaw.json | python3 -c "import sys,json; print(json.load(sys.stdin)['channels']['telegram']['botToken'])"
Run fetch script
Use returned file path with image tool for vision analysis

Supported media types

Photos, documents, videos, animations (GIFs), stickers, voice messages, video notes, audio files.

Limitations

Bot must be a member of the chat containing the target message
Files over 20MB cannot be downloaded via Bot API
The temporary forward may briefly appear in the forward-to chat before deletion
Use --forward-to with a private chat (e.g. bot owner's DM) to avoid visible forwards in group chats

Source

git clone https://clawhub.ai/kurinzo/tg-media-resolveView on GitHub

Overview

Telegram Media Resolver converts hidden media placeholders like <media:image> into actual downloadable files for vision/analysis. It’s used when media is present in replies, quotes, or group history but not directly visible. The tool fetches via the Telegram Bot API and returns a local file path for downstream processing.

How This Skill Works

The tool temporarily forwards the target message via the Bot API to obtain file metadata, downloads the file from Telegram servers, then deletes the forwarded copy for cleanup. It returns a local file path that can be used with an image tool or an exec script for further processing.

When to Use It

You see a <media:image> placeholder in a reply or quoted message and need the actual image for analysis.
Analyzing a <media:video> or <media:document> in a group chat history where the original media is not visible.
Processing <media:sticker> or <media:voice> placeholders to fetch the real file for processing.
Working in a bot-enabled chat and you must temporarily forward the message to obtain file metadata.
You need a local file path to feed an image tool or a custom script for vision tasks.

Quick Start

Step 1: Run the fetch_media.py script with --bot-token, --chat-id, and --message-id along with optional --out and --forward-to.
Step 2: Use the returned local file path for the image tool or downstream processing.
Step 3: If needed, delete or archive the temporary forward per your workflow and security policy.

Best Practices

Ensure the bot is a member of the target chat before attempting to fetch media.
Use --forward-to with a private chat (e.g., bot owner's DM) to avoid visible forwards in groups.
Prefer the default output directory (/tmp) unless you have a specific workspace path.
Be mindful of Bot API file size limits (20MB max) when requesting large media.
Validate chat_id and message_id from your message context before running the fetch script.

Example Use Cases

A support agent extracts a hidden product image from a customer’s quoted message for visual QA.
A moderator fetches a video placeholder from a group discussion history to verify content policy.
A UX tester downloads a sticker from a forwarded message to test in-app UI rendering.
A transcription workflow pulls an audio clip from a message in a chat for speech-to-text processing.
An OCR pipeline retrieves a document placeholder to run OCR on the actual document file.

Frequently Asked Questions

Add this skill to your agents