thefinn93 / semaphore

A simple (rule-based) bot library for Signal Private Messenger.

Semaphore

A simple (rule-based) bot library for Signal Private Messenger in Python.

Table of contents

• Requirements
• Installation
• Quick start
• Demo
• Code example
• Example bots
• Changelog
• License

Requirements

• 
• signald (01f4e764 or later), a daemon that facilitates communication over Signal

Installation

1. Install signald or build from source

   $ git clone https://gitlab.com/thefinn93/signald.git
   $ cd signald
   $ make installDist
   $ make setup

2. 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

1. Start signald

   $ cd signald
   $ build/install/signald/bin/signald

2. Open a new terminal and connect to signald control socket

   nc -U /var/run/signald/signald.sock

3. Register phone number with Signal by sending following message on the control socket (replace +xxxxxxxxxxx with bot Signal number)

   {"type": "register", "username": "+xxxxxxxxxxx"}

4. Verify phone number with SMS verification code by sending following message on the control socket (replace +xxxxxxxxxxx with bot Signal number and zzz-zzz with verification code)

   {"type": "verify", "username": "+xxxxxxxxxxx", "code": "zzz-zzz"}

5. 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"}

6. 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"}

7. Open a new terminal and set the SIGNAL_PHONE_NUMBER environment variable to your phone number:

   $ export SIGNAL_PHONE_NUMBER=+xxxxxxxxxxx

8. Start the example echo bot

   $ python echobot.py

9. Send message to Signal bot running on +xxxxxxxxxxx and wait for an echo

10. Now you can start writing your own bot for Signal Private Messenger!

Demo

A demonstration bot is running on [phone]. 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.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.