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
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 . $ 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
- stickerbot, links to the sticker pack for received stickers
- timerbot, sends an alert after a predefined time
- quotebot, quotes and repeats received messages
- xkcdbot, replies with latest XKCD comic
Changelog
v0.9.0
- Support for typing indicators
- Support for GroupsV2 (thanks @thefinn93)
- Example sticker bot (thanks @iomintz)
- Compatibility with signald 0.11.0+
v0.8.0
- Support for Python 3.9
- Support for executing multiple handlers in parallel (thanks @iomintz)
- Support incoming sticker messages (thanks @iomintz)
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 (thanks @iomintz)
- 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.9.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b89323ead6ba25710a28ac1e5f68bff86ca367336c25a6c921fff56f96111af |
|
MD5 | ad2f9b33c05991cce23a7b466c79cce5 |
|
BLAKE2b-256 | ff6d20b543dc6dd31b921a280415bdb6c5b2d4d269189f588444d086b51a9468 |