signal-cli-rest-api

To use the REST API with an existing mobile Signal account, use the QR code linking method. This allows the API to act as a secondary device on your behalf.

1. Request a QR code link by calling the /v1/qrcodelink endpoint with a device_name.
2. If the response warns about binary output, save the response to a file using --output img.jpg.
3. Scan the resulting QR code image with your primary Signal mobile app.

Note: The QR code changes with every request for security reasons.

Troubleshooting Binary Output: If curl returns a warning about binary output, use the --output flag to save the image.

curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/qrcodelink?device_name=HomeAssistant' --output img.jpg

A plugin consists of a definition file (.def) and a matching Lua script (.lua) with the same filename. These files must be stored in a plugins folder on your host and bind-mounted into the /plugins directory inside the Docker container.

services:
  signal-cli-rest-api:
    image: bbernhard/signal-cli-rest-api:latest
  environment:
    - MODE=json-rpc
    - ENABLE_PLUGINS=true
  volumes:
    - "./signal-cli-config:/home/.local/share/signal-cli"
    - "./plugins:/plugins" #map "plugins" folder on host system into docker container.

The recommended way to view the API documentation is via Docker Compose. This builds the documentation and starts the web server.

1. Build the docs: docker compose build
2. Serve the docs: docker compose up
3. Access the documentation at http://127.0.0.1:8080/swagger/index.html.

Note: If you encounter a Network error, replace 127.0.0.1 with the Docker internal IP (e.g., http://172.18.0.2:8080/swagger/index.html).

To run an ARM64 version of the signal-cli-rest-api image on an x86-64 host, you must first enable multi-architecture support using QEMU.

1. Register the QEMU user static binaries: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
2. Pull the specific ARM64 image using its SHA256 hash (found on Docker Hub).
3. Run the container using that same SHA256 hash.

To use custom plugins, you must enable the feature by setting the ENABLE_PLUGINS environment variable to true. This is typically done in your docker-compose.yml file.

services:                                                                                                                                                                                                        
  signal-cli-rest-api:
    image: bbernhard/signal-cli-rest-api:latest
    environment:
      - MODE=json-rpc #supported modes: json-rpc, native, normal
      - ENABLE_PLUGINS=true #enable plugins

You can create new Signal groups via the API.

1. Create Group: Send a POST request to /v1/groups/<number> with a JSON body containing the name and an array of members (phone numbers).
2. Get Group ID: After creation, perform a GET request to /v1/groups/<number> to retrieve the group_id. This ID is required for integrations like Home Assistant.

Troubleshooting Empty Group Lists: If groups do not appear in the list, ensure you are using json-rpc mode and try calling the /v1/receive/<number> endpoint to force the API to fetch data from Signal servers.

You can register a new phone number (including land-lines) via the REST API.

1. Initiate Registration: Send a POST request to /v1/register/<number>. Use the use_voice: true parameter if registering a land-line to receive the verification token via a phone call instead of SMS.
2. Verify Registration: Once you receive the token, send a POST request to /v1/register/<number>/verify/<verification code> to complete the process.

Handling Captchas: If the API returns {"error":"Captcha required for verification (null)\n"}, you must generate a captcha at https://signalcaptchas.org/registration/generate.html, solve it, and copy the signalcaptcha:// link to use in the captcha field of your registration request.

To visualize the generated documentation locally, run the web server from the src directory:

1. Navigate to the src folder: cd src
2. Run the main script: go run main.go
3. Access the documentation at http://127.0.0.1:8080/swagger/index.html.