signal-cli-rest-api-client

Async Python client for bbernhard's signal-cli-rest-api.

Requires signal-cli-rest-api to be running in json-rpc mode (the default normal mode will not work).

Covers the endpoints I currently need — sending messages, listening for events, reactions, typing indicators, attachments, and a few others. The upstream API has many more endpoints (groups, contacts, profiles, registration, etc.) that are not yet wrapped by this client. See the coverage table below so you know if this meets your needs.

Install

pip install signal-cli-rest-api-client

Or from source:

pip install .

Requires Python 3.10+ and aiohttp.

Quick start

import asyncio
from signal_cli_rest_api_client.client import SignalClient, encode_attachment

client = SignalClient(
    url="https://signal-api.example.com",
    phone="+1234567890",
    user="admin",        # optional, for basic auth
    password="secret",   # optional, for basic auth
)

async def main():
    # Send a message
    resp = await client.send("+0987654321", "Hello from Python!")

    # Send with an attachment
    attachment = encode_attachment("/path/to/photo.jpg")
    await client.send("+0987654321", "Check this out", base64_attachments=[attachment])

    # Listen for incoming events
    async for event in client.stream_events():
        print(event)

asyncio.run(main())

What's included

SignalClient

Helpers

API coverage

The upstream signal-cli-rest-api exposes ~40 endpoints. This client wraps the ones listed below. Everything else is not implemented.

PRs welcome if you need something from the "not implemented" list.

Configuration

The client expects signal-cli-rest-api to be running in json-rpc mode (--mode=json-rpc). This is different from the default normal mode — json-rpc mode is required for the v2 send API and WebSocket event streaming to work. See the signal-cli-rest-api docs for how to enable it.

Pass the base URL and your registered phone number:

client = SignalClient(url="https://signal.example.com", phone="+1234567890")

If your API is behind basic auth, pass user and password as well.

Running tests

Tests hit a real Signal API instance and send messages to yourself. Set these in a .env file at the project root:

SIGNAL_URL=https://signal-api.example.com
SIGNAL_NUMBER=+1234567890
SIGNAL_USER=admin
SIGNAL_PASSWORD=secret

Then:

pip install -e ".[dev]"
pytest

License

MIT