Skip to content
Back to skills

Telegram Voice Transcribe

ASecurity

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 ...

  • 3 stars
  • 0 votes
  • 0 copies
  • 6 views
  • Added September 9, 2026
toolspythongobashtestingapi

Works with

  • api

Security analysis

A92/100
  • mediumInstalls packages at runtime which could introduce malicious dependencies

Pro shows the line behind each finding and how to fix it

Scanned September 9, 2026

npx -y skills add Lord1Egypt/awesome-skill-forge --skill telegram-voice-transcribe --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Telegram Voice Transcribe?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Telegram Voice Transcribe
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/lord1egypt-telegram-voice-transcribe/badge)](https://www.skillsdirectory.com/skills/lord1egypt-telegram-voice-transcribe)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
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

1. **Detect** a voice message: look for `voice.file_id` or `audio.file_id` in the inbound message metadata.
2. **Run** the transcription script:
   ```bash
   python3 ~/openclaw/skills/telegram-voice-transcribe/scripts/transcribe.py \
     --file-id <file_id> --language es
   ```
3. **Read** the JSON output — `transcript` field contains the text.
4. **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

```json
{"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](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 |

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in tools →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.