Skip to main content
The Signal interface lets your agent respond to messages on Signal, the privacy-focused messenger. It communicates through signal-cli-rest-api, a Docker container that bridges Signal’s protocol.

​
Setup

Signal requires a signal-cli-rest-api container running alongside your application. You can either let Definable manage the container or run it yourself.

​
Option 1: Auto-Managed Docker

Definable starts and stops the container automatically: 
config = SignalConfig(
  phone_number="+15551234567",
  manage_container=True,
  docker_data_dir="./signal-data",  # Persists registration across restarts
)

​
Option 2: Bring Your Own Container

Run the container yourself and point Definable at it: 
docker run -d --name signal-api \
  -p 8080:8080 \
  -v ./signal-data:/home/.local/share/signal-cli \
  -e MODE=native \
  bbernhard/signal-cli-rest-api:latest
Then register and verify your phone number following the signal-cli-rest-api docs.

​
Installation

No additional pip dependencies are needed — Signal communication happens over HTTP to the Docker container: 
pip install definable

​
Quick Example

import asyncio

from definable.agents import Agent
from definable.interfaces import SignalInterface, SignalConfig
from definable.models import OpenAIChat

agent = Agent(
  model=OpenAIChat(id="gpt-4o"),
  instructions="You are a helpful Signal bot.",
)

signal = SignalInterface(
  agent=agent,
  config=SignalConfig(
    phone_number="+15551234567",
    api_base_url="http://localhost:8080",
  ),
)

asyncio.run(signal.serve_forever())

​
SignalConfig

​
phone_number
str
required
The registered Signal phone number (e.g., "+15551234567").
​
api_base_url
str
default:"http://localhost:8080"
URL of the signal-cli-rest-api server.
​
allowed_phone_numbers
list[str]
default:"None"
Restrict to specific phone numbers. When None, responds to everyone.
​
allowed_group_ids
list[str]
default:"None"
Restrict to specific Signal group IDs. When None, responds in all groups.
​
polling_interval
float
How often to poll for new messages (seconds).
​
trust_all_keys
bool
default:true
Automatically trust all safety number changes.

​
Docker Management

​
manage_container
bool
default:false
When True, Definable starts/stops the Docker container automatically.
​
docker_image
str
default:"bbernhard/signal-cli-rest-api:latest"
Docker image to use.
​
docker_container_name
str
default:"definable-signal-api"
Name for the Docker container.
​
docker_host_port
int
default:8080
Host port to map to the container.
​
docker_data_dir
str
default:""
Directory to mount for persistent data. When empty, uses a temporary directory.
​
docker_startup_timeout
float
How long to wait for the container to start (seconds).
​
docker_mode
str
default:"native"
signal-cli mode. Use "native" for most setups.

​
Features

  • Group and direct messages — responds in both Signal groups and 1:1 conversations
  • Attachments — receives files sent by users
  • Quote/reply context — includes quoted messages for context
  • Auto message splitting — long responses are split to fit Signal’s limits
  • Access control — restrict by phone number or group ID