elizaos--eliza/plugins/plugin-signal

@elizaos/plugin-signal

Signal messaging integration for elizaOS. Enables Eliza agents to send and receive end-to-end-encrypted Signal messages via signal-cli or its REST API.

What it does

• Receive messages — inbound Signal DMs and group messages are stored as agent memories and trigger SIGNAL_MESSAGE_RECEIVED events.
• Send messages — agents send DMs and group messages through the elizaOS MessageConnector surface (LifeOps, workflow automations, explicit send actions).
• Contact and group discovery — the plugin exposes Signal contacts and groups as connector targets so agents can resolve conversation destinations by name, phone number, or group.
• QR device linking — HTTP endpoints drive a pairing flow (QR code → signal-cli device link) without requiring a separate phone.
• Multi-account — configure multiple Signal accounts via character.settings.signal.accounts.
• Workflow integration — supplies credentials to the workflow plugin for Signal-backed automations.

Capabilities registered

This plugin registers no actions. Messaging is handled through the MessageConnector interface.

Services:

• SignalService — core connector; manages daemon lifecycle, inbound/outbound messages, contacts, and groups.
• SignalWorkflowCredentialProvider — bridges Signal credentials to the workflow plugin.

Setup routes (no auth required, mounted at raw paths):

• GET /api/setup/signal/status — pairing and connection state
• POST /api/setup/signal/start — begin QR device-linking session
• POST /api/setup/signal/cancel — stop pairing and disconnect

Prerequisites

One of:

• signal-cli installed and on PATH (the plugin can spawn and manage it as a daemon). On macOS, install via Homebrew: brew install signal-cli. Java is required; the plugin auto-detects Homebrew's OpenJDK.
• A running signal-cli REST API server (signal-cli -a +1... daemon --http 127.0.0.1:8080) accessible at SIGNAL_HTTP_URL.
• The optional @elizaos/signal-native peer dependency for QR linking without spawning signal-cli.

The agent's Signal account must be linked (registered or device-linked) before the service can connect. Use the /api/setup/signal/start endpoint or run signal-cli -a +1... link manually.

Configuration

Environment variables

Variable	Required	Default	Description
SIGNAL_ACCOUNT_NUMBER	yes	—	Phone number in E.164 format (e.g. +15551234567)
SIGNAL_HTTP_URL	no	http://127.0.0.1:8080	signal-cli REST API URL; omit to auto-start a local daemon
SIGNAL_CLI_PATH	no	signal-cli (PATH)	Path to signal-cli binary
SIGNAL_CLI_AUTO_INSTALL	no	true	Set false to disable Homebrew auto-install
SIGNAL_AUTH_DIR	no	~/.local/share/signal-cli	signal-cli data directory
SIGNAL_SHOULD_IGNORE_GROUP_MESSAGES	no	false	Set true to respond only to DMs
SIGNAL_AUTO_REPLY	no	false	Set true to have the agent auto-generate replies
SIGNAL_RECEIVE_MODE	no	manual	on-start polls immediately; manual lets LifeOps pull
SIGNAL_STARTUP_TIMEOUT_MS	no	30000	Daemon startup timeout (max 120 000 ms)

Character settings (multi-account)

{
  "settings": {
    "signal": {
      "account": "+15551234567",
      "httpUrl": "http://127.0.0.1:8080",
      "accounts": {
        "work": {
          "account": "+15559876543",
          "httpUrl": "http://127.0.0.1:8081",
          "enabled": true
        }
      }
    }
  }
}

Enabling the plugin

The plugin auto-enables when a signal connector block is present in the agent config and not explicitly set to enabled: false. You can also add it directly to the plugins array:

import signalPlugin from "@elizaos/plugin-signal";

const agent = new AgentRuntime({
  plugins: [signalPlugin],
  // ...
});

Important behavior notes

• Auto-reply is off by default. Inbound messages are recorded as memories and events, but the agent does not respond unless SIGNAL_AUTO_REPLY=true. Use LifeOps or explicit workflow actions to send responses.
• Auth directory: signal-cli always uses ~/.local/share/signal-cli on all platforms (including macOS). This matches the signal-cli default, so an existing local installation works without extra config.
• Message length: messages over 4 000 characters are split automatically.
• Group filtering: set SIGNAL_SHOULD_IGNORE_GROUP_MESSAGES=true to limit the agent to direct messages only.