Configuration Options

This document outlines the configuration options available for initializing the application. The application supports two configuration methods:

• Configuration File: /app/config/config.json
• Environment Variables: (used as fallback)

---

Configuration Loading Priority

The application loads configuration using the following order of precedence:

1. Configuration File: Attempts to load /app/config/config.json if it exists.
2. Environment Variables: If the config file is missing or incomplete, environment variables are used as a fallback.

---

Case Insensitivity

All configuration keys are case-insensitive.

The following examples are equivalent and valid:

{
  "SLOTID": "slot1",
  "slotid": "slot1",
  "SlotId": "slot1"
}

Or as environment variables:

export SLOTID=slot1
export slotid=slot1
export SlotId=slot1

Required Configuration Variables

Variable	Description	Example	Validation
slotid	Unique identifier for the WhatsApp instance	slotid=slot1	Must not be empty
nrurl	URL endpoint where to post incoming WA messages	nrurl=https://api.host.com	Must not be empty
portin	Port number for the application to listen on	portin=8080	Must be a valid port (1024–65535); can be string or number in config.json

Note on portin: The port 8888 commonly used in examples is just a suggestion. You can use any non-reserved port (1024-65535) that is accessible on your server. Higher ports (e.g., 8000-9000 range) are generally recommended to avoid conflicts with other services. Make sure your firewall allows traffic on whatever port you choose.

Optional Configuration Variables

Variable	Description	Example	Type	Default
devicename	Name of the device	devicename=WhatsApp Bot	String	-
debuglevel	Debug logging level	debuglevel=0	Integer	0
logstdout	Enable logging to stdout	logstdout=true	Boolean	false
logsse	Enable Server-Sent Events logging	logsse=true	Boolean	false
qrurl	URL for QR code generation	qrurl=https://qr.example.com	String	-
qrterm	Enable terminal QR code display	qrterm=false	Boolean	false

Complete Configuration Example

Below is a comprehensive example showcasing all available configuration options with explanations of what each setting achieves:

{
  "slotid": "production-whatsapp",
  "nrurl": "https://your-api.example.com/webhook",
  "portin": 9001,
  "devicename": "Company WhatsApp Server",
  "debuglevel": 3,
  "logstdout": true,
  "logsse": true,
  "qrurl": "https://your-api.example.com/qrcode-handler",
  "qrterm": false
}

What This Configuration Achieves

• slotid: "production-whatsapp" - Identifies this instance as the production WhatsApp service. This helps distinguish between multiple instances if you run more than one (e.g., testing, development, production).

• nrurl: "https://your-api.example.com/webhook" - All incoming WhatsApp messages will be forwarded to this webhook URL. Your backend application should be configured to receive and process these messages.

• portin: 9001 - The Whinself service will listen on port 9001. You'll access the web interface via this port (e.g., http://your-server:9001).

• devicename: "Company WhatsApp Server" - This name will appear in the WhatsApp "Linked Devices" section on your phone. A descriptive name helps identify the purpose of this linked device.

• debuglevel: 3 - Sets verbose debugging information (levels available: 0-4):

  • 0: Error messages only
  • 1: Warnings and errors
  • 2: Normal operational information
  • 3: Detailed debug information (useful for troubleshooting)
  • 4: Very verbose tracing (high volume of logs)

• logstdout: true - Outputs logs to standard output, which is useful for:

  • Viewing logs directly in the terminal
  • Docker container logs (docker logs whatsapp-bot)
  • Integration with logging systems that capture stdout

• logsse: true - Enables Server-Sent Events for real-time log streaming, allowing:

  • Live log viewing in the web dashboard
  • Real-time monitoring of message activity
  • Immediate visibility of connection issues

• qrurl: "https://your-api.example.com/qrcode-handler" - When a new QR code for WhatsApp connection is generated, it will be sent to this URL. This allows:

  • Custom handling of QR codes
  • Integration with notification systems
  • Automation of QR code distribution

• qrterm: false - Disables displaying the QR code in the terminal. In a server environment, terminal QR codes are typically not useful, so setting this to false makes sense for a production deployment.

Starting Whinself with Environment Variables

If you prefer to use environment variables instead of a config.json file, you can start Whinself directly with environment variables like this:

# Setting environment variables directly in the docker run command
docker run -d \
  --name whatsapp-bot \
  --restart unless-stopped \
  -p 9001:9001 \
  -e SLOTID=production-whatsapp \
  -e NRURL=https://your-api.example.com/webhook \
  -e PORTIN=9001 \
  -e DEVICENAME="Company WhatsApp Server" \
  -e DEBUGLEVEL=2 \
  -e LOGSTDOUT=true \
  -e LOGSSE=true \
  inutil/whingo:latest

This approach eliminates the need for creating and mounting a config.json file, which can be useful in containerized environments or when using orchestration tools like Kubernetes or Docker Compose.

Using Environment Variables

export NRURL=https://host.TLD/api/newrelic
export SLOTID=slot1
export DEVICENAME=WhatsApp Bot
export DEBUGLEVEL=0
export LOGSTDOUT=true
export LOGSSE=true
export QRURL=https://host.TLD/api/qr
export QRTERM=false
export PORTIN=9001

Notes

• Boolean values such as logstdout, logsse, and qrterm should be expressed as "true" or "false" strings when using environment variables.
• Configuration files should be in valid JSON format.
• All configuration keys are case-insensitive
• Configuration from config.json takes precedence over environment variables
• Required variables must be set either in config.json or as environment variables
• Boolean values can be set as "true", "false", "1", or "0"
• Port numbers must be valid (1024-65535)
• The application will stop with a clear error message if required variables are missing
• Configuration is loaded once at startup and remains constant throughout the application's lifetime
• Web interface allows changing NRURL at runtime.

Note: Whinself is an unofficial third-party tool that connects to the WhatsApp network using your personal WhatsApp account. It is not affiliated with or endorsed by WhatsApp or Meta Platforms, Inc. Users should ensure their usage complies with WhatsApp's Terms of Service.