Semaphore: A simple (rule-based) bot library for Signal Private Messenger.
Project description
Semaphore
A simple (rule-based) bot library for Signal Private Messenger in Python.
Table of contents
Requirements
- signald 0.10.0+, a daemon that facilitates communication over Signal
Installation
-
Install signald or build from source
$ git clone https://gitlab.com/thefinn93/signald.git $ cd signald $ make installDist $ make setup
-
Install Semaphore
Latest release from PyPi:
$ pip install semaphore-bot
From source with pip:
$ pip install git+https://github.com/lwesterhof/semaphore.git
From source:
$ git clone https://github.com/lwesterhof/semaphore.git $ cd semaphore $ python -m pip install -r requirements.txt $ python setup.py sdist bdist_wheel $ python -m pip install dist/semaphore-*.tar.gz
Quick start
-
Start signald
$ cd signald $ build/install/signald/bin/signald
-
Open a new terminal and connect to signald control socket
nc -U /var/run/signald/signald.sock
-
Register phone number with Signal by sending following message on the control socket (replace
+xxxxxxxxxxx
with bot Signal number){"type": "register", "username": "+xxxxxxxxxxx"}
-
Verify phone number with SMS verification code by sending following message on the control socket (replace
+xxxxxxxxxxx
with bot Signal number andzzz-zzz
with verification code){"type": "verify", "username": "+xxxxxxxxxxx", "code": "zzz-zzz"}
-
Verify Signal is working by sending following message on the control socket (replace
+xxxxxxxxxxx
with bot Signal number and+yyyyyyyyyyy
with your Signal number){"type": "send", "username": "+xxxxxxxxxxx", "recipientAddress": {"number": "+yyyyyyyyyyy"}, "messageBody": "Hello world"}
-
Subscribe to receive messages for the bot by sending following message on the control socket (replace
+xxxxxxxxxxx
with bot Signal number){"type": "subscribe", "username": "+xxxxxxxxxxx"}
-
Open a new terminal and set the
SIGNAL_PHONE_NUMBER
environment variable to your phone number:$ export SIGNAL_PHONE_NUMBER=+xxxxxxxxxxx
-
Start the example echo bot
$ python echobot.py
-
Send message to Signal bot running on
+xxxxxxxxxxx
and wait for an echo -
Now you can start writing your own bot for Signal Private Messenger!
Demo
A demonstration bot is running on +31686100384
.
Do not send anything confidential, use at your own risk!
Code example
import anyio
from semaphore import Bot, ChatContext
# Connect the bot to number.
bot = Bot("+xxxxxxxxxxx")
@bot.handler('')
async def echo(ctx: ChatContext) -> None:
await ctx.message.reply(ctx.message.get_body())
async def main():
async with bot:
# Run the bot until you press Ctrl-C.
await bot.start()
anyio.run(main)
Example bots
The following example bots can be found in examples:
- apodbot, replies with Astronomy Picture of the Day
- bbcbot, replies with latest BBC headlines
- btcbot, sends notification when BTC price drops below a set price
- echobot, repeats received messages
- lovebot, loves everything you say!
- spongebot, repeats received messages in sPOngEbOb sqUArepAnTs text
- timerbot, sends an alert after a predefined time
- quotebot, quotes and repeats received messages
- xkcdbot, replies with latest XKCD comic
Changelog
v0.8.0
- Support for Python 3.9
- Support for executing multiple handlers in parallel
- Support incoming sticker messages
v0.7.1
- Support for decorators to register handlers
- Support for sending delivery receipts
- Mark messages as read by default
v0.7.0
- Compatibility with signald 0.10.0+
- Support for multiple replies/reactions by handler
- Marking messages as read is optional
- First release on PyPi
v0.6.0
- Support for message reactions
- Example message reaction bot
v0.5.0
- Improve the logging system
- Add logging to job queue
- Strict typing
v0.4.0
- Support for recurring jobs
- Example BTC price notification bot
v0.3.0
- Support for scheduled jobs
- Example timer bot
v0.2.0
- Support for quoting messages
- Example quote bot
v0.1.0
- First release on Github
License
This project is licensed under the AGPL-v3 license. The full license can be found in LICENSE.txt.
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 semaphore_bot-0.8.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 95128b9b147d3fb2920ec7fcaf2f5004f2738dd40124c6b0a35728b268710a17 |
|
MD5 | f717d303c77691b0c305d7d7814a0529 |
|
BLAKE2b-256 | 59fcd76bcba7f3bd29a006aa04e557872bdaec1925d3b4824fe5b03e09074930 |