Signal

Sophon connects to Signal through signal-cli-rest-api, a REST wrapper around the signal-cli command-line tool. You'll run signal-cli-rest-api as a Docker container, register a phone number, and point Sophon at the REST endpoint.

Prerequisites

Docker installed on the host machine
A phone number that can receive SMS or voice calls (for Signal registration)
The phone number must not be actively used with the Signal mobile app (Signal only allows one device per number, unless using linked devices)

Step-by-Step Setup

1. Run signal-cli-rest-api

docker run -d --name signal-cli-rest-api \
  -p 8081:8080 \
  -v signal-cli-data:/home/.local/share/signal-cli \
  bbernhard/signal-cli-rest-api

This starts the REST API on port 8081.

2. Register Your Phone Number

# Request a verification code via SMS
curl -X POST "http://localhost:8081/v1/register/+1234567890"

# Or via voice call
curl -X POST "http://localhost:8081/v1/register/+1234567890?voice=true"

Enter the verification code:

curl -X POST "http://localhost:8081/v1/register/+1234567890/verify/123456"

3. Verify Registration

curl "http://localhost:8081/v1/about"

This should return information about the registered number.

4. Configure in Sophon Dashboard

Go to Channels and click Add Channel
Select Signal
Enter the signal-cli REST API Endpoint (e.g., http://localhost:8081)
Enter the Registered Phone Number in international format (e.g., +1234567890)
Click Test Connection
Click Activate

5. Test It

Send a Signal message to the registered phone number. Sophon should respond.

Configuration Reference

Field	Type	Required	Description
`signalCliEndpoint`	url	Yes	URL of the signal-cli-rest-api instance
`phoneNumber`	text	Yes	Registered phone number in international format (e.g., `+1234567890`)

channels.json Example

{
  "id": "signal-bot",
  "type": "signal",
  "name": "Sophon Signal",
  "enabled": true,
  "config": {
    "signalCliEndpoint": "http://localhost:8081",
    "phoneNumber": "+1234567890"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session"
  },
  "status": "connected"
}

Troubleshooting

Registration fails — The phone number may already be registered with Signal on another device. Unregister from the Signal mobile app first, or use a dedicated number.
"Connection refused" — Verify signal-cli-rest-api is running and accessible at the configured endpoint. Check with curl http://localhost:8081/v1/about.
Messages not received — signal-cli-rest-api polls for messages. Ensure the container is running and the phone number is correctly registered. Check container logs with docker logs signal-cli-rest-api.
Rate limiting from Signal — Signal rate-limits message sending. If Sophon sends too many messages in a short period, some may be delayed or blocked.

On this page