signal-cli-rest-api-client 0.1.0

Async Python client for the signal-cli-rest-api (json-rpc mode).

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="[phone]",
    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

Method	Description
stream_events()	Open a WebSocket and yield incoming events as dicts
send(recipients, message, ...)	Send a message via the v2 API (supports attachments, quotes, edits, stickers, styled text, view-once)
submit_rate_limit_challenge(challenge_token, captcha)	Solve a CAPTCHA to lift rate-limit restrictions
show_typing_indicator(recipient)	Show "typing..." to a recipient
hide_typing_indicator(recipient)	Stop showing "typing..."
delete_message(recipient, timestamp)	Remote-delete a message for everyone
set_reaction(recipient, target_author, timestamp, reaction)	React to a message with an emoji
clear_reaction(recipient, target_author, timestamp)	Remove your reaction from a message
send_read_receipt(recipient, timestamp)	Send a read receipt
list_attachments()	List all attachment IDs on the server
get_attachment(attachment_id)	Download attachment bytes by ID
delete_attachment(attachment_id)	Delete an attachment from the server

Helpers

Symbol	Description
encode_attachment(file_or_bytes, ...)	Encode a file path or raw bytes into a data-URI string for send(base64_attachments=...)
SendError	Exception raised on 400 responses; carries challenge_tokens for rate-limit recovery

API coverage

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

Upstream endpoint	Client method	Status
POST /v2/send	send()	Implemented
WS /v1/receive/{number}	stream_events()	Implemented
POST /v1/reactions/{number}	set_reaction()	Implemented
DELETE /v1/reactions/{number}	clear_reaction()	Implemented
POST /v1/receipts/{number}	send_read_receipt()	Implemented
DELETE /v1/remote-delete/{number}	delete_message()	Implemented
PUT /v1/typing-indicator/{number}	show_typing_indicator()	Implemented
DELETE /v1/typing-indicator/{number}	hide_typing_indicator()	Implemented
GET /v1/attachments	list_attachments()	Implemented
GET /v1/attachments/{id}	get_attachment()	Implemented
DELETE /v1/attachments/{id}	delete_attachment()	Implemented
POST /v1/accounts/{number}/rate-limit-challenge	submit_rate_limit_challenge()	Implemented
Groups (create, list, update, members, admins, join, quit, block, avatar)	—	Not implemented
Contacts (list, update, sync, avatar)	—	Not implemented
Profiles (get, update)	—	Not implemented
Devices (list, link, remove)	—	Not implemented
Identities (list, trust)	—	Not implemented
Registration & verification	—	Not implemented
Account settings, PIN, username	—	Not implemented
Polls (create, vote)	—	Not implemented
Sticker packs	—	Not implemented
Search	—	Not implemented
QR code linking	—	Not implemented
/v1/about, /v1/health	—	Not implemented
POST /v1/send (v1 send)	—	Not implemented (use v2)
GET /v1/receive/{number} (REST poll)	—	Not implemented (use WebSocket)

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="[phone]")

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=[phone]
SIGNAL_USER=admin
SIGNAL_PASSWORD=secret

Then:

pip install -e ".[dev]"
pytest

License

MIT