signal-cli-rest-api

Dockerized Signal Messenger REST API

1,273

153

1,273

View on GitHub

Top Related Projects

signal-cli

3,130

signal-cli provides an unofficial commandline, JSON-RPC and dbus interface for the Signal messenger.

matrix-js-sdk

1,530

Matrix Client-Server SDK for JavaScript

Signal-Desktop

14,501

A private messenger for Windows, macOS, and Linux.

Quick Overview

Signal-cli-rest-api is a Docker image that provides a REST API for the signal-cli command-line interface. It allows users to interact with the Signal messaging service programmatically, enabling the sending and receiving of messages, managing contacts, and performing other Signal-related operations through HTTP requests.

Pros

Easy integration with existing systems and applications
Supports multiple accounts and devices
Provides a RESTful interface for Signal operations
Containerized solution for easy deployment and scaling

Cons

Requires Docker for deployment
Limited documentation for advanced use cases
Potential security concerns when exposing Signal operations via API
May not support all features available in the official Signal app

Getting Started

Pull the Docker image:

docker pull bbernhard/signal-cli-rest-api

Run the container:

docker run -p 8080:8080 -v $(pwd)/signal-cli-config:/home/.local/share/signal-cli -e MODE=normal bbernhard/signal-cli-rest-api

curl -X POST -H "Content-Type: application/json" 'http://localhost:8080/v1/register/+1234567890'

Verify the number with the received code:

curl -X POST -H "Content-Type: application/json" 'http://localhost:8080/v1/register/+1234567890/verify/123456'

After completing these steps, you can start using the API to send and receive messages, manage contacts, and perform other Signal-related operations.

Competitor Comparisons

signal-cli

3,130

signal-cli provides an unofficial commandline, JSON-RPC and dbus interface for the Signal messenger.

Pros of signal-cli

Command-line interface allows for more flexible integration and scripting
Direct access to Signal protocol features without an additional API layer
Potentially lower resource usage due to lack of REST API overhead

Cons of signal-cli

Requires more technical knowledge to set up and use
Less user-friendly for developers who prefer working with RESTful APIs
May require additional work to integrate into web-based applications

Code Comparison

signal-cli:

signal-cli -u +1234567890 send -m "Hello, World!" +9876543210

signal-cli-rest-api:

POST /v1/send
Content-Type: application/json

{
  "message": "Hello, World!",
  "number": "+9876543210"
}

Summary

signal-cli provides a command-line interface for interacting with the Signal protocol, offering more direct access and flexibility for advanced users. signal-cli-rest-api, on the other hand, wraps signal-cli in a RESTful API, making it easier to integrate into web applications and use for developers familiar with HTTP-based APIs. The choice between the two depends on the specific use case and developer preferences.

matrix-js-sdk

1,530

Matrix Client-Server SDK for JavaScript

Pros of matrix-js-sdk

Comprehensive SDK for Matrix protocol, offering a wide range of features
Well-documented and actively maintained by the Matrix.org team
Supports both browser and Node.js environments

Cons of matrix-js-sdk

Steeper learning curve due to Matrix protocol complexity
Larger codebase and potentially higher resource usage
Limited to Matrix protocol, not suitable for Signal integration

Code Comparison

matrix-js-sdk:

const client = matrixcs.createClient({
    baseUrl: "https://matrix.org",
    accessToken: "YOUR_ACCESS_TOKEN",
    userId: "@alice:matrix.org"
});
client.sendMessage("!roomId:matrix.org", {
    body: "Hello, World!",
    msgtype: "m.text"
});

signal-cli-rest-api:

curl -X POST -H "Content-Type: application/json" \
     -d '{"message": "Hello, World!", "number": "+1234567890"}' \
     http://localhost:8080/v1/send

Summary

matrix-js-sdk is a comprehensive SDK for the Matrix protocol, offering extensive features and documentation. It's suitable for complex Matrix-based applications but has a steeper learning curve. signal-cli-rest-api, on the other hand, provides a simpler REST API for Signal messaging, making it easier to integrate Signal functionality into applications. The choice between the two depends on the specific messaging protocol requirements and the desired level of integration complexity.

Signal-Desktop

14,501

A private messenger for Windows, macOS, and Linux.

Pros of Signal-Desktop

Full-featured desktop client with a graphical user interface
Direct integration with Signal's infrastructure
Regular updates and maintenance by the official Signal team

Cons of Signal-Desktop

Limited API access for third-party developers
Focused on end-user experience rather than programmatic control
Larger resource footprint due to Electron-based architecture

Code Comparison

Signal-Desktop (TypeScript):

async sendMessage(
  timestamp: number,
  message: MessageAttributesType,
  options: SendOptionsType = {}
): Promise<void> {
  // Implementation details
}

signal-cli-rest-api (Python):

@app.route('/v1/send', methods=['POST'])
def send_message():
    data = request.get_json()
    recipient = data['recipient']
    message = data['message']
    # Implementation details

Key Differences

Signal-Desktop is a full-fledged desktop application for end-users, while signal-cli-rest-api is a RESTful API wrapper for the signal-cli command-line tool. Signal-Desktop offers a complete GUI experience, whereas signal-cli-rest-api provides programmatic access to Signal functionality, making it more suitable for automation and integration into other applications.

Signal-Desktop is maintained by the official Signal team, ensuring compatibility and regular updates. In contrast, signal-cli-rest-api is a community-driven project that depends on signal-cli, which may have limitations in terms of features and update frequency.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Dockerized Signal Messenger REST API

This project creates a small dockerized REST API around signal-cli.

At the moment, the following functionality is exposed via REST:

