Signalbot¶

Python package to build your own Signal bots.

The package provides methods to easily listen for incoming messages and responding or reacting on them. It also provides a class to develop new handlers, which then can be registered within the bot.

Here is minimal example of what that looks like:

import logging
import os

from signalbot import (
    Config,
    DataMessageContext,
    DataMessageHandler,
    SendMessage,
    SignalBot,
    text_triggered,
)


class PingCommand(DataMessageHandler):
    @text_triggered("Ping")
    async def handle_data_message(self, context: DataMessageContext) -> None:
        await context.send(SendMessage(text="Pong"))


if __name__ == "__main__":
    bot = SignalBot(
        Config(
            phone_number=os.environ["PHONE_NUMBER"],
            logging_level=logging.INFO,
        )
    )
    bot.register(PingCommand())
    bot.start()

To set it up follow the steps in the getting started page. See How it works for a visual walkthrough of how a message travels from signal-cli-rest-api to your handler and back.

Methods overview¶

The bot can do a lot more, here is an overview of the methods available on the context passed into a Handler:

Action	Method
Send a new message	`context.send(SendMessage(text=...))`
Reply, quoting the received message	`context.reply(SendMessage(text=...))` *
Edit a previously sent message	`context.edit(SendMessage(text=...), original_message)` *
Delete a previously sent message	`context.remote_delete(sent_message)` *
React to a message	`context.react("emoji")` *
Mark a message as read	`context.send_receipt(ReceiptType.READ)` *
Delete the local copy of an attachment	`context.delete_attachment(attachment)` *
Start typing	`context.start_typing()`
Stop typing	`context.stop_typing()`
Change group settings	`context.update_group(UpdateGroup(name=...))`
Update a contact	`context.update_contact(UpdateContact(name=...))`
Create a poll	`context.create_poll(CreatePoll(question=..., answers=[...]))`

* Only available on DataMessageContext.

A few methods aren't tied to a specific message and only exist on bot:

bot.register(handler): Register a new handler
bot.start(): Start the bot
bot.scheduler: Schedule tasks, see the scheduler examples.
bot.storage (SQLiteStorage or RedisStorage): Store and read data on disk with a db.

Every method above can also be called directly on the bot, outside a handler, by supplying the recipient yourself, e.g. bot.messages.send(SendMessage(text=...), recipient).

Real world bot examples¶

There are many real world examples of bot implementations using this library. Check the whole list at https://github.com/signalbot-org/signalbot/network/dependents