Signal Integration

Complete Signal messenger integration with security-first contact management.

Feature Overview

• Text & voice messaging — Send and receive text messages, voice notes, images, and attachments
• 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
• New contact triage — Unknown senders are flagged for owner approval before the agent engages; prevents prompt injection via unsolicited messages
• Voice transcription — Incoming voice messages transcribed via Whisper (or any STT engine) for processing
• Voice replies — Generate spoken responses via TTS and send as audio attachments
• Conversation history — Per-contact message logs with timestamps for context continuity
• Typing indicators — Shows "typing..." in the recipient's Signal app before sending
• Read & viewed receipts — Marks messages as read; sends "viewed" receipt for voice messages
• UUID contact support — Handles both phone number and UUID-based Signal contacts
• Instant wake — Triggers OpenClaw's /hooks/wake API on new messages for immediate response (no waiting for next heartbeat)
• Auto-logging — All sent and received messages logged to conversation files

Prerequisites

• signal-cli (v0.13.x+): Java-based Signal client — github.com/AsamK/signal-cli
• ffmpeg: Audio format conversion
• A phone number: For Signal registration (can be a VoIP number)
• OpenClaw hooks: For instant wake-on-message (optional but recommended)

Optional (for voice messages)

• Whisper (or whisper.cpp): Speech-to-text transcription
• TTS engine (Coqui, Piper, or OpenClaw's built-in tts tool): Text-to-speech for voice replies

Setup

1. Install signal-cli

# Download latest release
SIGNAL_CLI_VERSION="0.13.12"
curl -L "https://github.com/AsamK/signal-cli/releases/download/v${SIGNAL_CLI_VERSION}/signal-cli-${SIGNAL_CLI_VERSION}-Linux.tar.gz" | tar xz
sudo mv signal-cli-${SIGNAL_CLI_VERSION}/bin/signal-cli /usr/local/bin/
sudo mv signal-cli-${SIGNAL_CLI_VERSION}/lib /usr/local/lib/signal-cli

# Or install to user directory
mv signal-cli-${SIGNAL_CLI_VERSION} ~/.local/share/signal-cli-install
ln -s ~/.local/share/signal-cli-install/bin/signal-cli ~/.local/bin/signal-cli

Requires Java 21+: sudo apt install openjdk-21-jre-headless

2. Register a number

# Register with SMS verification
signal-cli -a +YOUR_NUMBER register

# Enter the verification code
signal-cli -a +YOUR_NUMBER verify CODE

# Set your profile name
signal-cli -a +YOUR_NUMBER updateProfile --given-name "YourName" --family-name "Bot"

3. Configure the scripts