Register a number
Verify the number using the code received via SMS
Send message (+ attachments) to multiple recipients (or a group)
Receive messages
Link devices
Create/List/Remove groups
List/Serve/Delete attachments
Update profile

and many more

Getting started

Create a directory for the configuration This allows you to update signal-cli-rest-api by just deleting and recreating the container without the need to re-register your signal number

$ mkdir -p $HOME/.local/share/signal-api

Start a container

$ sudo docker run -d --name signal-api --restart=always -p 8080:8080 \
      -v $HOME/.local/share/signal-api:/home/.local/share/signal-cli \
      -e 'MODE=native' bbernhard/signal-cli-rest-api

In this case we'll register our container as secondary device, assuming that you already have your primary number running / assigned to your mobile.

Therefore open http://localhost:8080/v1/qrcodelink?device_name=signal-api in your browser, open Signal on your mobile phone, go to Settings > Linked devices and scan the QR code using the + button.

Test your new REST API

Call the REST API endpoint and send a test message: Replace +4412345 with your signal number in international number format, and +44987654 with the recipients number.

$ curl -X POST -H "Content-Type: application/json" 'http://localhost:8080/v2/send' \
     -d '{"message": "Test via Signal API!", "number": "+4412345", "recipients": [ "+44987654" ]}'

You should now have send a message to +44987654.

Execution Modes

The signal-cli-rest-api supports three different modes of execution, which can be controlled by setting the MODE environment variable.

normal Mode: (Default) The signal-cli executable is invoked for every REST API request. Being a Java application, each REST call requires a new startup of the JVM (Java Virtual Machine), increasing the latency and hence leading to the slowest mode of operation.
native Mode: A precompiled binary signal-cli-native (using GraalVM) is used for every REST API request. This results in a much lower latency & memory usage on each call. On the armv7 platform this mode is not available and falls back to normal. The native mode may also be less stable, due to the experimental state of GraalVM compiler.
json-rpc Mode: A single, JVM-based signal-cli instance is spawned as daemon process. This mode is usually the fastest, but requires more memory as the JVM keeps running.

mode	speed	resident memory usage
`normal`	:heavy_check_mark:	normal
`native`	:heavy_check_mark: :heavy_check_mark:	normal
`json-rpc`	:heavy_check_mark: :heavy_check_mark: :heavy_check_mark:	increased

Example of running signal-cli-rest in native mode

$ sudo docker run -d --name signal-api --restart=always -p 9922:8080 \
              -v /home/user/signal-api:/home/.local/share/signal-cli \
              -e 'MODE=native' bbernhard/signal-cli-rest-api

This launches a instance of the REST service accessible under http://localhost:9922/v2/send. To preserve the Signal number registration, i.e. for updates, the storage location for the signal-cli configuration is mapped as Docker Volume into a local /home/user/signal-api directory.

Auto Receive Schedule

:warning: This setting is only needed in normal/native mode!

signal-cli, which this REST API wrapper is based on, recommends to call receive on a regular basis. So, if you are not already calling the receive endpoint regularly, it is recommended to set the AUTO_RECEIVE_SCHEDULE parameter in the docker-compose.yml file. The AUTO_RECEIVE_SCHEDULE accepts cron schedule expressions and automatically calls the receive endpoint at the given time. e.g: 0 22 * * * calls receive daily at 10pm. If you are not familiar with cron schedule expressions, you can use this website.

WARNING Calling receive will fetch all the messages for the registered Signal number from the Signal Server! So, if you are using the REST API for receiving messages, it's not a good idea to use the AUTO_RECEIVE_SCHEDULE parameter, as you might lose some messages that way.

Example

Sample docker-compose.ymlfile:

version: "3"
services:
  signal-cli-rest-api:
    image: bbernhard/signal-cli-rest-api:latest
    environment:
      - MODE=normal #supported modes: json-rpc, native, normal
      #- AUTO_RECEIVE_SCHEDULE=0 22 * * * #enable this parameter on demand (see description below)
    ports:
      - "8080:8080" #map docker port 8080 to host port 8080.
    volumes:
      - "./signal-cli-config:/home/.local/share/signal-cli" #map "signal-cli-config" folder on host system into docker container. the folder contains the password and cryptographic keys when a new number is registered

Documentation & Usage

API Reference

The Swagger API documentation can be found here. If you prefer a simple text file based API documentation have a look here.

Blog Posts

Clients, Libraries and Scripts

Name	Type	Language	Description	Maintainer
pysignalclirestapi	Library	Python	Small python library	@bbernhard
signalbot	Library	Python	Framework to build Signal bots	@filipre
signal-cli-to-file	Script	JavaScript	Save incoming signal messages as files	@jneidel

In case you need more functionality, please file a ticket or create a PR.

Advanced Settings

There are a bunch of environmental variables that can be set inside the docker container in order to change some technical details. This settings are meant for developers and advanced users. Usually you do not need to change anything here - the default values are perfectly fine!

SIGNAL_CLI_CONFIG_DIR: Specifies the path to the signal-cli config directory inside the docker container. Defaults to /home/.local/share/signal-cli/
SIGNAL_CLI_UID: Specifies the uid of the signal-api user inside the docker container. Defaults to 1000
SIGNAL_CLI_GID: Specifies the gid of the signal-api group inside the docker container. Defaults to 1000
SWAGGER_HOST: The host that's used in the Swagger UI for the interactive examples (and useful when this runs behind a reverse proxy). Defaults to SWAGGER_IP:PORT.
SWAGGER_IP: The IP that's used in the Swagger UI for the interactive examples. Defaults to the container ip.
PORT: Defaults to port 8080 unless this env var is set to tell it otherwise.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot