Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
whatsapp-linked
What it is
Personal WhatsApp accounts linked as devices (External tab → WhatsApp): link an
account by QR, list its WhatsApp chats, and add a group or direct chat as its
own shareable external chat (POST /external-chats with provider: 'whatsapp'). Each person sends from their own account. Behind the enable-whatsapp-linked flag.
Start here
whatsapp-linked.tsx: production wiring (shared queries + split navigation).context/whatsapp-linked-context.tsx: the capability contract tests fake.views/whatsapp-page.tsx: account states, the header (search + account strip), the chat sections and Can't be added, and the pairing/confirm dialogs.components/conversation-sections.tsx+core/chat.tsconversationSections: Direct messages / Groups / one section per community, on view-shell'sCollapsibleSection(what Chat's rail uses); External's sidebar renders the same sections. Open state isprimitives/open-sections.ts, per user.components/chat-list.tsx: one-line chat rows styled like Macro's list rows (bg-list-hover, actions on hover/focus, always on touch).- Starting chats:
core/chat.tschatSectionsputs saved contacts nobody wrote to (direct, nolastActivityAt) incontacts, shown as the page's Contacts section.components/new-chat-dialog.tsxtakes a number (core/new-chat.tsnormalises it to E.164 and words eachNewChatFailure); thestartChatcapability looks it up (useLookUpWhatsappNumberMutationpollsGET /whatsapp/lookups/{id}), then adds and opens the chat. components/history-import-prompt.tsx: the bottom-right prompt (mounted lazily inLayout.tsx; not on phones, where it covers the composer) to import earlier messages of the owner's chats waiting for their phone (core/history-import.ts). It and the chat view's import bar (features/external-chat) are the only things that ask the phone (POST /whatsapp/history-import).core/chat.ts: chat sections, search matching and row wording.
Scope
- Owns: the WhatsApp account page, pairing dialog, one-click add (no dialog; DSS names the chat after WhatsApp) and the New chat dialog.
- Chat timeline and sending:
features/external-chat; channels only reach a chat through a mention, which shares it (MentionsMenu). - One account at a time: there is no replace flow; switching means Disconnect, then Connect.
- Not here: the External tab shell, the chats nested under each provider in
its sidebar and the
/external/chat/:chatIdroute →features/external-view; HTTP →lib/service-clients/service-storage/whatsapp-linked.ts(DSS/whatsapp/*) andexternal-chats.ts(adding); shared queries →lib/queries/whatsapp-linked; DSS routes →crates/whatsapp_linked.
Gotchas
- Mutations open
whatsapp.*operation spans in the shared queries; HTTP trace propagation usessafeFetch. Record outcomes without server error bodies or pairing material. - Pairing material (QR, codes) stays in the
ph-no-capturedialog and the never-persisted,gcTime: 0pairing query. Never put it in a URL or log. - The QR is encoded locally with
uqr; never send the value to an image service. core/pairing.tsmatches DSS's pairing states exhaustively; a new state must be handled there, not fall through to "preparing".primitives/pairing-flow.tsreplaces an expired pairing on its own (like WhatsApp Web) only when the server saysexpired, the tab stayed visible, and fewer thanAUTO_ROLLScodes rolled since the last click; otherwise the QR square offers Show a new code. A pairing that arrives after Cancel is cancelled at once.- Disconnect results are toasts, not page state.
- Wire types come from DSS's generated
@service-storage/generated/schemas(WhatsApp*,ExternalChat*); changecrates/whatsapp_linkedand regenerate, never hand-type. - Add failures carry DSS's
LinkedErrorcode (whatsappErrorResponse);core/add.tswords each one. Never show a catch-all message. - The chat list (
GET /whatsapp/chats) arrives sorted by recent activity; keep DSS's order. Sections follow itsadded/shared/canAdd/cannotAddReasonfields; direct chats are addable, except the chat with yourself. DSS sends reason codes (cannotAddReason, andcannot_add_<reason>on a refused add);core/chat.tswords them. User-facing copy says "chat", not "group". Community groups show as "Community · Group" (communityTitle); disappearing and community groups are addable, a community itself is not. - Adding grants access only to its owner; the generic Share dialog manages later access. Viewing never requires WhatsApp membership.
Checks
bunx vitest run --project app src/features/whatsapp-linkedbun run test:functional -- 'whatsapp-linked.spec.ts$'(mocked/whatsappand/external-chatsroutes)
Related
- Rules:
.agents/rules/web/architecture.md(FE-33) · Docs:docs/agent-guide/external.md