Signal.Bot 0.1.0

Signal.Bot

<div align="center">

<img alt="Signal.Bot logo" height="128" src="https://raw.githubusercontent.com/st0o0/Signal.Bot/eb7e4e5c69480e29a635b5f93b764aff899b3eba/docs/logo/logo.png" width="128"/>

A .NET Signal Messenger Bot Client - because sometimes Telegram isn't enough

</div>

What is Signal.Bot?

Signal.Bot wraps the signal-cli-rest-api with a clean, intuitive interface inspired by Telegram.Bot. If you've ever wanted to build a Signal bot in .NET but were put off by the lack of proper tooling - this is for you.

Key highlights:

• Telegram.Bot-inspired API — feels immediately familiar
• Built-in polling via StartReceiving
• Full feature support: messages, attachments, groups, profiles
• Modern async/await with proper CancellationToken handling

Prerequisites

Signal.Bot requires signal-cli-rest-api as a backend. The quickest way to get it running is via Docker:

mkdir -p $HOME/.local/share/signal-api

docker run -d --name signal-api --restart=always -p 8080:8080 \
  -v $HOME/.local/share/signal-api:/home/.local/share/signal-cli \
  -e 'MODE=native' \
  bbernhard/signal-cli-rest-api

Link your Signal number

Option 1 – Link as Secondary Device (Recommended)

Open http://localhost:8080/v1/qrcodelink?device_name=signal-bot in your browser, then scan the QR code via Signal → Settings → Linked Devices.

Option 2 – Register a New Number

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

Installation

# Package Manager
Install-Package Signal.Bot

# .NET CLI
dotnet add package Signal.Bot

<PackageReference Include="Signal.Bot" Version="1.0.0"/>

Quick Start

using Signal.Bot;
using Signal.Bot.Types;

var client = new SignalBotClient(builder => builder
    .WithBaseUrl("http://localhost:8080")
    .WithNumber("+1234567890"));

using var cts = new CancellationTokenSource();

client.StartReceiving(
    async (botClient, message, ct) =>
    {
        var text = message.Envelope?.DataMessage?.Message;
        Console.WriteLine($"Received from {message.Account}: {text}");

        if (!string.IsNullOrEmpty(text))
        {
            await botClient.SendMessageAsync(builder => builder
                .WithRecipient(message.Envelope!.SourceNumber!)
                .WithMessage($"You said: {text}"),
                cancellationToken: ct);
        }
    },
    async (botClient, error, ct) =>
    {
        Console.WriteLine($"Error: {error.ErrorType}: {error.Exception?.Message}");
        await Task.CompletedTask;
    },
    builder => builder.WithMaxMessages(1),
    cts.Token);

Console.WriteLine("Bot is running. Press any key to stop...");
Console.ReadKey();
cts.Cancel();

Features

Architecture

Your Application
      │
      ▼
Signal.Bot          ← This library
(SignalBotClient)
      │
      ▼
signal-cli-rest-api ← Docker container
(HTTP REST API)
      │
      ▼
Signal Servers

Configuration

Performance Modes

Set via the MODE environment variable:

Troubleshooting

Bot not receiving messages? Make sure you're registered and the container is running: docker ps. Test the API with curl http://localhost:8080/v1/about.

"Connection refused" errors? Check your port mapping and that the URL you configured matches the running container.

Messages not sending? Verify the recipient is a valid Signal number and check container logs: docker logs signal-api.

Contributing

1. Fork the repo and create a feature branch: git checkout -b feature/my-feature
2. Write tests and make sure they pass: dotnet test
3. Open a Pull Request

Please keep changes focused, follow the existing code style, and update docs for any API changes.

License

MIT — see LICENSE for details.

Built with ❤️ for the .NET and Signal communities · Open an issue

Related Projects

• signal-cli-rest-api — Required backend
• signal-cli — Underlying CLI tool
• Telegram.Bot — Design inspiration