Nacorpio.Signal.Domain 0.5.0-preview.1

This is a prerelease version of Nacorpio.Signal.Domain.
dotnet add package Nacorpio.Signal.Domain --version 0.5.0-preview.1
                    
NuGet\Install-Package Nacorpio.Signal.Domain -Version 0.5.0-preview.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Nacorpio.Signal.Domain" Version="0.5.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Nacorpio.Signal.Domain" Version="0.5.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="Nacorpio.Signal.Domain" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Nacorpio.Signal.Domain --version 0.5.0-preview.1
                    
#r "nuget: Nacorpio.Signal.Domain, 0.5.0-preview.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Nacorpio.Signal.Domain@0.5.0-preview.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Nacorpio.Signal.Domain&version=0.5.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Nacorpio.Signal.Domain&version=0.5.0-preview.1&prerelease
                    
Install as a Cake Tool

Signal.NET

CI Docs NuGet License: MIT

A .NET 11 / C# 15 framework for building Signal bots and integrations on top of bbernhard/signal-cli-rest-api (Swagger).

  • DDD layering – pure domain model, application ports, infrastructure adapters, hosting.
  • DI everywhere – every service is registered with TryAdd* and can be replaced.
  • Text command system – class-based or attribute-based commands, typed argument binding, flags, preconditions, cooldowns, generated help.
  • appsettings.json configuration – validated on startup, hot-reloadable command/access settings.
  • All four container modes – normal, native (HTTP polling) and json-rpc, json-rpc-native (WebSocket push).

Installation

Start a new bot from the template:

dotnet new install Nacorpio.Signal.Templates
dotnet new signalbot -n MyBot --mode JsonRpc --account +4915112345678

Or add Signal.NET to an existing project. Signal.NET uses C# 15 unions, so set <LangVersion>preview</LangVersion>.

dotnet add package Nacorpio.Signal.Hosting --prerelease

Nacorpio.Signal.Hosting pulls in Nacorpio.Signal.Infrastructure, Nacorpio.Signal.Application and Nacorpio.Signal.Domain. The packages are owner-prefixed because the Signal. ID prefix is reserved on nuget.org; the assemblies and namespaces are still Signal.*.

Documentation

The documentation site is at https://nacorpio.github.io/Signal.NET/. It contains the guides and the full API reference. The guides are also in docs/: architecture, domain, application, the command system, infrastructure, hosting, the configuration reference, execution modes, extensibility, and samples and testing.

Every public type and member also has XML documentation comments, which IntelliSense shows. Any public member without a comment fails the build.

Solution layout

Project Responsibility
Signal.Domain Value objects (PhoneNumber, GroupId, Recipient), IncomingEnvelope aggregate, OutgoingMessage builder, entities (Group, Contact, Identity), domain events, ExecutionMode. No dependencies.
Signal.Application Ports (IMessageSender, IMessageReceiver, IGroupService, ...), SignalOptions, message middleware pipeline, domain event dispatcher, command system.
Signal.Infrastructure REST adapters (typed HttpClient, source-generated JSON, standard resilience pipeline), envelope mapping, polling and WebSocket receivers keyed by ExecutionMode.
Signal.Hosting AddSignal() + ISignalBuilder, SignalHostedService (receive loops + partitioned processing), health check.
samples/Signal.Sample.Bot Worker service demonstrating commands, event handlers and configuration.

Message flow

signal-cli-rest-api ──(poll | WebSocket)──► IMessageReceiver ──► partition by conversation (N workers)
    ──► new DI scope ──► ExceptionHandling ► Logging ► AccessControl ► RateLimiting ► [your middleware]
    ──► DomainEventMiddleware (IEventHandler<T>) ► CommandMiddleware (parse ► preconditions ► bind ► execute)

Messages from different conversations are processed in parallel (MaxConcurrency), while messages from the same conversation keep their order.

Requirements

  • The .NET 11 SDK preview pinned in global.json. C# 15 preview features (unions, extension members) are used.
  • Docker, to run signal-cli-rest-api
  • A Signal account to link, or a phone number to register

