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, Account
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(Account('+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.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f70dfa4fc36db67b3b540806874360f12c4a5d1beff11158efca611e3e9bd373 |
|
MD5 | 82edd62a2a2fdaab2c9cfa1c3ed14908 |
|
BLAKE2b-256 | bbebec19ab78d94d7e00d268b681f7f1557201f035bcc543ac5d51c39f4cf6b6 |
Hashes for signal_bot_framework-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5092c4fe86c2a10f66f447767fd2ffaa796bada9ecbcfe9b5bd8e716ff940087 |
|
MD5 | a0a5fcb6b9bfeb6c472cca3e86444a83 |
|
BLAKE2b-256 | 2510d33ff30aeb8a774bc61c99136fade49355f14149df41d89009c3110304d6 |