openclaw-messaging

What this skill does

# OpenClaw Messaging

Three messaging layers, from user-facing to agent-internal.

## 1. System Events (Most Common for Agents)

Notify the active agent session (Grimlock) of state changes, completions, or discoveries.

```bash
# Immediate delivery — agent processes NOW
openclaw system event --mode now --text "Deployed atproto-agents to prod. CF Worker live at agents.joelhooks.com"

# Batched — delivered on next heartbeat (default 15m)
openclaw system event --text "Non-urgent: test suite passing, 47/47 green"

# Wait for agent response
openclaw system event --mode now --text "Need decision: use D1 or KV for session state?" --expect-final --json
```

**When to use:** After shipping to main, completing a task, discovering something important, or needing a decision routed through the system agent.

## 2. Direct Messages (External Channels)

Send to Telegram, Slack, Discord, WhatsApp, Signal, and 12+ other channels.

### Send

```bash
# Telegram (most common)
openclaw message send --channel telegram --target @joelhooks -m "Build complete, PR ready for review"

# Telegram with chat ID
openclaw message send --channel telegram --target 123456789 -m "Deployment finished"

# Slack
openclaw message send --channel slack --target "#dev-ops" -m "CI green, merging to main"

# With media attachment
openclaw message send --channel telegram --target @joelhooks -m "Architecture diagram" --media ./diagram.png

# Silent (no notification sound, Telegram only)
openclaw message send --channel telegram --target @joelhooks -m "FYI: background job done" --silent

# Dry run (preview without sending)
openclaw message send --channel telegram --target @joelhooks -m "test" --dry-run
```

### Broadcast

Same message to multiple targets:

```bash
openclaw message broadcast --channel telegram --targets @joelhooks 123456789 -m "System maintenance in 5 min"
```

### Read

Fetch recent messages from a conversation:

```bash
openclaw message read --channel telegram --target @joelhooks --limit 10 --json
openclaw message read --channel slack --target "#general" --limit 5
```

### React / Edit / Delete

```bash
openclaw message react --channel slack --target "#dev" --message-id 1234 --emoji thumbsup
openclaw message edit --channel telegram --target 123456789 --message-id 42 -m "Updated text"
openclaw message delete --channel telegram --target 123456789 --message-id 42
```

## 3. Agent Invocation

Trigger an agent turn and optionally deliver the response to a channel.

```bash
# Trigger agent, get response in terminal
openclaw agent -m "Summarize today's PRs" --json

# Trigger specific named agent
openclaw agent --agent ops -m "Check deployment status"

# Trigger agent AND deliver reply to Telegram
openclaw agent -m "Generate status report" --deliver --reply-channel telegram --reply-to @joelhooks

# With thinking level
openclaw agent -m "Analyze error logs" --thinking high

# Target existing session
openclaw agent --session-id abc123 -m "Continue from where we left off"
```

## 4. Swarmmail (Agent-to-Agent)

Internal message queue for coordinating between swarm workers. Available as MCP tools within agent sessions.

```
swarmmail_init       — Start mail session (call once at session start)
swarmmail_send       — Send message to another agent
swarmmail_inbox      — Check incoming messages
swarmmail_reserve    — Lock files for exclusive editing
swarmmail_release    — Release file locks
swarmmail_ack        — Acknowledge message receipt
swarmmail_health     — Check session health
```

Swarmmail is for inter-agent coordination only. For user-facing notifications, use `openclaw message send` or `openclaw system event`.

## 5. Directory Lookups

Find targets before sending:

```bash
openclaw directory self --channel telegram          # Your bot's info
openclaw directory peers --channel telegram          # Known contacts
openclaw directory groups --channel telegram         # Groups the bot is in
openclaw directory peers --channel slack             # Slack users
```

## Quick Reference

| Goal | Command |
|------|---------|
| Notify system agent (urgent) | `openclaw system event --mode now --text "..."` |
| Notify system agent (can wait) | `openclaw system event --text "..."` |
| Message user on Telegram | `openclaw message send --channel telegram --target @user -m "..."` |
| Message Slack channel | `openclaw message send --channel slack --target "#channel" -m "..."` |
| Send to multiple people | `openclaw message broadcast --channel telegram --targets @a @b -m "..."` |
| Trigger agent + deliver reply | `openclaw agent -m "..." --deliver --reply-channel telegram --reply-to @user` |
| Read conversation history | `openclaw message read --channel telegram --target @user --limit 10` |
| Preview without sending | Add `--dry-run` to any send/broadcast command |
| JSON output for scripting | Add `--json` to any command |

## Channel Support

Telegram, Slack, Discord, WhatsApp, Signal, iMessage, Google Chat, MS Teams, Mattermost, Matrix, Nostr, Feishu, Nextcloud Talk, BlueBubbles, Line, Zalo, Tlon.

Check active channels: `openclaw channels status`

## Common Patterns

### Post-deploy notification
```bash
openclaw system event --mode now --text "Shipped v1.2.3 to prod. Changes: new auth flow, fixed rate limiter."
openclaw message send --channel telegram --target @joelhooks -m "v1.2.3 live on prod"
```

### Agent handoff with context
```bash
openclaw system event --mode now --text "Completed Phase 1 encryption. All tests passing. Ready for Phase 2 HITL gate review."
```

### Swarm worker status update
```bash
openclaw system event --mode now --text "Worker task-42 complete: implemented D1 schema migration. 12 tests added."
```