Quick start

  1. Start the container. MODE must match Signal:Mode:

    SIGNAL_MODE=json-rpc docker compose up -d
    
  2. Link the container to your Signal account. Open http://localhost:8080/v1/qrcodelink?device_name=signal-net and scan the QR code in the Signal app (Settings → Linked devices). You can also register a dedicated number for the bot with IRegistrationService (RegisterAsync, then VerifyAsync with the code you receive).

  3. Configure your number with user secrets, so it never ends up in the repository. The placeholder values in appsettings.json are overridden.

    dotnet user-secrets --project samples/Signal.Sample.Bot set "Signal:Accounts:0" "+4915112345678"
    dotnet user-secrets --project samples/Signal.Sample.Bot set "Signal:Commands:Admins:0" "+4915112345678"
    

    Run the bot:

    dotnet run --project samples/Signal.Sample.Bot
    
  4. Send /help to the account from another device.

MODE (container) Signal:Mode Receiving
normal Normal HTTP polling of GET /v1/receive/{number}
native Native HTTP polling
json-rpc JsonRpc WebSocket ws://…/v1/receive/{number} with auto-reconnect
json-rpc-native JsonRpcNative WebSocket

With VerifyModeOnStartup enabled, the host reads /v1/about on startup and warns about a mode mismatch. With FailOnModeMismatch it stops instead.

Usage

var builder = Host.CreateApplicationBuilder(args);

builder.AddSignal()                                  // binds the "Signal" section
    .AddCommands(typeof(Program).Assembly)           // ICommand classes + CommandModules
    .AddEventHandlers(typeof(Program).Assembly)      // IEventHandler<TEvent>
    .AddMiddleware<MyMiddleware>()
    .AddArgumentConverter<MyTypeConverter>()
    .MapCommand("about", ctx => ctx.ReplyAsync("Signal.NET bot"));

builder.Services.AddHealthChecks().AddSignalApi();
await builder.Build().RunAsync();

Commands

Attribute-based modules support typed parameters, flags, remainder text, constructor injection and preconditions:

[RequireGroup]
public sealed class GroupModule(IGroupService groups) : CommandModule
{
    [Command("kick", Description = "Removes a member")]
    [RequireAdmin, RequireGroupAdmin]
    public async Task KickAsync(PhoneNumber member, CancellationToken ct)
    {
        await groups.RemoveMembersAsync(Context.Account, Context.Group!.Value, [member.Value], ct);
        await ReplyAsync($"Removed {member}.");
    }

    [Command("echo"), Cooldown(5)]
    public Task EchoAsync([Remainder] string text, [Flag] bool upper) =>
        ReplyAsync(upper ? text.ToUpperInvariant() : text);   // /echo --upper hello world
}

Class-based commands:

[Command("ping", Aliases = ["p"], Description = "Checks that the bot is alive.")]
public sealed class PingCommand : CommandBase
{
    public override Task ExecuteAsync(CommandContext context, CancellationToken ct) =>
        context.ReplyAsync("pong", cancellationToken: ct);
}
  • Parsing: you can configure several prefixes. Quoted arguments work with "…", '…' and the typographic quotes that mobile keyboards insert. Flags take the form --name value, --name=value or --switch, and -- ends flag parsing.
  • Binding: string, bool (yes/no/on/off), enums, Recipient, and anything that implements IParsable<T> (numbers, Guid, TimeSpan, PhoneNumber, GroupId, ...) bind automatically. Nullable and optional parameters are supported. If binding fails, the bot replies with the reason and the usage line.
  • Preconditions: the built-ins are RequireAdmin, RequireGroup, RequireDirectMessage, RequireGroupAdmin and Cooldown (scoped per sender, per conversation or globally). For your own, derive from PreconditionAttribute.
  • Results: replace ICommandResultHandler to change how unknown commands and errors are reported.

Events

