{"skill":{"slug":"signal-messenger-standalone","displayName":"Signal messaging for standalone bots/accounts","summary":"Full Signal messenger integration for OpenClaw agents. Send/receive text and voice messages via signal-cli with role-based permissions (owner/trusted/untrust...","description":"---\nname: signal-integration\ndescription: Full Signal messenger integration for OpenClaw agents. Send/receive text and voice messages via signal-cli with role-based permissions (owner/trusted/untrusted), automatic voice transcription (Whisper), voice replies (TTS), conversation history, new contact triage, typing indicators, read receipts, and instant wake-on-message via OpenClaw hooks API. Use when setting up Signal messaging, handling Signal contacts, sending/receiving Signal messages, or managing Signal contact permissions.\n---\n\n# Signal Integration\n\nComplete Signal messenger integration with security-first contact management.\n\n## Feature Overview\n\n- **Text & voice messaging** — Send and receive text messages, voice notes, images, and attachments\n- **Role-based permissions** — Three-tier contact system (owner/trusted/untrusted) controls who can instruct your agent to execute commands, modify files, or access private information\n- **New contact triage** — Unknown senders are flagged for owner approval before the agent engages; prevents prompt injection via unsolicited messages\n- **Voice transcription** — Incoming voice messages transcribed via Whisper (or any STT engine) for processing\n- **Voice replies** — Generate spoken responses via TTS and send as audio attachments\n- **Conversation history** — Per-contact message logs with timestamps for context continuity\n- **Typing indicators** — Shows \"typing...\" in the recipient's Signal app before sending\n- **Read & viewed receipts** — Marks messages as read; sends \"viewed\" receipt for voice messages\n- **UUID contact support** — Handles both phone number and UUID-based Signal contacts\n- **Instant wake** — Triggers OpenClaw's `/hooks/wake` API on new messages for immediate response (no waiting for next heartbeat)\n- **Auto-logging** — All sent and received messages logged to conversation files\n\n## Prerequisites\n\n- **signal-cli** (v0.13.x+): Java-based Signal client — [github.com/AsamK/signal-cli](https://github.com/AsamK/signal-cli)\n- **ffmpeg**: Audio format conversion\n- **A phone number**: For Signal registration (can be a VoIP number)\n- **OpenClaw hooks**: For instant wake-on-message (optional but recommended)\n\n### Optional (for voice messages)\n\n- **Whisper** (or whisper.cpp): Speech-to-text transcription\n- **TTS engine** (Coqui, Piper, or OpenClaw's built-in `tts` tool): Text-to-speech for voice replies\n\n## Setup\n\n### 1. Install signal-cli\n\n```bash\n# Download latest release\nSIGNAL_CLI_VERSION=\"0.13.12\"\ncurl -L \"https://github.com/AsamK/signal-cli/releases/download/v${SIGNAL_CLI_VERSION}/signal-cli-${SIGNAL_CLI_VERSION}-Linux.tar.gz\" | tar xz\nsudo mv signal-cli-${SIGNAL_CLI_VERSION}/bin/signal-cli /usr/local/bin/\nsudo mv signal-cli-${SIGNAL_CLI_VERSION}/lib /usr/local/lib/signal-cli\n\n# Or install to user directory\nmv signal-cli-${SIGNAL_CLI_VERSION} ~/.local/share/signal-cli-install\nln -s ~/.local/share/signal-cli-install/bin/signal-cli ~/.local/bin/signal-cli\n```\n\nRequires Java 21+: `sudo apt install openjdk-21-jre-headless`\n\n### 2. Register a number\n\n```bash\n# Register with SMS verification\nsignal-cli -a +YOUR_NUMBER register\n\n# Enter the verification code\nsignal-cli -a +YOUR_NUMBER verify CODE\n\n# Set your profile name\nsignal-cli -a +YOUR_NUMBER updateProfile --given-name \"YourName\" --family-name \"Bot\"\n```\n\n### 3. Configure the scripts\n\nEdit `scripts/signal-poll.sh` and `scripts/signal-send.sh`:\n- Set `SIGNAL_NUMBER` to your registered number\n- Set `SIGNAL_CLI` to your signal-cli binary path\n- Set `STATE_DIR` to your preferred state directory (default: `~/.signal-state`)\n- Add known contacts to `ALLOWLIST` and `CONTACTS` in signal-poll.sh\n\n### 4. Set up cron polling\n\n```bash\n# Poll every minute\ncrontab -e\n# Add: * * * * * /path/to/scripts/signal-poll.sh\n```\n\n### 5. Configure OpenClaw wake hook (recommended)\n\nAdd to your `openclaw.json` config:\n```json\n{\n  \"hooks\": {\n    \"wake\": {\n      \"enabled\": true,\n      \"token\": \"your-secret-token\"\n    }\n  }\n}\n```\n\nThen set the same token in `signal-poll.sh` (`WAKE_TOKEN` variable) and the OpenClaw URL (`WAKE_URL`).\n\n## Architecture\n\n```\nsignal-cli ←→ signal-poll.sh (cron every 1min)\n                  ├── Parses text + attachments\n                  ├── Logs to conversations/<sender>.log\n                  ├── Writes pending_wakes file\n                  └── POSTs to OpenClaw /hooks/wake API\n                  \nAgent (heartbeat/wake)\n  ├── Reads pending_wakes\n  ├── Reads conversation history for context\n  ├── Transcribes voice messages (Whisper)\n  ├── Generates reply (text or voice)\n  └── Sends via signal-send.sh\n```\n\n## Sending Messages\n\n```bash\n# Text message\nscripts/signal-send.sh +1234567890 \"Hello!\"\n\n# With attachment\nsignal-cli -a +YOUR_NUMBER send +RECIPIENT -m \"Check this out\" -a /path/to/file\n\n# Voice message (generate TTS then send as attachment)\n# 1. Generate audio (use your TTS engine)\n# 2. Convert to m4a: ffmpeg -i voice.wav -c:a aac -b:a 64k voice.m4a\n# 3. Send: signal-cli -a +YOUR_NUMBER send +RECIPIENT -m \"\" -a voice.m4a\n```\n\n## Receiving Messages\n\nThe poll script handles receiving automatically. In your HEARTBEAT.md, add:\n\n```markdown\n### Signal Messages (check first!)\ncat /path/to/.signal-state/pending_wakes 2>/dev/null\n```\n\nWhen processing a wake:\n1. Read `pending_wakes` for new message summary\n2. Read `conversations/<sender>.log` for full context\n3. For voice messages: transcribe the attachment path with Whisper\n4. Respond via `signal-send.sh` or voice attachment\n5. Clear: `> /path/to/.signal-state/pending_wakes`\n\n## Voice Message Handling\n\n### Transcribing incoming voice messages\n\n```bash\n# Convert to WAV for Whisper\nffmpeg -i /path/to/attachment.m4a -ar 16000 -ac 1 -c:a pcm_s16le /tmp/audio.wav -y\n\n# Transcribe (whisper.cpp server example)\ncurl -s http://127.0.0.1:8080/inference -F \"file=@/tmp/audio.wav\" -F \"language=en\"\n\n# Or use OpenAI Whisper, faster-whisper, etc.\n```\n\n### Sending voice replies\n\n```bash\n# 1. Generate speech (example with a local TTS server)\ncurl -X POST http://127.0.0.1:5002/tts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"Your message here\", \"language\": \"en\"}' \\\n  -o /tmp/voice.wav\n\n# 2. Convert to m4a for Signal\nffmpeg -i /tmp/voice.wav -c:a aac -b:a 64k /tmp/voice.m4a -y\n\n# 3. Send as attachment\nsignal-cli -a +YOUR_NUMBER send +RECIPIENT -m \"\" -a /tmp/voice.m4a\n```\n\n## Contact Management\n\n### New contacts (UUID-based)\n\nWhen someone new messages you, signal-cli may show them as a UUID (no phone number). The poll script handles both phone numbers and UUIDs.\n\n```bash\n# Accept a message request\nsignal-cli -a +YOUR_NUMBER sendMessageRequestResponse --type accept UUID_OR_NUMBER\n\n# List all known identities\nsignal-cli -a +YOUR_NUMBER listIdentities\n```\n\n### Triage workflow\n\nUnknown senders are logged to `.signal-state/triage.log` and flagged in `pending_wakes` with `⚠️ NEW CONTACT`. The agent should:\n1. Notify the owner about the new contact\n2. Wait for approval before engaging\n3. Add approved contacts to `ALLOWLIST` in signal-poll.sh\n\n## Typing Indicators & Read Receipts\n\nThe send script automatically shows a typing indicator before sending. The poll script sends read receipts and \"viewed\" receipts for voice messages.\n\n## File Reference\n\n- `scripts/signal-poll.sh` — Cron-based message receiver with wake integration\n- `scripts/signal-send.sh` — Send wrapper with typing indicator and conversation logging\n- `references/troubleshooting.md` — Common issues and fixes\n","topics":["Transcription","Message","Messaging"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":1179,"installsAllTime":44,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771691289554,"updatedAt":1779077225143},"latestVersion":{"version":"1.0.0","createdAt":1771691289554,"changelog":"Initial release: Full-featured Signal messenger integration for OpenClaw agents.\n\n- Send and receive text, image, and voice messages with role-based contact permissions (owner/trusted/untrusted).\n- Automatic voice message transcription (Whisper) and voice replies via TTS.\n- Secure new contact triage with owner approval workflow to prevent prompt injection.\n- Conversation history, typing indicators, read/viewed receipts, and UUID contact support.\n- Instant wake-on-message using OpenClaw’s /hooks/wake API integration.\n- All messages are auto-logged per contact to conversation files.","license":null},"metadata":null,"owner":{"handle":"lucksus","userId":"s1760d1qjmc195mvvnkwva9275885ejh","displayName":"Nicolas Luck","image":"https://avatars.githubusercontent.com/u/311749?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779947356153}}