Semaphore

A simple (rule-based) bot library for Signal Private Messenger in Python. Please note that this library is unofficial, unapproved and not nearly as secure as the real Signal clients.

Requirements
Installation
Quick start
Code example
Example bots
Changelog
License

Requirements

signald 0.23.0 or later, a daemon that facilitates communication over Signal

Installation

Install signald or build from source

$ git clone https://gitlab.com/signald/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
$ make build
$ make install

Quick start

Start signald

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

Open a new terminal and connect to signald control socket
```
$ nc -U $XDG_RUNTIME_DIR/signald/signald.sock
```
(or /var/run/signald/signald.sock for older versions of signald, see signald docs)
Register phone number with Signal by sending following message on the control socket (replace +xxxxxxxxxxx with bot Signal number). Sometimes Signal requires completion of a captcha to register.
```
{"type": "register", "version": "v1", "account": "+xxxxxxxxxxx"}
```
Verify phone number with SMS verification code by sending following message on the control socket (replace +xxxxxxxxxxx with bot Signal number and zzzzzz with verification code)
```
{"type": "verify", "version": "v1", "account": "+xxxxxxxxxxx", "code": "zzzzzz"}
```
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", "version": "v1", "username": "+xxxxxxxxxxx", "recipientAddress": {"number": "+yyyyyyyyyyy"}, "messageBody": "Hello world"}
```
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 examples/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!

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:
        # Set profile name.
        await bot.set_profile("Semaphore example 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
broadcastbot, send broadcast to all subscribers
btcbot, sends notification when BTC price drops below a set price
echobot, repeats received messages
exceptionbot, with custom exception handler
expirationbot, sets the message expiration timer for a chat to random value
groups, manage groups
lovebot, loves everything you say!
profilebot, retrieves profile for personal touch
quotebot, quotes and repeats received messages
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
xkcdbot, replies with latest XKCD comic

Changelog

v0.16.0

Compatibility with signald 0.23.0+
Add method to retrieve profile of message sender

v0.15.0

Compatibility with signald 0.22.0+
Add option to automatically accept group invites

v0.14.0

Compatibility with signald 0.18.0+
Migrate to latest version of anyio (3.5.0)
Add Dockerfile to run Signal bot in container
Add support for link previews (thanks @Era-Dorta)

v0.13.0

Compatibility with signald 0.17.0+
Add method to set expiration timer of chat (thanks @Era-Dorta)
Example expiration timer bot

v0.12.0

Compatibility with signald 0.15.0+
Add support for emoji and about to in profile (thanks @EsEnZeT)
Add option to throw signals errors on send (thanks @eknoes)

v0.11.0

Compatibility with signald 0.14.0+ (signald protocol v1)
Add support for waiting on signald send confirmation (thanks @eknoes)
Add support for sending messages to groups (thanks @brazuzan)

v0.10.1

Add method to set profile name and profile picture
Store e164 phone number and uuid for received messages

v0.10.0

Add support for sending messages without previous context (thanks @eknoes)
Add support for exception handlers (thanks @eknoes)
Add ability to set profile picture (thanks @eknoes)
Support signald client protocol v1
Compatibility with signald 0.12.0+

v0.9.1

Fix repeating job re-add to queue (thanks @grandchild)

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.

sks444/semaphore