Configuration reference
All settings live in the Signal section, which is bound to SignalOptions. Any .NET configuration
source works: appsettings.json, environment variables (Signal__Mode=JsonRpc,
Signal__Accounts__0=+49…), user secrets, command-line arguments, and so on.
Durations use the TimeSpan format hh:mm:ss. Enum values are case-insensitive names
(JsonRpc, not json-rpc).
{
"Signal": {
"BaseUrl": "http://localhost:8080",
"Mode": "JsonRpc",
"Accounts": [ "+4915112345678" ],
"MaxConcurrency": 4,
"VerifyModeOnStartup": true,
"FailOnModeMismatch": false,
"Receive": { "PollingInterval": "00:00:01", "TimeoutSeconds": 1, "MaxMessages": null,
"IgnoreAttachments": false, "IgnoreStories": true, "SendReadReceipts": false,
"MaxErrorBackoff": "00:00:30" },
"WebSocket": { "ReconnectMinDelay": "00:00:01", "ReconnectMaxDelay": "00:00:30",
"KeepAlive": "00:00:20", "ReceiveBufferSize": 16384 },
"Http": { "Timeout": "00:00:30", "RetryCount": 3 },
"Commands": { "Prefixes": [ "/", "!" ], "CaseSensitive": false, "RespondToUnknown": true,
"UnknownCommandMessage": "Unknown command '{0}'. Send {1}help for a list of commands.",
"SuggestSimilarCommands": true,
"ErrorMessage": "Sorry, something went wrong while executing this command.",
"QuoteReplies": false, "EnableHelp": true, "HelpPageSize": 20, "Admins": [ "+4915112345678" ] },
"AccessControl": { "AllowedSenders": [], "BlockedSenders": [], "IgnoreOwnMessages": true },
"RateLimit": { "PermitsPerWindow": 0, "Window": "00:01:00" },
"Background": { "MaxConcurrency": 4, "Capacity": 100, "PromptTimeout": "00:02:00" },
"Scheduler": { "PollInterval": "00:00:01", "RetryDelay": "00:01:00" }
}
}
Root
| Key |
Type |
Default |
Validation / notes |
BaseUrl |
URL |
http://localhost:8080/ |
Absolute http/https URL. A base path (reverse proxy) is supported. |
Mode |
Normal | Native | JsonRpc | JsonRpcNative |
Normal |
Must match the container's MODE. See Execution modes. |
Accounts |
string[] |
– |
Required, and each entry must be a valid E.164 number. One receive loop runs per account. |
MaxConcurrency |
int |
4 |
≥ 1. The number of conversations processed in parallel. |
VerifyModeOnStartup |
bool |
true |
Checks /v1/about on startup |
FailOnModeMismatch |
bool |
false |
Stop instead of warning on a mode mismatch |
Receive (polling modes only)
| Key |
Default |
Validation / notes |
PollingInterval |
1 s |
> 0. The pause after an empty poll. |
TimeoutSeconds |
1 |
≥ 0. Server-side long-poll duration. |
MaxMessages |
null |
> 0 when set |
IgnoreAttachments |
false |
Don't store attachments in the container |
IgnoreStories |
true |
Skip stories. Set it to false to receive StoryReceived events. Applies in every mode: the polling modes pass it to the API, and the mapper also drops stories when it's true. |
SendReadReceipts |
false |
The container sends read receipts automatically |
MaxErrorBackoff |
30 s |
Cap of the retry delay after failed polls |
WebSocket (json-rpc modes only)
| Key |
Default |
Validation / notes |
ReconnectMinDelay |
1 s |
> 0 and ≤ ReconnectMaxDelay |
ReconnectMaxDelay |
30 s |
|
KeepAlive |
20 s |
Ping interval. Keeps idle connections open through proxies. |
ReceiveBufferSize |
16384 |
≥ 1024 bytes. Larger messages are reassembled. |
Http
| Key |
Default |
Validation / notes |
Timeout |
30 s |
> 0. Polling modes: it must exceed Receive:TimeoutSeconds by at least 5 s. |
RetryCount |
3 |
≥ 0. Applies only to GET/PUT/DELETE. Sends are never retried. |
Commands
| Key |
Default |
Notes |
Prefixes |
["/"] when empty |
Non-empty strings. The longest match wins. |
CaseSensitive |
false |
Applies to command names and aliases |
RespondToUnknown |
true |
Reply to prefixed messages that don't match a command |
UnknownCommandMessage |
see above |
{0} = the typed name, {1} = the prefix |
DisabledCommandMessage |
"This command is disabled in this conversation." |
Reply when a command is disabled in the conversation's settings; empty for no reply |
SuggestSimilarCommands |
true |
Append "Did you mean /help?" when a visible command, alias or group name (or, for /group typo, a subcommand) is one typo away, or two for names of 6+ characters. Swapped letters count as one typo. |
ErrorMessage |
see above |
Sent when a command throws |
QuoteReplies |
false |
Replies quote the triggering message |
EnableHelp |
true |
Enables the built-in help command |
HelpPageSize |
20 |
Commands per /help page (/help 2 for the next). 0 disables paging. |
Admins |
[] |
Phone numbers or UUIDs allowed to use [RequireAdmin] commands. They also have the admin role. |
Roles |
{} |
Role name → phone numbers or UUIDs for [RequireRole], e.g. { "moderator": ["+4915112345678"] }. Role names are case-insensitive; changes apply without restart. |
AccessControl
| Key |
Default |
Notes |
AllowedSenders |
[] |
If not empty, only these senders are processed |
BlockedSenders |
[] |
Always ignored |
IgnoreOwnMessages |
true |
Ignore messages from the receiving account itself, including transcripts of messages sent from its other devices. Set it to false to receive MessageSent events; transcripts never run commands. |
RateLimit
| Key |
Default |
Notes |
PermitsPerWindow |
0 (off) |
Data messages per sender per window |
Window |
1 min |
> 0 |
Background
Work queued with RunInBackgroundAsync / IBackgroundWorkQueue.
| Key |
Default |
Notes |
MaxConcurrency |
4 |
Work items running at the same time; at least 1 |
Capacity |
100 |
Items that may wait; queuing waits while the queue is full. At least 1. |
PromptTimeout |
2 min |
Default wait of BackgroundWork.PromptAsync; must be positive |
Items still queued at shutdown are dropped (logged as a warning), so don't use the queue for work that must survive restarts.
Scheduler
Scheduled messages (IMessageScheduler, ScheduleReplyAsync).
| Key |
Default |
Notes |
PollInterval |
1 s |
How often due messages are checked for, which is the send-time precision. With a database store, a longer interval means fewer queries. |
RetryDelay |
1 min |
Wait before retrying a message whose send failed |
After downtime, overdue one-off messages are sent on the first check. A recurring message sends one catch-up and then continues at its next future time; it doesn't replay every missed occurrence.
Localization
Languages of the texts the framework sends: errors, usage lines, help, precondition failures and prompt re-asks.
| Key |
Default |
Notes |
DefaultCulture |
en |
Culture of conversations without their own ConversationSettings.Culture; must be a well-formed culture name (en, de-AT) |
Texts |
{} |
Culture → text key → text. The keys are the constants of TextKey; {0}, {1} … are their documented arguments. |
"Localization": {
"DefaultCulture": "en",
"Texts": {
"de": {
"UnknownCommand": "Unbekannter Befehl '{0}'. Sende {1}help für eine Liste.",
"InvalidArgument": "'{0}' ist keine gültige {1} für <{2}>.",
"Type.whole number": "Ganzzahl"
}
}
}
- Culture: a conversation's culture comes from its settings (
ConversationSettings.Culture), otherwise from
DefaultCulture. Cultures are plain names, so lookup falls back by name (zh-Hant-TW → zh-Hant → zh → English).
This also works in invariant-globalization mode (common in small container images), and CI tests that mode.
- Type names in errors ("whole number", "yes/no", …) are translated with the key
Type.{English name}. That
also works for custom converters' DisplayName.
- Existing message options stay the defaults:
Commands:UnknownCommandMessage, DisabledCommandMessage and
ErrorMessage remain the English texts for UnknownCommand, DisabledCommand and CommandError.
- Broken translations don't break replies: a translation with invalid placeholders is logged and replaced by
the English text.
- In your own code,
await context.GetCultureAsync() and ISignalTexts give you the same lookup, and custom
preconditions can call Fail(context, key, args).
Hot reload
Options read through IOptionsMonitor take effect without a restart when the configuration file changes:
Commands:* (the CaseSensitive flag and the command table are fixed once built);
AccessControl:*;
RateLimit:*;
Receive:*;
- the
WebSocket reconnect settings.
BaseUrl, Mode, Accounts, MaxConcurrency and Http:* are read once at startup.