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.

Quick Start (Recommended)

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

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:

# 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

./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

{
    "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

{
    "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.

   The main steps are summarized below:

   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

2. Access the Signal CLI setup page:

   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

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

Initialize the Python Virtual Environment

python -m venv venv
source venv/bin/activate

Add Environment Variables

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

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

pip install -r requirements.txt

Run the Server

# 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.