public sealed class Welcome(IMessageSender sender) : IEventHandler<GroupUpdated>
{
    public Task HandleAsync(GroupUpdated e, CancellationToken ct) =>
        sender.SendAsync(e.Envelope.Account, OutgoingMessage.To(e.Group).WithText("👋").Build(), ct);
}

The available events are MessageReceived, MessageEdited, MessageDeleted, MessageSent, StoryReceived, CallReceived, ReactionReceived, ReceiptReceived, TypingIndicatorChanged and GroupUpdated.

Using the API directly

Inject ISignalClient (a facade) or a single port:

await signal.Messages.SendAsync(account, OutgoingMessage.To(recipient)
    .WithStyledText("**bold** and *italic*")
    .WithAttachment(bytes, "image/png", "chart.png")
    .Build());
await signal.Groups.CreateAsync(account, "Team", ["+4915112345678"]);

Configuration reference (Signal section)

Key Default Notes
BaseUrl http://localhost:8080/
Mode Normal Normal, Native, JsonRpc, JsonRpcNative
Accounts – Required. E.164 numbers to receive for.
MaxConcurrency 4 Parallel conversations.
VerifyModeOnStartup / FailOnModeMismatch true / false
Receive:* 1 s interval, 1 s timeout IgnoreStories (all modes). Polling modes only: PollingInterval, TimeoutSeconds, MaxMessages, IgnoreAttachments, SendReadReceipts, MaxErrorBackoff.
WebSocket:* 1 s–30 s backoff, 20 s keep-alive WebSocket modes only.
Http:Timeout / Http:RetryCount 30 s / 3 Only GET/PUT/DELETE requests are retried. Sends are never retried, so a message is not duplicated.
Commands:* prefix / Prefixes, CaseSensitive, RespondToUnknown, UnknownCommandMessage, DisabledCommandMessage, SuggestSimilarCommands, ErrorMessage, QuoteReplies, EnableHelp, HelpPageSize, Admins, Roles.
AccessControl:* AllowedSenders, BlockedSenders, IgnoreOwnMessages.
RateLimit:* disabled PermitsPerWindow per sender per Window.
Localization:* English DefaultCulture, Texts (culture → TextKey → text) for the framework's replies.
Scheduler:* 1 s checks, 1 min retry PollInterval, RetryDelay for scheduled messages.
Background:* 4 workers, 100 queued, 2 min prompts MaxConcurrency, Capacity for work queued with RunInBackgroundAsync; PromptTimeout for PromptAsync.

The options are validated on startup (SignalOptionsValidator). An invalid configuration stops the host with a list of all problems.

Extending

Want to… Do
Add behaviour to every message AddMiddleware<T>() (IMessageMiddleware)
React to events IEventHandler<TEvent>
Bind a custom argument type Implement IParsable<T>, or AddArgumentConverter<T>()
Swap the transport or add a custom mode receiver UseReceiver<T>(modes) or register a keyed IMessageReceiver
Customize WebSocket connections (proxy, TLS, auth) Replace IWebSocketConnector
Replace any port (e.g. for tests) Register your implementation before or after AddSignal()

Tests

dotnet test

The tests cover the domain invariants, the parser, binding and preconditions, and the pipeline. On the infrastructure side they cover REST request bodies, the retry policy, envelope mapping, polling, and a real WebSocket over loopback, including reconnects.

Contributing

Planned features are listed in the ROADMAP. Contributions are welcome. See CONTRIBUTING.md for the build setup and conventions, and SECURITY.md for how to report vulnerabilities and run a bot safely. Changes are tracked in CHANGELOG.md.

License

MIT © 2026 Nacorpio

Signal.NET is an independent project. It is not affiliated with Signal Messenger LLC or signal-cli.

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net11.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Nacorpio.Signal.Domain:

Package Downloads
Nacorpio.Signal.Application

Application layer for Signal.NET: ports, message pipeline, domain event dispatching and the text command system.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.5.0-preview.1 136 9/30/2026
0.4.0-preview.1 182 9/30/2026
0.3.0-preview.1 124 9/29/2026
0.2.0-preview.2 158 9/29/2026