Telegram Voice Transcribe

检测 Telegram 消息中的语音 file_id，调用 Python 脚本获取音频并交给 OpenAI Whisper API 转写为纯文本，也支持本地音频文件与外部音频地址。结果以 JSON 返回 transcript 字段，供智能体继续自然回复；需 OpenAI 密钥，file_id 模式还需机器人令牌。

dreadterror

热度 59.35

最近更新 2026-05-11 17:28:01

分类：效率依赖：代码执行 / 读写文件 / 第三方 API应用场景：文件转换 / 自动化脚本

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add telegram-voice-transcribe

Metadata

name: telegram-voice-transcribe
description: Transcribe Telegram voice messages and audio notes into text using the OpenAI Whisper API. Use when (1) a user sends a voice message or audio note via Telegram and you need to read or understand its content, (2) you receive a message with a voice file_id in the Telegram message metadata, (3) the user explicitly asks you to transcribe an audio file. Produces the transcript as plain text so you can respond naturally. Requires OPENAI_API_KEY env var and optionally TELEGRAM_BOT_TOKEN for file_id mode. NOT for live audio streams, video transcription, or non-Telegram audio pipelines (though the script supports local files and URLs too).

telegram-voice-transcribe

Transcribe Telegram voice notes into text via OpenAI Whisper (whisper-1).

Quick Workflow

Detect a voice message: look for voice.file_id or audio.file_id in the inbound message metadata.

Run the transcription script:

python3 ~/openclaw/skills/telegram-voice-transcribe/scripts/transcribe.py \
  --file-id <file_id> --language es

Read the JSON output — transcript field contains the text.
Respond to the user based on the transcript content (treat it like typed text).

Script Modes

Mode	Flag	When to use
Telegram file_id	`--file-id <id>`	Standard case — voice message in Telegram
Local file	`--file <path>`	Testing, or file already downloaded
URL	`--url <https://...>`	Audio hosted externally

Always pass --language es for Spanish speakers to improve speed and accuracy.

Output

{"transcript": "Hola, necesito que hagas un cambio en el juego", "language": "es", "duration_s": 4.2}

If error key is present, surface it to the user and check setup.

Environment Requirements

OPENAI_API_KEY — required (set via openclaw configure)
TELEGRAM_BOT_TOKEN — required for --file-id mode

See references/setup.md for full setup, hooks integration, costs, and local Whisper alternative.

Error Handling

Error	Fix
`OPENAI_API_KEY not set`	Configure key via `openclaw configure --section env`
`TELEGRAM_BOT_TOKEN required`	Add bot token to env
`openai package not installed`	`pip install openai`
Telegram `400 Bad Request`	file_id expired — Telegram file_ids expire after ~48h
File too large	Whisper API limit is 25MB; split audio or use local Whisper