Welcome to Signal-Bot’s documentation!

Signal-Bot is an asyncio Python 3.11 module for building Signal bots that interact with AsamK/signal-cli.

Installation and Basic Usage 

Install with Pip: python3.11 -m pip install signal_bot_framework.

# test_bot.py
import asyncio
from signal_bot_framework import create, AccountNumber

async def do_crabby(signal, context, message):
        await signal.send_reaction(message, "🦀")
        await signal.send_message(context[1], 
            "Sorry, just feeling a little crabby.")
        return True

async def main():
    # The default, finds `signal-cli` on path and launches it
    connection = 'ipc://'
    signal = await create(AccountNumber('+12345678900'), connection)
    signal.on_keyword('ok?', do_crabby)
    await signal.run()

if __name__ == '__main__':
    asyncio.run(main())

Docker 

For convenience, a base Docker image can be built as sidneys1/signal_bot, based on python:3.11-alpine. You can base your bot on it like so:

FROM sidneys1/signal_bot:latest

COPY ./test_bot.py .

CMD ["python", "test_bot.py"]

You can easily combine this in Docker-Compose with a signal-cli container. Make sure to change your test_bot.py’s connection string to tcp://signal-cli:7583.

Additionally, an easy way to keep your Signal account from being stored in your image or docker-compose.yml is to store it in a Docker secret, as shown below.

secrets:
  signal-account:
    file: .signal-account

services:
  test_bot:
    build: .
    depends_on: [signal-cli]
  signal-cli:
    image: registry.gitlab.com/packaging/signal-cli/signal-cli-native:latest
    volumes:
     # Mount an existing signal-cli configuration directory from the host.
     - "${HOME}/.local/share/signal-cli:/var/lib/signal-cli:rw"
    ports: ["7583"]
    secrets: [signal-account]
    entrypoint: sh -c
    command: "'signal-cli -c /var/lib/signal-cli --account $(cat /run/secrets/signal-account) daemon --receive-mode on-connection --no-receive-stdout --send-read-receipts --tcp 0.0.0.0:7583'"

Building From Source 

Clone this repository and install the prerequisites:
- Python >= 3.11 with venv support (included with Python for Windows, python3.11-venv on most package managers).
- python3.11 -m pip install build
Run python3.11 -m build in the repository folder.
Distribute or install ./dist/signal_bot_framework-X.Y.Z-py3-none-any.whl.