Signal Bot

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)

Start signal-cli

docker compose up signal-cli -d

Request a verification code

curl -X POST "http://localhost:8080/v1/register/+15551234567" \
  -H "Content-Type: application/json" \
  -d '{"use_voice": false}'

Submit the SMS code

curl -X POST "http://localhost:8080/v1/register/+15551234567/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

Clone

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

Configure

cp .env.example .env

Set at minimum:

SIGNAL_PHONE_NUMBER=+15551234567
SIGNAL_API_URL=http://signal-cli:8080
VAQUILL_API_KEY=vq_key_your_key_here
VAQUILL_COUNTRY_CODE=US

Run

docker compose up -d

Or, if signal-cli is already up:

docker compose up signal-bot -d

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": "+15551234567",
    "recipients": ["+15559876543"]
  }'

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:

signal-cli: Docker image bbernhard/signal-cli-rest-api, env MODE=json-rpc, persistent volume on /home/.local/share/signal-cli.
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.

The official Business API path.

Lightest setup, no Docker required.

Chatbots overview

Compare all six platforms.

Authentication

How Vaquill API keys work.

Overview

MCP Servers

Chatbots

Widgets

Browser

Automation

Features

Prerequisites

Platform setup

Option A: Register a fresh number (primary device)

Option B: Link as a secondary device

Quickstart

Configuration

Commands

Deployment

Docker Compose (recommended)

Dokploy / self-hosted

Risks to plan for

Troubleshooting

WhatsApp

Telegram

Chatbots overview

Authentication

​Features

​Prerequisites

​Platform setup

​Option A: Register a fresh number (primary device)

​Option B: Link as a secondary device

​Quickstart

​Configuration

​Commands

​Deployment

​Docker Compose (recommended)

​Dokploy / self-hosted

​Risks to plan for

​Troubleshooting

​Related

WhatsApp

Telegram

Chatbots overview

Authentication

Features

Prerequisites

Platform setup

Option A: Register a fresh number (primary device)

Option B: Link as a secondary device

Quickstart

Configuration

Commands

Deployment

Docker Compose (recommended)

Dokploy / self-hosted

Risks to plan for

Troubleshooting

Related