Signal Connector

Connect your agent to Signal for private and group messaging via signal-cli using the @elizaos/plugin-signal package.

Prerequisites

• signal-cli installed and a registered/linked Signal account
• signal-cli running in HTTP daemon mode

Configuration

The connector auto-enables when token/botToken/apiKey is set, OR any of authDir/account/httpUrl/httpHost/httpPort/cliPath is set, OR accounts contains configured entries.

Configure in ~/.eliza/eliza.json:

{
  "connectors": {
    "signal": {
      "account": "+1234567890",
      "httpUrl": "http://localhost:8080",
      "dmPolicy": "pairing"
    }
  }
}

Setup

1. Install signal-cli

Install signal-cli and register or link a Signal account:

signal-cli -a +1234567890 register
signal-cli -a +1234567890 verify CODE

2. Start signal-cli in HTTP Mode

signal-cli -a +1234567890 daemon --http localhost:8080

3. Configure Eliza

Add the connectors.signal block to eliza.json as shown in the minimal configuration above.

Disabling

To explicitly disable the connector even when an account is configured:

{
  "connectors": {
    "signal": {
      "account": "+1234567890",
      "httpUrl": "http://localhost:8080",
      "enabled": false
    }
  }
}

Features

The plugin-auto-enable.ts module checks connectors.signal in your config. The plugin auto-enables when any of the following conditions are met (and enabled is not explicitly false):

• token, botToken, or apiKey is truthy (generic trigger fields)
• account is set together with httpUrl
• cliPath is set (signal-cli binary path for auto-start)
• Any of authDir, httpHost, or httpPort is set
• accounts contains at least one configured entry

No environment variable is required to trigger auto-enable — it is driven entirely by the connector config object.

Environment Variables

The runtime injects the following environment variables from your connectors.signal config into process.env, so the plugin can read them at startup:

You do not need to set these manually — they are derived from the connector config at runtime.

Full Configuration Reference

All fields are defined under connectors.signal in eliza.json.

Core Fields

Message Handling

Access Policies

Streaming Configuration

Actions

Reaction Notifications

Heartbeat

{
  "connectors": {
    "signal": {
      "heartbeat": {
        "showOk": true,
        "showAlerts": true,
        "useIndicator": true
      }
    }
  }
}

Multi-Account Support

The accounts field allows running multiple Signal accounts from a single agent:

{
  "connectors": {
    "signal": {
      "accounts": {
        "personal": {
          "account": "+1234567890",
          "httpUrl": "http://localhost:8080",
          "dmPolicy": "pairing"
        },
        "work": {
          "account": "+0987654321",
          "httpUrl": "http://localhost:8081",
          "dmPolicy": "allowlist",
          "allowFrom": ["+1111111111"]
        }
      }
    }
  }
}

Each account entry accepts all the same fields as the top-level connectors.signal configuration. Top-level fields act as defaults that individual accounts can override.

Validation

• When dmPolicy is "open", the allowFrom array must include "*".
• startupTimeoutMs must be between 1000 and 120000 (1-120 seconds).

Related

• Signal plugin reference
• Connectors overview
• Configuration reference