whatsapp

WhatsApp connector

Drive the user's WhatsApp via the wa CLI, which talks to an always-on local daemon.

Always call it by absolute path: {{WA_DIR}}/bin/wa

Reading (allowed freely)

• wa chats — list chats/groups
• wa read "<chat>" [--limit 30 | --all] — recent messages (each has an id for reactions). --all reads the WHOLE chat (every synced message), bypassing the 200 cap — use sparingly: a busy chat can be thousands of messages (large payload + heavy on your context)
• wa search "<query>" [--chat "<chat>"] — find messages
• wa members "<group>" — who is in a group
• wa contacts "<query>" — resolve a name/number
• wa media "<chat>" "<message-id>" — download an image/file; prints a path you can then open

Chats are addressed by name (fuzzy) or exact id. If wa reports the name is ambiguous, show the candidates and ask which one.

Response shapes (verified against a live account)

Everything prints as JSON (or a plain string). Shapes you can rely on:

• wa chats → array of { id, name, unread }, ordered most-recently-active first. The id suffix is the chat type:
  • …@g.us — a group
  • …@lid — an individual person (WhatsApp's current per-contact id). The older …@c.us form can also appear; treat BOTH as 1:1 people. To filter to real people, exclude @g.us — do NOT match on @c.us alone (modern accounts return @lid and you'll get zero results).
• wa read → { chat, id, messages: [ … ] }, oldest→newest. Each message is { id, sender, ts, text, hasMedia }:
  • sender is the literal string "me" for the user's own messages, otherwise the counterparty's chat id — so message direction is just sender === "me".
  • ts is a UNIX timestamp in seconds (multiply by 1000 for a JS Date).
  • --limit is capped at 200 (MAX_LIMIT); a busier chat returns only its most recent 200, so a chat sitting at exactly 200 means "≥200", not exactly 200. Pass --all to bypass the cap and fetch every message — but "every" means every message currently synced into the Web session, NOT the full lifetime history. Depth is volatile: a freshly linked device backfills older messages over time, and a daemon restart flushes the loaded depth — right after a (re)start most chats read only their newest message or two and re-deepen as the session re-syncs. So a low --all count can mean "not synced yet," not "that's the whole chat." A big, warmed chat can return thousands of messages at once.
• wa status → { state, ready, syncPercent } (plus recovery: {attempt, max} while self-recovering); state ∈ starting | needs-login | syncing | ready | recovering | relinking | auth-failure | disconnected.
• Errors come back as { ok:false, error, code } with codes like NOT_ALLOWED (chat not on the allow-list), NOT_APPROVED (human denied or the dialog timed out), AMBIGUOUS (name matched >1 chat), NOT_FOUND.