Signal Bot

Connect your AI agent to Signal via a local signal-cli-rest-api bridge — end-to-end encrypted, no cloud tokens

Connect your AI agent to Signal — end-to-end encrypted, linked through a local signal-cli-rest-api bridge, no cloud bot token needed.

from praisonaiagents import Agent
from praisonai_bot.bots import SignalBot

agent = Agent(name="assistant", instructions="Be helpful on Signal.", llm="gpt-4o-mini")
bot = SignalBot(account="+15551234567", bridge_url="http://localhost:8080", agent=agent)

import asyncio
asyncio.run(bot.start())

The user messages you on Signal; the bridge relays the chat to the agent and the agent replies in the same thread.

Quick Start

1. One command (CLI)

   The quickest way to run Signal — no Python needed:

   praisonai bot run --platform signal \
       --account +15551234567 \
       --bridge-url http://bridge:8080 \
       --agent agents.yaml

   The --account / --bridge-url flags are generated from Signal’s ChannelDescriptor.config_fields. bot run starts any registered platform by name. See praisonai bot run for the full flag list.

2. Run the bridge

   Signal links a device through the signal-cli-rest-api bridge. Start it with Docker in native mode.

   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

3. Link your device

   Open the bridge link URL, then scan the QR from Signal → Settings → Linked Devices → Link New Device.

   http://localhost:8080/v1/qrcodelink?device_name=praisonai

4. Start the bot

   Point the bot at your linked account and the bridge.

   from praisonaiagents import Agent
   from praisonai_bot.bots import SignalBot
   
   agent = Agent(name="assistant", instructions="Be helpful on Signal.", llm="gpt-4o-mini")
   bot = SignalBot(account="+15551234567", bridge_url="http://localhost:8080", agent=agent)
   
   import asyncio
   asyncio.run(bot.start())

   Message your linked Signal number and the agent replies.

How It Works

Signal is poll-based: the bot fetches inbound envelopes from the bridge, routes text to the agent, and sends the reply back through the bridge.

sequenceDiagram
    participant User as 📱 Signal User
    participant Bridge as 📡 Bridge
    participant Bot as 🤖 SignalBot
    participant Agent as 🧠 Agent

    User->>Bridge: Send message
    loop Every poll_interval
        Bot->>Bridge: GET /v1/receive/{account}
        Bridge-->>Bot: Envelopes (DMs + groups)
    end
    Bot->>Agent: chat(content)
    Agent-->>Bot: Response
    Bot->>Bridge: POST /v2/send
    Bridge-->>User: Reply

    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff

    class User user
    class Bridge,Bot process
    class Agent agent

The adapter talks HTTP/JSON to these bridge endpoints:

Inbound liveness. A delivered envelope refreshes the Signal channel’s last_activity for the shared Channel Supervision health monitor. Successfully-empty polls do not refresh it, so a silently half-open bridge (returns [] forever without raising) trips stale-socket after stale_after seconds and the supervisor reconnects — instead of the bot going quietly deaf.

Configuration

Signal needs an account and a bridge URL. Configure it with YAML, environment variables, or the Python SDK.

# bot.yaml
channels:
  signal:
    account: "+15551234567"
    bridge_url: "http://localhost:8080"
    allowed_users: ["+15557654321"]

from praisonai_bot.bots import BotOS

BotOS(agent=agent, platforms=["telegram", "signal"]).start()

export SIGNAL_ACCOUNT="+15551234567"
export SIGNAL_BRIDGE_URL="http://localhost:8080"

from praisonaiagents import Agent
from praisonai_bot.bots import SignalBot

agent = Agent(name="assistant", instructions="Be helpful.", llm="gpt-4o-mini")
bot = SignalBot(agent=agent)  # reads SIGNAL_ACCOUNT / SIGNAL_BRIDGE_URL

import asyncio
asyncio.run(bot.start())

from praisonaiagents import Agent
from praisonai_bot.bots import SignalBot

agent = Agent(name="assistant", instructions="Be helpful.", llm="gpt-4o-mini")

bot = SignalBot(
    account="+15551234567",
    bridge_url="http://localhost:8080",
    agent=agent,
    allowed_users=["+15557654321"],
    poll_interval=1.0,
)

import asyncio
asyncio.run(bot.start())

Config keys

Constructor parameters

Capabilities & Limits

Signal declares honest capabilities so shared engines degrade correctly.

Built-in Commands

Every Signal channel ships these commands out of the box.

Register custom commands:

@bot.on_command("ping")
async def ping(msg):
    return "Pong!"

DM Allowlist

Restrict who can DM the bot with allowed_users — phone numbers are normalised to digits so formatting never blocks a match.

bot = SignalBot(
    account="+15551234567",
    agent=agent,
    allowed_users=["+1 555 765 4321", "15559876543"],
)

Groups pass through the allowlist — group membership is the gate there, not the DM list.

What’s Not Supported Yet

This release ships text messaging plus inbound voice-note transcription. The following are intentionally not wired:

Troubleshooting

pip install aiohttp

Best Practices

Inbound voice notes

Signal voice notes are transcribed automatically — the bot fetches the audio attachment from the signal-cli-rest-api bridge and the agent receives the transcript as plain text. STT is on by default; tune or opt out with the shared stt: block.

channels:
  signal:
    platform: signal
    account: ${SIGNAL_ACCOUNT}
    bridge_url: ${SIGNAL_BRIDGE_URL}
    stt:
      enabled: true
      language: en

The DM allowlist runs before the bridge download, so rejected senders never trigger a transcription request. See Voice Notes for the full STT configuration.

Standalone scheduled delivery (no gateway)

You do not need a running Signal Bot process to deliver a scheduled brief to Signal. Point SIGNAL_ACCOUNT at your linked sender number (and, if the bridge is not on http://localhost:8080, set SIGNAL_BRIDGE_URL). From OS cron / CI, praisonai schedule tick will POST to {SIGNAL_BRIDGE_URL}/v2/send using an explicit deliver: signal:<recipient> target or SIGNAL_HOME_CHANNEL. The bridge must be reachable from wherever the tick fires. See Out-of-process delivery.

Related