WhatsApp Personal

This is a shipped plugin-backed bridge surface. Loong owns the stable send and reply-loop contract, while a bundled local bridge owns WhatsApp Web QR login, reconnects, and session persistence.

At A Glance

Field	Value
Catalog id	`whatsapp-personal`
Config key	`whatsapp_personal`
Implementation status	`plugin_backed`
Transport	`whatsapp_web_baileys_bridge`
Aliases	`whatsapp-web`, `wa-personal`, `whatsapp-personal-bridge`
Default send target kind	`conversation`

Minimal Config

[runtime_plugins]
enabled = true
roots = ["./runtime-plugins"]

[whatsapp_personal]
enabled = true
managed_bridge_plugin_id = "whatsapp-personal-baileys-bridge"
bridge_url = "http://127.0.0.1:39731/bridge"
auth_dir = "~/.loong/whatsapp-personal/default"
allowed_chat_ids = ["*"]

First-Time Pairing

Start the bundled bridge in one terminal. On the first run it will install its Node dependencies if needed, print a QR code by default, and keep the personal account session alive. If you cannot scan, the same helper can also request a pairing code fallback for your phone number.

loong whatsapp-personal bridge run --config ./loong.toml

After the QR-linked bridge is live, run the normal Loong reply loop in another terminal:

loong channels serve whatsapp-personal --config ./loong.toml

Smoke Test

# Terminal 1: keep the bridge running so the QR-linked session stays online
loong whatsapp-personal bridge run --config ./loong.toml

# Terminal 2: start the Loong reply loop
loong channels serve whatsapp-personal --config ./loong.toml

# Terminal 3: proactive send through the same personal account bridge
loong channels send whatsapp-personal \
  --config ./loong.toml \
  --target contact:+15551234567 \
  --text "hello from loong"

Stable Target Contract

Target id	Meaning
`whatsapp-personal:<account>:contact:<e164-or-jid>`	direct chat route via an E.164 number or a full WhatsApp contact JID
`whatsapp-personal:<account>:group:<jid>`	group chat route via a WhatsApp group JID

Grouped commands also accept the short form <kind>:<id> when one configured account is already selected.

Pairing-Code Fallback

QR remains the primary pairing path. If scanning is not possible, request a pairing code for the phone number that should own the linked personal session:

loong whatsapp-personal bridge run \
  --config ./loong.toml \
  --pairing-code 15551234567

Notes:

The number can be entered in E.164 form or digits only; the helper normalizes it before calling Baileys.
Baileys expects the country code to be included.
The bridge still prints the QR first, then requests the pairing code fallback a few seconds later.
--custom-pairing-code ABCD1234 is available when you need to request one exact 8-character code.

Command Surface

Operation	Command	Usage or status
bridge-backed send	`channels send whatsapp-personal`	requires the bundled bridge to be running
bridge-backed serve	`channels serve whatsapp-personal`	starts the Loong reply loop against the running bundled bridge
bridge helper	`loong whatsapp-personal bridge run`	starts the bundled QR bridge and prints the pairing QR when needed
pairing-code fallback	`loong whatsapp-personal bridge run --pairing-code <phone>`	still shows QR first, then requests a linking code for the given phone number if scanning is not possible

Required Fields For Send

Requirement	Config paths	Env pointer paths	Default env
channel enabled	`whatsapp_personal.enabled` `whatsapp_personal.accounts.<account>.enabled`	none	none
local bridge url	`whatsapp_personal.bridge_url` `whatsapp_personal.accounts.<account>.bridge_url`	`whatsapp_personal.bridge_url_env` `whatsapp_personal.accounts.<account>.bridge_url_env`	`WHATSAPP_PERSONAL_BRIDGE_URL`

Required Fields For Serve

Requirement	Config paths	Env pointer paths	Default env
channel enabled	`whatsapp_personal.enabled` `whatsapp_personal.accounts.<account>.enabled`	none	none
local bridge url	`whatsapp_personal.bridge_url` `whatsapp_personal.accounts.<account>.bridge_url`	`whatsapp_personal.bridge_url_env` `whatsapp_personal.accounts.<account>.bridge_url_env`	`WHATSAPP_PERSONAL_BRIDGE_URL`
bridge auth dir	`whatsapp_personal.auth_dir` `whatsapp_personal.accounts.<account>.auth_dir`	`whatsapp_personal.auth_dir_env` `whatsapp_personal.accounts.<account>.auth_dir_env`	`WHATSAPP_PERSONAL_AUTH_DIR`
allowed chat ids	`whatsapp_personal.allowed_chat_ids` `whatsapp_personal.accounts.<account>.allowed_chat_ids`	none	none

Operator Notes

This surface is for QR-linked personal WhatsApp Web access. Keep it separate from the shipped WhatsApp Cloud API business-account lane.
runtime_plugins.roots must include ./runtime-plugins (or another root that contains the whatsapp-personal-baileys-bridge manifest) so loong doctor, loong channels, and grouped send/serve can discover the bundled bridge contract.
The bridge binds to 127.0.0.1 only. If you change bridge_url, keep it on a local-only interface.
allowed_chat_ids = ["*"] keeps the bridge open to every chat the linked personal account can see. Replace that wildcard with a narrow allowlist once the route ids you care about are stable.
The bridge helper owns QR login and session persistence. The grouped channels serve whatsapp-personal loop owns only Loong’s reply-loop runtime.
The bundled bridge currently supports text sends and text-first inbound relaying. If you need richer media semantics, add them in the bridge package instead of overloading the existing Cloud API lane.

Continue to WhatsApp Cloud API for the existing Meta business-account lane.
Continue to Channel Setup for the shared public setup contract.
Continue to Channels for the surface taxonomy and ownership model.
Continue to Channel Guides for the full matrix.

Overview

Get Started

Use Loong

Build On Loong

Reference

WhatsApp Personal

WhatsApp Personal

At A Glance

Minimal Config

First-Time Pairing

Smoke Test

Stable Target Contract

Pairing-Code Fallback

Command Surface

Required Fields For Send

Required Fields For Serve

Operator Notes

​WhatsApp Personal

​At A Glance

​Minimal Config

​First-Time Pairing

​Smoke Test

​Stable Target Contract

​Pairing-Code Fallback

​Command Surface

​Required Fields For Send

​Required Fields For Serve

​Operator Notes

​Related Docs

WhatsApp Personal

At A Glance

Minimal Config

First-Time Pairing

Smoke Test

Stable Target Contract

Pairing-Code Fallback

Command Surface

Required Fields For Send

Required Fields For Serve

Operator Notes

Related Docs