bbernhard/signal-cli-rest-api: Dockerized Signal Messenger REST API

Dockerized Signal Messenger REST API. Contribute to bbernhard/signal-cli-rest-api development by creating an account on GitHub.

Summary

signal-cli-rest-api is a Dockerized Go service that wraps the signal-cli command-line tool, exposing Signal Messenger capabilities (sending and receiving messages, attachments, group management, device linking, profile updates) over a REST API. The project is MIT-licensed and targets engineers who want to integrate Signal into automation, bots, or backend systems without handling the underlying Java CLI directly.

What it is useful for

This project is useful when you need to send or receive Signal messages from a server, a CI pipeline, or a custom application. Documented use cases include notification systems that alert users via Signal, bots that respond to inbound messages, archival of incoming Signal attachments, and syncing Signal groups with another system.

The wrapper offers four execution modes with different trade-offs: normal spawns a JVM per request (simplest, slowest); native uses a GraalVM-compiled signal-cli-native binary (faster, less memory); and json-rpc and json-rpc-native keep a long-lived daemon (fastest, more memory). A plugin mechanism allows registering custom endpoints without forking. The README lists community clients in Python and TypeScript, including pysignalclirestapi, signalbot, and signal-rest-ts.

Documented limitations to plan around: native mode is not available on armv7 and falls back to normal, and the GraalVM-based mode is described as potentially less stable due to its experimental status. In normal and native modes, signal-cli recommends calling the receive endpoint on a schedule, which is why the AUTO_RECEIVE_SCHEDULE cron option exists; the README warns that combining scheduled auto-receive with manual receive calls can cause message loss.

How engineers can use it

The README documents a quick start with docker run. The basic flow is: create a persistent host directory for the signal-cli config (mkdir -p $HOME/.local/share/signal-api), start the container with that directory mounted and MODE=native set, link the container as a secondary device by opening http://localhost:8080/v1/qrcodelink?device_name=signal-api in a browser and scanning the QR code from Signal's Settings > Linked devices, then send a test message with curl -X POST -H "Content-Type: application/json" 'http://localhost:8080/v2/send' -d '{"message": "Test via Signal API!", "number": "+4412345", "recipients": [ "+44987654" ]}'. A sample docker-compose.yml is included. The Swagger API reference is published at bbernhard.github.io/signal-cli-rest-api/, and a plain-text examples file lives in doc/EXAMPLES.md. For env-var tuning (LOG_LEVEL, PORT, DEFAULT_SIGNAL_TEXT_MODE, JSON_RPC_TRUST_NEW_IDENTITIES, etc.), the Advanced Settings section in the README is the authoritative list; the defaults are described as sufficient for most users.