Agent Messenger

Send batch messages with delivery tracking to OpenClaw agents via Telegram or other channels, supporting scheduling, templating, and fallback routing.

Send coordinated messages to OpenClaw agents with full delivery tracking.

Quick Start

Send to all agents (one-shot)

python3 scripts/send_telegram_direct.py "Tout le monde va bien ?" --agents all

Send to specific agents

python3 scripts/send_telegram_direct.py "Test message" --agents cybercodeur snake picsou

Send heartbeat (wait for manual ACKs)

bash scripts/heartbeat_check.sh "Heartbeat: Tout le monde là?" 10
# Waits 10 seconds for agents to react with ✅ on Telegram

Schedule heartbeat every 30 minutes

bash scripts/install_heartbeat_cron.sh "*/30"

Checks crontab:

crontab -l
tail -f /tmp/heartbeat.log

Use Cases

Broadcast health checks: Send "Are you alive?" to all agents, get ACK responses Trigger workflows: Send commands like "/health" to activate agent skills
Update notifications: Push configuration changes to all agents Scheduled messages: Combine with cron for periodic check-ins

Core Patterns

Pattern 1: Direct API Telegram (no chat resolution needed)

Uses bot tokens + user ID directly. Bypasses OpenClaw chat resolution issues.

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=<USER_ID>&text=<MESSAGE>"

Pattern 2: Agent Batching

Extract all agents from openclaw.json, build message list, send in parallel.

Pattern 3: Delivery Verification

Store sent message IDs, poll for ACK reactions, track delivery rate.

Files

• scripts/send_telegram_direct.py - Core: Send messages via Telegram API
• scripts/heartbeat_check.sh - Send heartbeat, wait for manual ACKs (RECOMMENDED)
• scripts/install_heartbeat_cron.sh - Automate heartbeat via cron job
• scripts/send_agent_msg.sh - Legacy: Bash-only batch sender

Troubleshooting

"Chat not found" → Use Pattern 1 (direct API) or ensure user ID matches No responses → Check agent model is running, token is valid Rate limit → Implement exponential backoff (auto in v2+)

Next Steps

• Add Discord/Slack handlers (references/slack-adapter.md)
• Implement ACK tracking (scripts/track_acks.py)
• Build message queue with retries (scripts/message_queue.py)