Telegram Send

Send voice, photo, and document files via Telegram bot — with a Bot-API-first delivery policy, automatic chat ID resolution, and a local endpoint fallback for text notices and retries.

Default Active Communication

Quick Reference

Delivery Policy (Bot-First)

The skill follows a strict two-tier delivery strategy. The Telegram Bot API is always tried first. The local CLI-JAW endpoint serves as a convenience layer for text and as a fallback when the Bot API fails.

Required Inputs

Step-by-Step Workflow

Step 1: Read Token and Chat ID

The agent reads credentials from the CLI-JAW settings file. Tokens are kept in shell variables only — never printed to stdout or logs.

TOKEN=$(jq -r '.telegram.token' ~/.cli-jaw/settings.json)
CHAT_ID=$(jq -r '.telegram.allowedChatIds[-1]' ~/.cli-jaw/settings.json)

If CHAT_ID resolves to null (no previous Telegram message on record), the agent recovers by pinging the local endpoint:

CHAT_ID=$(curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"chat_id check"}' | jq -r '.chat_id')

Step 2: Send via Bot API (Primary)

The agent constructs a curl multipart form POST to the appropriate Telegram Bot API endpoint based on the message type.

Send a photo

curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendPhoto" \
  -F "chat_id=${CHAT_ID}" \
  -F "photo=@/tmp/chart.png" \
  -F "caption=Analysis chart"

Send a voice message

curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendVoice" \
  -F "chat_id=${CHAT_ID}" \
  -F "voice=@/tmp/reply.ogg" \
  -F "caption=Voice response"

Send a document

curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendDocument" \
  -F "chat_id=${CHAT_ID}" \
  -F "document=@/tmp/report.pdf" \
  -F "caption=Weekly report"

Step 3: Local Endpoint (Secondary / Fallback)

The local CLI-JAW server exposes a Telegram send endpoint at:

Text message (primary use of local endpoint)

curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"Deployment complete!"}'

Media fallback via local endpoint

curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"photo","file_path":"/tmp/chart.png","caption":"Analysis chart"}'

Step 4: Verify Delivery

A successful send returns a JSON response with "ok": true:

{"ok":true,"chat_id":8231528245,"type":"text"}

The agent checks this response before reporting success to the user. If the response indicates failure, and the primary method was Bot API, one retry is attempted via the local endpoint.

Supported Message Types

Configuration

The skill reads all configuration from ~/.cli-jaw/settings.json. No separate config file is needed.

// ~/.cli-jaw/settings.json (relevant keys)
{
  "telegram": {
    "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "allowedChatIds": [8231528245]
  }
}

Dependencies

This skill requires only standard Unix tools that are pre-installed on macOS and most Linux distributions.

Verify dependencies

# Check curl
curl --version

# Check jq
jq --version

# Install jq if missing (macOS)
brew install jq

# Install jq if missing (Ubuntu/Debian)
sudo apt-get install -y jq

Safety Rules

The skill enforces strict security practices around token handling:

Quick Verification

To test that the Telegram integration is working, run this ping command:

curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"ping"}'

Expected response:

{"ok":true,"chat_id":8231528245,"type":"text"}

If you receive an error, check that:

1. The CLI-JAW server is running (jaw server status)
2. The bot token is configured in ~/.cli-jaw/settings.json
3. You have sent at least one message to the bot on Telegram (to establish the chat)

"~해줌" Usage Examples

Real-world examples showing how to trigger the telegram-send skill in natural language. Korean and English both work.

Integration with Other Skills

The telegram-send skill is often the final step in a multi-skill workflow. It pairs naturally with any skill that produces output files or status updates.

API Reference

Bot API Endpoints Used

Local Endpoint

Response Format

// Success
{"ok": true, "chat_id": 8231528245, "type": "text"}

// Failure (example)
{"ok": false, "error": "Bot token not configured"}

Troubleshooting

Chat ID is null

If jq -r '.telegram.allowedChatIds[-1]' returns null, the bot has not received any messages from you yet. Send any message to the bot on Telegram first, then the chat ID will be recorded in settings. Alternatively, the agent will auto-recover by probing the local endpoint.

Bot API returns 401 Unauthorized

The bot token is invalid or expired. Generate a new token from @BotFather and update ~/.cli-jaw/settings.json.

Bot API returns 400 Bad Request

Common causes:

• Invalid chat_id: The chat ID does not correspond to an active conversation with the bot.
• File too large: Telegram Bot API limits files to 50 MB for uploads. For larger files, use the local endpoint which may handle chunked uploads.
• Wrong file format for voice: Voice messages must be in OGG format with OPUS encoding. Other audio formats should be sent as document instead.

Local endpoint connection refused

The CLI-JAW server is not running. Start it with:

jaw server start

# Or check status
jaw server status

jq not found

Install jq to parse the settings file:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install -y jq

# Verify
jq --version

Comparison with Telegram Guide

CLI-JAW documentation covers Telegram in two places. They serve different purposes: