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, edit the example echo bot and replace
+xxxxxxxxxxx
with the Signal bot number:$ cd semaphore/examples/ $ vim echobot.py
-
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
from semaphore import Bot, ChatContext
def echo(ctx: ChatContext) -> None:
ctx.message.reply(body=ctx.message.get_body())
def main():
"""Start the bot."""
# Connect the bot to number.
bot = Bot("+xxxxxxxxxxx")
# Add handler to bot.
bot.register_handler("", echo)
# Run the bot until you press Ctrl-C.
bot.start()
if __name__ == '__main__':
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.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 GPL-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.7.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e820d480740fe3d7f4017b4f8be9b264af58b2ac515f3993bfb47c356c0c9098 |
|
MD5 | 44a04db7820c8f37f4b1da5d837cc480 |
|
BLAKE2b-256 | 57b866917423f4ebaa36c5841f74fd1d54344d941906e251915d6a998bc1b68c |