signal-cli-api

A native REST + WebSocket API for signal-cli. Build Signal bots, notification systems, and integrations in any language.

Why this one

• Zero config. Run signal-cli-api and it works. Auto-spawns signal-cli, picks free ports, no containers or orchestration needed.
• Real-time streaming. WebSocket, SSE, and webhook delivery for incoming messages. No polling loops.
• Observable. Prometheus metrics, structured request tracing with x-request-id, per-RPC latency logging.
• Native TLS. Pass --tls-cert and --tls-key. No reverse proxy needed for HTTPS.
• Fast. Rust + axum. Sub-millisecond request overhead. Persistent JSON-RPC connection to signal-cli (no JVM restarts per request).
• Tested. 267 integration tests against a mock signal-cli daemon.

Quick start

1. Install

cargo install signal-cli-api

2. Set up signal-cli and link your phone

brew install signal-cli          # or your package manager
brew install qrencode            # to display QR code in terminal

Link signal-cli to your existing Signal account (keeps your phone working):

signal-cli link -n "my-server" | tee >(xargs -L 1 qrencode -t utf8)

This prints a QR code in your terminal. Scan it with your phone: Signal app > Settings > Linked Devices > Link New Device.

Wait for the process to exit — linking is complete. Then sync your contacts:

signal-cli -u +1234567890 receive

3. Run

signal-cli-api

That's it. API is live at http://localhost:8080. signal-cli is managed automatically.

If you already run signal-cli as a daemon:

signal-cli-api --signal-cli 127.0.0.1:7583

Options

--signal-cli <addr>   Connect to existing signal-cli daemon (default: auto-spawn)
--listen <addr>       HTTP listen address (default: 127.0.0.1:8080, falls back to random port if busy)
--tls-cert <path>     TLS certificate (PEM). Enables HTTPS.
--tls-key <path>      TLS private key (PEM). Required with --tls-cert.

Send a message

curl -X POST http://localhost:8080/v2/send \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Hello from my app!",
    "number": "+1234567890",
    "recipients": ["+1987654321"]
  }'

{"timestamp": 1234567890}

Receive messages

WebSocket (recommended for bots)

Connect to ws://localhost:8080/v1/receive/+1234567890. Messages stream as JSON:

{
  "envelope": {
    "source": "+1987654321",
    "dataMessage": {
      "message": "Hey!",
      "timestamp": 1234567890
    }
  }
}

Works with any WebSocket client — Python, Node, Go, Rust, whatever.

Server-Sent Events (SSE)

curl -N http://localhost:8080/v1/events/+1234567890

Webhooks

Push incoming messages to your HTTP endpoint:

# Register
curl -X POST http://localhost:8080/v1/webhooks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://your-app.com/signal-hook"}'

# With event filtering
curl -X POST http://localhost:8080/v1/webhooks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://your-app.com/hook", "events": ["message", "receipt"]}'

Monitoring

Prometheus-compatible metrics at /metrics:

signal_messages_sent_total 42
signal_messages_received_total 108
signal_rpc_calls_total 312
signal_rpc_errors_total 0
signal_ws_clients_active 2

Every request gets an x-request-id header and structured log entry:

INFO request_id=47 method=POST path="/v2/send" status=201 latency_ms=1152
INFO rpc_method="send" status=201 latency_ms=1150

API reference

Messages

Typing, Reactions & Receipts

Groups

Contacts

Accounts

Devices

Identities & Profiles

Polls & Stickers

Attachments & Search

Webhooks

System

Building from source

git clone <this-repo>
cd signal-cli-api
cargo build --release
# Binary at target/release/signal-cli-api (~4 MB)

Tests

cargo test   # 267 tests, no Signal account needed

License

MIT