WhatsApp

KhunQuant connects to WhatsApp in two modes: a native client that speaks the WhatsApp Web protocol directly, or a bridge mode that delegates protocol handling to an external process over a WebSocket. The native mode is recommended for most users.

Capabilities

• Text message send/receive
• Incoming media download and context integration
• Voice message transcription (when an ASR model is configured)
• Allow-listing by phone number

Configuration

Native mode (recommended)

Add to ~/.khunquant/config.json:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "~/.khunquant/workspace/whatsapp",
      "allow_from": [],
      "reasoning_channel_id": ""
    }
  }
}

On first launch a QR code is printed to the terminal. Open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device, and scan the code. The session is then persisted to session_store_path and reused automatically on subsequent starts.

Bridge mode

If you already run a separate WhatsApp bridge process (e.g. mautrix-whatsapp), point KhunQuant at its WebSocket endpoint:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": false,
      "bridge_url": "ws://localhost:3001"
    }
  }
}

KhunQuant treats the bridge as a transparent transport layer and does not manage the bridge process itself.

Configuration reference

Field	Type	Default	Description
enabled	bool	false	Enable the WhatsApp channel
use_native	bool	false	Use the built-in client instead of an external bridge
bridge_url	string	""	WebSocket endpoint for bridge mode
session_store_path	string	""	Directory where the native session is persisted
allow_from	[]string	[]	Allowlist of phone numbers (empty allows all)
reasoning_channel_id	string	""	Contact/group ID for separate reasoning output

Access control

Restrict access to specific contacts by listing their phone numbers in international format, without the leading +:

{
  "allow_from": ["6612345678901", "6623456789012"]
}

An empty allow_from array permits messages from any contact.

Setup steps

1. Add the native mode configuration block to config.json.
2. Start KhunQuant — a QR code will appear in the terminal.
3. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device and scan the QR code.
4. The session is saved automatically. Future starts will reconnect without re-scanning.

Re-pairing the device

To reset and pair a new device, delete the session_store_path directory and restart KhunQuant. A new QR code will be generated.

Voice transcription

Audio messages are automatically transcribed before being passed to the agent if an ASR model is configured. See the model configuration guide for details.