Signal Bot

Vaquill legal AI on Signal via signal-cli-rest-api - Docker Compose stack with primary or linked-device registration.

A Signal messenger bot for Vaquill, built on the unofficial signal-cli-rest-api and the signalbot Python framework. Two Docker containers - signal-cli (handles the Signal protocol) and signal-bot (Python app calling Vaquill) - communicate over a local WebSocket. Source code at github.com/Vaquill-AI/integrations/signal-bot.

Signal does not offer an official bot API. This integration uses the unofficial signal-cli project. Account ban risk exists if Signal’s anti-abuse systems detect bot-like behavior. Keep volume low, use a dedicated phone number, and pin Docker image versions in production.

Features

• Plain-text Q&A via the Vaquill /ask API
• Per-chat conversation history
• Slash-like commands: help, examples, stats, clear
• Runs entirely inside a local Docker network - no public URL required

Prerequisites

• Docker and Docker Compose
• A phone number you control for Signal registration (or an existing Signal account you can link as a secondary device)
• Vaquill API key (vq_key_...). See Authentication.

Platform setup

You need to either register a fresh phone number with Signal, or link the bot as a secondary device on an existing Signal account.

Option A: Register a fresh number (primary device)

1. Start signal-cli

   docker compose up signal-cli -d
   
2. Request a verification code

   curl -X POST "http://localhost:8080/v1/register/[phone]" \
     -H "Content-Type: application/json" \
     -d '{"use_voice": false}'
   
3. Submit the SMS code

   curl -X POST "http://localhost:8080/v1/register/[phone]/verify/123456"
   

Option B: Link as a secondary device

This keeps your existing Signal phone active and avoids re-registering a number:

curl "http://localhost:8080/v1/qrcodelink?device_name=vaquill-bot"

Open the returned URL (or scan the QR), then in your Signal mobile app go to Settings > Linked Devices > Add a new device and scan it.

The registration is tied to the signal-cli Docker volume. Back it up - losing the volume means re-registering and a new Signal safety number.

Quickstart

1. Clone

   git clone https://github.com/Vaquill-AI/integrations.git
   cd integrations/signal-bot
   
2. Configure

   cp .env.example .env
   

   Set at minimum:

   SIGNAL_PHONE_NUMBER=[phone]
   SIGNAL_API_URL=http://signal-cli:8080
   VAQUILL_API_KEY=vq_key_your_key_here
   VAQUILL_COUNTRY_CODE=US
   
3. Run

   docker compose up -d
   

   Or, if signal-cli is already up:

   docker compose up signal-bot -d
   
4. Verify

   curl http://localhost:8080/v1/about
   curl http://localhost:8080/v1/accounts
   

   Send yourself a test message:

   curl -X POST "http://localhost:8080/v2/send" \
     -H "Content-Type: application/json" \
     -d '{
       "message": "Hello from Vaquill!",
       "number": "[phone]",
       "recipients": ["[phone]"]
     }'
   

   Then DM the bot’s number from another Signal account and ask:

   What is qualified immunity under 42 USC 1983?
   

Configuration

Variable	Required	Default	Description
SIGNAL_PHONE_NUMBER	Yes	-	Registered or linked Signal number, E.164 format
SIGNAL_API_URL	Yes	http://signal-cli:8080	URL of the signal-cli-rest-api container
VAQUILL_API_KEY	Yes	-	Vaquill API key (vq_key_...)
VAQUILL_API_URL	No	https://api.vaquill.ai/api/v1	API base URL
VAQUILL_MODE	No	standard	standard or deep
VAQUILL_COUNTRY_CODE	No	-	Jurisdiction filter, e.g. US

See .env.example for the full list.

Commands

Command	Description
help	Show available commands
examples	Show example legal questions
stats	View usage statistics
clear	Clear conversation history
hi / hello	Start a fresh conversation

Any other text is treated as a legal question and routed to Vaquill.

Deployment

Docker Compose (recommended)

Deploy both services on the same Docker network. The signal-cli service needs a persistent volume mounted at /home/.local/share/signal-cli to retain the registration.

services:
  signal-cli:
    image: bbernhard/signal-cli-rest-api:latest
    environment:
      - MODE=json-rpc
    ports:
      - "8080:8080"
    volumes:
      - signal-cli-data:/home/.local/share/signal-cli
    restart: unless-stopped

  signal-bot:
    build: .
    env_file: .env
    depends_on:
      - signal-cli
    restart: unless-stopped

volumes:
  signal-cli-data:

Dokploy / self-hosted

Deploy as two separate applications in the same project:

1. signal-cli: Docker image bbernhard/signal-cli-rest-api, env MODE=json-rpc, persistent volume on /home/.local/share/signal-cli.
2. signal-bot: Build from the Dockerfile in signal-bot/, env vars from .env.

Risks to plan for

• No official Signal bot API - this is an unofficial integration.
• Account ban risk if Signal detects automated behavior. Keep volume low and ideally use a dedicated number.
• Protocol breakage - signal-cli updates can break on Signal protocol changes. Pin image versions (bbernhard/signal-cli-rest-api:0.92) in production rather than latest.
• Volume backups - the phone-number registration is tied to the persistent volume. Back it up regularly.

Troubleshooting

Symptom	Fix
curl http://localhost:8080/v1/about fails	signal-cli is not running. docker compose up signal-cli -d.
Registration verify returns 400	Wrong or expired code. Request a new code with /v1/register/<number>.
Bot does not reply	Confirm SIGNAL_PHONE_NUMBER matches the registered number. Check docker compose logs signal-bot.
Vaquill 401	Invalid VAQUILL_API_KEY. Generate a fresh one.
Account suddenly unable to send	Possible ban. Reduce volume and consider switching to a fresh number.

Related

WhatsApp

The official Business API path.

Telegram

Lightest setup, no Docker required.

Chatbots overview

Compare all six platforms.

Authentication

How Vaquill API keys work.