Skip to main content

​
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

FieldValue
Catalog idwhatsapp-personal
Config keywhatsapp_personal
Implementation statusplugin_backed
Transportwhatsapp_web_baileys_bridge
Aliaseswhatsapp-web, wa-personal, whatsapp-personal-bridge
Default send target kindconversation

​
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 idMeaning
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

OperationCommandUsage or status
bridge-backed sendchannels send whatsapp-personalrequires the bundled bridge to be running
bridge-backed servechannels serve whatsapp-personalstarts the Loong reply loop against the running bundled bridge
bridge helperloong whatsapp-personal bridge runstarts the bundled QR bridge and prints the pairing QR when needed
pairing-code fallbackloong 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

RequirementConfig pathsEnv pointer pathsDefault env
channel enabledwhatsapp_personal.enabled
whatsapp_personal.accounts.<account>.enabled		nonenone
local bridge urlwhatsapp_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

RequirementConfig pathsEnv pointer pathsDefault env
channel enabledwhatsapp_personal.enabled
whatsapp_personal.accounts.<account>.enabled		nonenone
local bridge urlwhatsapp_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 dirwhatsapp_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 idswhatsapp_personal.allowed_chat_ids
whatsapp_personal.accounts.<account>.allowed_chat_ids		nonenone

​
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.