signal-bot/readme.md

# Signal CLI REST API Integration Guide

This guide will help you set up and run a Signal bot using the Signal CLI REST API. For more details, refer to the [signal cli rest api examples](https://bbernhard.github.io/signal-cli-rest-api/).

## Quick Start (Recommended)

The easiest way to get started is using the deployment script:

```sh
git clone https://github.com/kuhyx/signal-bot
cd signal-bot
cp .env.sample .env
# Edit .env with your configuration
./run.sh
```

The `run.sh` script will:
- Create a Python virtual environment if needed
- Install all dependencies
- Load environment variables from `.env`
- Show configuration status and any missing settings
- Start the server with live reload enabled

## Features

- **Live Reload**: Changes to Python files automatically restart the server
- **Debug Mode**: Test the bot locally using "note to self" messages
- **Automatic Deployment**: GitHub Actions workflow deploys to your server on push to main
- **Unit Tests**: Comprehensive test suite for bot functionality

## Debug Mode

Set `MODE=DBG` in your `.env` file to enable debug mode. In this mode:
- Commands are received from your own "note to self" conversation
- Responses are sent back to yourself instead of to a group
- Perfect for testing without affecting real groups

Set `MODE=PRD` for production mode to process group messages normally.

## Configuration

Create a `.env` file (or copy from `.env.sample`) with the following:

```sh
# Your Signal phone number (linked via QR code)
PHONE_NUMBER="+1234567890"

# Group ID where bot receives messages (not needed in debug mode)
GROUP_ID="your-group-id"

# Group ID where bot sends responses (not needed in debug mode)
GROUP_ID_SEND="your-group-id"

# Optional: The Cat API key
CAT_API=""

# DBG for debug mode, PRD for production
MODE=DBG
```

## Automatic Deployment

The repository includes a GitHub Actions workflow (`.github/workflows/deploy.yml`) that automatically deploys to your server when you push to the `main` branch.

### Setting Up Automatic Deployment

Add the following secrets to your GitHub repository (Settings → Secrets and variables → Actions):

- `DEPLOY_HOST`: Your server's hostname or IP
- `DEPLOY_USER`: SSH username
- `DEPLOY_SSH_KEY`: Private SSH key for authentication
- `DEPLOY_PORT`: SSH port (optional, defaults to 22)
- `DEPLOY_PATH`: Path to the bot on your server (optional, defaults to `~/signal-bot`)

## Running Tests

```sh
./run.sh  # This will set up the environment
source venv/bin/activate
pytest tests/ -v
```

## Message Formats

### Message Sent from the Same Account as the Bot

```json
{
    "envelope": {
        "source": "NAME",
        "sourceNumber": "PHONE_NUMBER",
        "sourceUuid": "SOURCE_ID",
        "sourceName": "USER_DEFINED_NAME",
        "sourceDevice": 69,
        "timestamp": 1719177728639,
        "syncMessage": {
            "sentMessage": {
                "destination": "DEST_NAME",
                "destinationNumber": "DEST_PHONE_NUMBER",
                "destinationUuid": "DEST_SEND_MESSAGE",
                "timestamp": 1719177728639,
                "message": "MESSAGE_CONTENT",
                "expiresInSeconds": 0,
                "viewOnce": false,
                "sticker": {
                    "packId": "166dd1b5b060200035a533bbb0d118ff",
                    "stickerId": 6
                }
            }
        }
    },
    "account": "BOT_ACCOUNT_PHONE_NUMBER"
}
```

### Message Sent from Another Account

```json
{
    "envelope": {
        "source": "NAME",
        "sourceNumber": "PHONE_NUMBER",
        "sourceUuid": "SOURCE_ID",
        "sourceName": "USER_DEFINED_NAME",
        "sourceDevice": 69,
        "timestamp": 1719177917717,
        "dataMessage": {
            "timestamp": 1719177917717,
            "message": "MESSAGE_CONTENT",
            "expiresInSeconds": 0,
            "viewOnce": false,
            "sticker": {
                "packId": "166dd1b5b060200035a533bbb0d118ff",
                "stickerId": 6
            },
            "groupInfo": {
                "groupId": "ID_OF_GROUP_SEND_TO",
                "type": "DELIVER"
            }
        }
    },
    "account": "BOT_ACCOUNT_PHONE_NUMBER"
}
```

## Setting Up Signal CLI REST API

1. Follow the instructions on the [Signal CLI REST API GitHub page](https://github.com/bbernhard/signal-cli-rest-api#getting-started).

    The main steps are summarized below:

    ```sh
    sudo docker run -d --name signal-api --restart=always -p 9922:8080 \
        -v /home/user/signal-api:/home/.local/share/signal-cli \
        -e 'MODE=json-rpc' bbernhard/signal-cli-rest-api:0.167-dev
    ```
    Pay attention to `:0.167-dev`! Try to upgrade if there is a new one as you can see errors connected with connecting your signal account otherwise.
    Double check if you are using correct version using: [http://localhost:9922/v1/about](http://localhost:9922/v1/about)

2. Access the Signal CLI setup page:

    ```sh
    http://localhost:9922/v1/qrcodelink?device_name=signal-api
    ```

3. Scan the QR code to complete the Signal CLI setup.

## Manual Setup (Alternative)

If you prefer to set up manually instead of using `run.sh`:

### Clone the Repository

```sh
git clone https://github.com/kuhyx/signal-bot
```

### Initialize the Python Virtual Environment

```sh
python -m venv venv
source venv/bin/activate
```

### Add Environment Variables

Create a `.env` file or add to `venv/bin/activate`:

```sh
export PHONE_NUMBER="+69YOURPHONENUMBER"
export CAT_API="CAN_LEAVE_BLANK"
export GROUP_ID="MESSAGES_SEND_HERE_WILL_TRIGGER_COMMANDS"
export GROUP_ID_SEND="TRIGGERED_COMMANDS_WILL_SEND_DATA_HERE"
export MODE="DBG"  # or PRD for production
```

### Install Required Python Packages

```sh
pip install -r requirements.txt
```

### Run the Server

```sh
# With live reload (recommended for development)
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Or simply
./run.sh
```

Now your Signal bot should be up and running, ready to send and receive messages via the Signal CLI REST API.