telegram-file-delivery

Files (64)

• .env.example
• LICENSE
• README.md
• SECURITY.md
• SKILL.md
• _meta.json
• TELEGRAM-DELIVERY-OPERATING-MODEL.md · assets/
• paperclip_telegram_send.py · bin/
• company-agent-pack.md · docs/
• env-setup.md · docs/
• guardrails.md · docs/
• install-checklist.md · docs/
• paperclip-ui-install.md · docs/
• production-pack.md · docs/
• v1.0.0.md · docs/releases/
• v1.0.1.md · docs/releases/
• rollout.md · docs/
• attachments.json · examples/
• comment.txt · examples/
• package-comment.txt · examples/
• import-contract.json
• pyproject.toml
• agent-instructions.md · references/
• company-agent-pack.md · references/docs/
• env-setup.md · references/docs/
• guardrails.md · references/docs/
• install-checklist.md · references/docs/
• paperclip-ui-install.md · references/docs/
• production-pack.md · references/docs/
• rollout.md · references/docs/
• attachments.json · references/examples/
• comment.txt · references/examples/
• package-comment.txt · references/examples/
• implementation-plan.md · references/
• operations.md · references/
• paperclip-integration.md · references/
• agent-instructions.md · references/templates/
• DELIVERY-AGENT.md · references/templates/agents/
• REVIEWER.md · references/templates/agents/
• company-skill.md · references/templates/
• AGENTS.md · references/templates/company/
• HEARTBEAT.md · references/templates/company/
• openclaw.env.example · references/templates/company/
• telegram_delivery.py · scripts/
• validate.sh · scripts/
• __init__.py · src/paperclip_telegram_delivery/
• attachments.py · src/paperclip_telegram_delivery/
• cli.py · src/paperclip_telegram_delivery/
• config.py · src/paperclip_telegram_delivery/
• dotenv_loader.py · src/paperclip_telegram_delivery/
• filters.py · src/paperclip_telegram_delivery/
• models.py · src/paperclip_telegram_delivery/
• result.py · src/paperclip_telegram_delivery/
• sender.py · src/paperclip_telegram_delivery/
• summary.py · src/paperclip_telegram_delivery/
• triggers.py · src/paperclip_telegram_delivery/
• workflow.py · src/paperclip_telegram_delivery/
• DELIVERY-AGENT.md · templates/agents/
• REVIEWER.md · templates/agents/
• AGENTS.md · templates/company/
• …and 4 more

SKILL.md (first lines)

# Telegram File Delivery

Use this skill when a Paperclip user explicitly requests that issue files or
final deliverables be sent to Telegram.

This package is designed to be **UI-importable** and **productive by default**:
- no pip install required
- no repo patching after import
- only `.env` configuration should be needed
- direct Python stdlib Telegram Bot API client included in `scripts/telegram_delivery.py`
- end-to-end workflow runner included for trigger parsing, attachment intake, delivery, and summary generation
- layout aligned to the working Paperclip pattern: `skills/<skill>/SKILL.md` plus sibling `scripts/`, `references/`, and `assets/`

## Production-safe trigger

Preferred triggers:

```text
telegram-send attachments
telegram-send latest-files
telegram-send latest-package
telegram-send final-package
```

Optional explicit destination override:

```text
telegram-send attachments to -1001234567890
telegram-send latest-files to -1001234567890
```

Keep V1 narrow. Do not act on vague requests like "send this somewhere".

## Paperclip best-practice workflow

On comment-driven wakes:

1. Read the exact triggering comment first.
2. Confirm it explicitly requests Telegram delivery.
3. Prefer the comment wake payload / latest comment delta over replaying the full thread.
4. Prefer issue attachments or explicit deliverable files from the current issue.
5. For `latest-files` / `latest-package` / `final-package`, resolve files from the latest prior comment that contains a `Delivered package` bullet list.
6. Filter files through the local safety policy.
7. Send only allowed files.
7. Post **one** summary comment back into the issue.
8. If configuration is missing or no safe files exist, comment clearly and set the issue to `blocked` only when operator action is actually required.

## V1 operating scope

For the first production rollout, keep behavior constrained:

- explicit command only
- default destination chat unless an allowlisted override is requested
- attachments-first source selection, with latest-files fallback from prior delivered-package comments
- safe allowlisted file types only
- one final summary comment

## Included local helper

For Paperclip-installed use, prefer the self-contained helper in `scripts/`:

```bash
python scripts/telegram_delivery.py message --text "Telegram delivery is configured."
python scripts/telegram_delivery.py document --path /absolute/path/to/file
python scripts/telegram_delivery.py workflow \
  --comment-text 'telegram-send attachments' \
  --attachments-manifest references/examples/attachments.json \
  --emit-comment
python scripts/telegram_delivery.py workflow \
  --comment-text 'telegram-send latest-files' \
  --package-comment-file references/examples/package-comment.txt \
  --emit-comment
```

For repo-local development, the richer library-backed helper also exists, but installed Paperclip workflows should rely on the self-contained `scripts/telegram_delivery.py` path.

## Supported file types by default

- `.md`
- `.txt`
- `.pdf`
- `.docx`
- `.pptx`
- `.xlsx`
- `.png`
- `.jpg`
- `.jpeg`

## Never auto-send

- `.env`
- private keys
- credential files
- archives unless explicitly approved
- database dumps
- unsupported binaries

## Setup

### 1. Configure env

Add to your runtime env / `.env`:

```dotenv
TELEGRAM_BOT_TOKEN=1234567890:replace-me
TELEGRAM_DEFAULT_CHAT_ID=-1001234567890
TELEGRAM_ALLOWED_CHAT_IDS=-1001234567890
TELEGRAM_ALLOWED_EXTENSIONS=.md,.txt,.pdf,.docx,.pptx,.xlsx,.png,.jpg,.jpeg
TELEGRAM_MAX_FILE_BYTES=50000000
TELEGRAM_TIMEOUT_SECONDS=30
```

The helper auto-loads `.env`, `.env.telegram`, or `.env.paperclip` if present, so the easiest path is usually to add these values to the deployment `.env` already used by Paperclip/OpenClaw.

### 2. Smoke test

```bash
python scripts/telegram_delivery.py message --text "Telegram delivery is configured."
```

From fob92/paperclip-telegram-file-delivery, MIT.