A .NET Signal Messenger Bot Client - because sometimes Telegram isn't enough
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
CancellationTokenhandling
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-apiOption 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"# Package Manager
Install-Package Signal.Bot
# .NET CLI
dotnet add package Signal.Bot<!-- PackageReference -->
<PackageReferenceInclude="Signal.Bot"Version="1.0.0"/>usingSignal.Bot;usingSignal.Bot.Types;varclient=newSignalBotClient(builder =>builder.WithBaseUrl("http://localhost:8080").WithNumber("+1234567890"));usingvarcts=newCancellationTokenSource();client.StartReceiving(async(botClient,message,ct)=>{vartext=message.Envelope?.DataMessage?.Message;Console.WriteLine($"Received from {message.Account}: {text}");if(!string.IsNullOrEmpty(text)){awaitbotClient.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}");awaitTask.CompletedTask;},
builder =>builder.WithMaxMessages(1),cts.Token);Console.WriteLine("Bot is running. Press any key to stop...");Console.ReadKey();cts.Cancel();| Category | Details |
|---|---|
| Messages | Send & receive text, mentions, reactions |
| Attachments | Images, videos, documents, voice messages |
| Groups | Create, list, update, delete |
| Profiles | Name, about, avatar |
| Polling | Built-in StartReceiving mechanism |
| Type Safety | Strongly-typed models throughout |
| Async | Full async/await & CancellationToken support |
Your Application
│
▼
Signal.Bot ← This library
(SignalBotClient)
│
▼
signal-cli-rest-api ← Docker container
(HTTP REST API)
│
▼
Signal Servers
Set via the MODE environment variable:
| Mode | Speed | Memory | Recommended |
|---|---|---|---|
native | Fast | Low | ✅ Yes |
json-rpc | Fastest | High | Only if needed |
normal | Slow | Low | Fallback |
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.
- Fork the repo and create a feature branch:
git checkout -b feature/my-feature - Write tests and make sure they pass:
dotnet test - Open a Pull Request
Please keep changes focused, follow the existing code style, and update docs for any API changes.
MIT — see LICENSE for details.
Built with ❤️ for the .NET and Signal communities · Open an issue
- signal-cli-rest-api — Required backend
- signal-cli — Underlying CLI tool
- Telegram.Bot — Design inspiration