A Python module for building Signal.org bots that interact with signal-cli.
Project description
Signal-Bot
An asyncio
Python 3.11 module for building Signal bots that interact with AsamK/signal-cli.
Features
- Construct different "personalities" for different contexts (users, groups, etc).
- Callbacks for the following events:
- Cron schedules.
- Any message is received.
- Message matches a prefix (e.g.,
/command ...
). - Message contains a keyword.
- Message contains an
@
-mention.
- Currently supported signal-cli functions:
- "Typing..." indicators.
- Reacting to messages.
- Sending messages, including:
- Inline mentions.
- Inline text styles.
- More to come...
- Deleting messages.
Usage
For development: python3.11 -m pip install signal_bot_framework
.
# test_bot.py
import asyncio
from signal_bot_framework import create, AccountNumber
async def crabby_callback(signal: Signal, context: Context, message: DataMessage) -> bool:
to = context[1]
await signal.send_reaction(message, "🦀")
await signal.send_message(to, f"Sorry, just feeling a little crabby, {message.sender_name}.",
args=SendMessageArgs(mention=[f"37:{len(message.sender_name)}:{message.sender}"]))
return True
async def main():
# The default, finds `signal-cli` on path and launches it as a subprocess
connection = 'ipc://'
# or, use TCP: connection = 'tcp://HOST:PORT'
signal = await create(AccountNumber('+12345678900'), connection)
signal.on_keyword('ok?', crabby_callback)
await signal.run()
if __name__ == '__main__':
asyncio.run(main())
Docker
For convenience, a base Docker image can be built as sidneys1/signal_bot
, based on python:3.11-alpine
.
You can base your bot on it like so:
FROM sidneys1/signal_bot:latest
COPY ./test_bot.py .
CMD ["python", "test_bot.py"]
You can easily combine this in Docker-Compose with a signal-cli
container.
Make sure to change your test_bot.py
's connection
string to tcp://signal-cli:7583
.
Additionally, an easy way to keep your Signal account from being stored in your image or docker-compose.yml
is to
store it in a Docker secret, as shown below.
secrets:
signal-account:
file: .signal-account
services:
test_bot:
build: .
depends_on: [signal-cli]
signal-cli:
image: registry.gitlab.com/packaging/signal-cli/signal-cli-native:latest
volumes:
# Mount an existing signal-cli configuration directory from the host.
- "${HOME}/.local/share/signal-cli:/var/lib/signal-cli:rw"
ports: ["7583"]
secrets: [signal-account]
entrypoint: sh -c
command: "'signal-cli -c /var/lib/signal-cli --account $(cat /run/secrets/signal-account) daemon --receive-mode on-connection --no-receive-stdout --send-read-receipts --tcp 0.0.0.0:7583'"
Building
- Clone this repository and install the prerequisites:
- Python >= 3.11 with
venv
support (included with Python for Windows,python3.11-venv
on most package managers). python3.11 -m pip install build
- Python >= 3.11 with
- Run
python3.11 -m build
in the repository folder. - Distribute or install
./dist/signal_bot_framework-X.Y.Z-py3-none-any.whl
.
Dependencies
cron-converter
(for Cron-based hooks).humanize
(for debugging output related to Cron-based hooks).
Signal-Bot assumes that you already have signal-cli
available and registered with an account from which messages will
be sent and received.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for signal_bot_framework-0.2.2a0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8a410a31db3f05d886d6a067669af26ea5a72f5c68e3e1620f5345d0536c4800 |
|
MD5 | 60c2ee12646c3f7b6e4958f340b74c31 |
|
BLAKE2b-256 | af8455f837221408a1464c8047230f65e7c134216f0b1022f43957231aa72f6b |
Hashes for signal_bot_framework-0.2.2a0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 489e4a717b399a572986031385a3da087dee928cca1afafa5e45aa13d2f42df8 |
|
MD5 | 14e74b02314c1852045f676fa7046493 |
|
BLAKE2b-256 | 6f10260a8c032b5f6d784426f447699941ee2be97531a7b82be10f8cef1776d8 |