Bitpart is a messaging tool that runs on top of Signal to support activists, journalists, and human rights defenders.
This repository contains three components: the Bitpart server, a command-line client for connecting to the Bitpart server, and a storage adapter used for storing Signal key information to Bitpart's database. In order to build all three components, make sure you have a 2024 edition of Rust and run:
cargo build
Visit the releases page to download the latest binaries for your operating system and architecture!
The Bitpart server expects certain configuration parameters. The following examples use the parameters defined below:
<BIND>: the IP address and port that Bitpart listens on for client connections. For example,127.0.0.1:3000would mean that Bitpart is listening on port 3000 on localhost. This is only used by the command-line client and is not necessary to expose to the public internet.<AUTH>: the token used to authenticate client connections on the above port. The token must match for both the server and the command-line client for them to be able to connect.<DATABASE>: the path to an SQLite database file where Bitpart stores its state. This file is created if it does not exist.<KEY>: the encryption key for the SQLite database. Bitpart uses an integrated copy of SQLCipher to encrypt its database. If Bitpart creates a new database file, it will be initialized with this key. The key must be the same between different runs of Bitpart or otherwise it will not be able to decrypt its database.
Assuming the bitpart binary is in your path, you can view the inline help for the Bitpart server:
bitpart --help
Or run it as follows:
bitpart --bind <BIND> --auth <AUTH> --database <DATABASE> --key <KEY>
Bitpart can also read configuration parameters from environment variables corresponding to its command-line parameters. For example, you could specify the encryption key via defining the environment variable BITPART_KEY.
Bitpart is available in a Docker-compatible container. For example, to run Bitpart on port 3000 and mounting a database from the current directory:
docker run -d --name bitpart -p 3000:3000 -v ./bitpart.sqlite:/bitpart.sqlite -e BITPART_BIND=127.0.0.1:3000 -e BITPART_DATABASE=/bitpart.sqlite -e BITPART_AUTH=connect to the Bitpart server<AUTH> -e BITPART_KEY=<KEY> ghcr.io/throneless-tech/bitpart:latest
Assuming the bitpart-cli binary is in your path, you can print out the inline help for the command-line client via:
bitpart-cli --help
Or print out the help for a given subcommand via:
bitpart-cli help <SUBCOMMAND>
For example, to list available bots on a Bitpart server listening at <BIND> and with authorization token <AUTH>:
bitpart-cli --auth <AUTH> --connect <BIND> list
When you have the server running as described above, and you have bitpart-cli able to connect to it at location <BIND> with authorization token <AUTH>, you can add a bot:
bitpart-cli --auth <AUTH> --connect <BIND> add --id <BOT_ID> --name <NAME> --default <BASENAME> ./<BASENAME>.csml
where <BOT_ID> is a unique name you choose for the bot, <NAME> is the keyword the bot will respond to when in a group, and <BASENAME> is the name of the default CSML script included in the bot (you can include multiple CSML scripts, but you must specify which one is used by default for new conversations). To find out more about CSML scripting, check out the example(s) in the examples directory in this repository.
To link the bot you created to Signal so that it receives messages, you must open a channel between the bot and a Signal account. We recommend using a separate Signal account just for this purpose, since Bitpart will also receive and respond to the Signal messages sent to this account.
bitpart-cli --auth <AUTH> --connect <BIND> channel-link --id signal --bot-id <BOT_ID> --device-name <DEVICE_NAME>
where <BOT_ID> is the id of the bot you're linking, and <DEVICE_NAME> is the name of the device as it will appear in the list of linked devices on Signal (for example, bitpart). Currently the channel ID is always signal, because that's the only type of channel available.
After you enter this command, a QR code will be displayed. In your Signal client, go to Settings -> Linked Devices -> Link new device and take a picture of the QR code. After a few seconds, your bot will finish linking with Signal. From another Signal device, send a message to the number or username associated with the bot (NOTE: the bot will take on the profile information of the linked device) and it should reply!
Bitpart's conversation logic is defined by scripts written in the open-source Conversational Standard Meta Language, or CSML. Visit the documentation from the CSML project to learn how to write a CSML conversation flow. Each instance of Bitpart can run one or more bots, where each bot processes incoming messages according to one or more CSML flows.
Bitpart is a free software project licensed under the GNU Affero General Public License v3.0 (AGPLv3). Parts of it are derived from code from the Presage and CSML projects, marked where appropriate.