Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
whatsapp_linked
What it is
The WhatsApp provider of external chats (crates/external_chat): personal
WhatsApp accounts linked as devices, owner-bound pairing, the account's chat
list and rosters, adding an existing group or direct chat as the adder's
own ExternalChat entity (one per owner, provider and remote chat, named
after WhatsApp), ingesting chat traffic, and dispatching deliberate sends
from each person's own account. WhatsAppProvider implements
external_chat's ChatProvider; external_chat owns the timeline, read
state, sharing, send validation, uploads, notification effects and the
/external-chats routes. ChatRef.kind / external_chat.kind says group or
direct (only the owner sends in a direct chat). DSS serves /whatsapp/*; the
WhatsApp session service calls domain::session::SessionService in-process.
They share no HTTP: only MacroDB rows and NOTIFY (external_chat's
outbound::pg notify helpers).
Start here
src/domain/service.rs: DSS use cases for the account, pairing and chat list.src/domain/provider.rs:ChatProviderfor WhatsApp (adoption validation, who can send, members, names, the send outbox).src/domain/session.rs+src/domain/events.rs: the session-service API and its event types (no whatsmeow types).src/outbound/pg/ingest.rs: canonical identity(binding, person, source id), quarantine, deferral and the standalone message write. Senders are resolved first (resolve_sender_in): WhatsApp's from-me flag means the account's own identity; a LID-only sender takes its phone number from the account's roster pair. Only what is still LID-only is quarantined. Each stored sender records awhatsapp.ingest.personspan (chat kind, LID or not, paired,message_named,person_created,person_named; no names or addresses).- Structured content (
external_chat::domain::rich::RichContent: poll, poll vote, location, contact cards, event, system line) is stored inexternal_chat_message.rich;kind = 'system'rows never notify or count as unread.GroupRepository::peoplenames the WhatsApp ids in mentions, system lines and votes forexternal_chat's timeline view. Poll votes are stored per voter inexternal_chat_poll_votethrough the reaction path ofreserve_in. A re-ingested message fills inrich/mentions/forwardedan earlier copy lacked (re-importing history upgrades old placeholders). src/outbound/pg/chats.rs: the account's chat list (whatsapp_chat,GET /whatsapp/chatsviaWhatsAppService::chats) and importing earlier messages of added chats (backfill_*columns onexternal_chat; limitsBACKFILL_MESSAGE_LIMIT/BACKFILL_MAX_AGE_DAYSinmodels.rs). The anchor is the chat'swhatsapp_chat.anchor, else the newest stored message the account saw; with one a chat waits for the owner's Import (waiting_for_phone;POST /whatsapp/history-import→pending+whatsapp_history_requested), without one a group iswaiting_for_messageuntil a chat update brings one, and a direct chat (a saved contact, a looked-up number) is addeddone, madewaiting_for_phoneonly by an anchor older than its adoption while nothing was imported. The phone is never asked without that Import. Recording an anchor and adding a chat share a per-user advisory lock (lock_anchors_in), so a chat added while its first message is recorded still sees it. Saved contacts are chat-list rows with no activity. History messages skip the adoption-time boundary but only reach the account owner's own groups (observed_bindings_in).src/outbound/pg/lookups.rs: phone-number lookups (whatsapp_lookup,POST/GET /whatsapp/lookups): DSS records one (E.164PhoneNumberindomain/jid.rs, human sessions only,LOOKUP_LIMITperLOOKUP_WINDOW_MINUTES, a pending one of the same number is reused) and signalswhatsapp_lookup_requested; the session records the answer, and a found number joins the chat list soadoptaccepts it unchanged. Pending pastLOOKUP_EXPIRY_SECONDSreadsfailed; rows go with the account's consent and after the window.src/outbound/pg/sends.rs: enqueue, claim, dispatch fence, outcome. A repeated intent key returns the stored send before any other check.src/signals.rs: the DSS ↔ session-serviceNOTIFYchannels; payloads, trace context and the channels DSS listens on areexternal_chat::signals. Writes send them inside the writing transaction. Every write a page shows callsnotify_change(external_chat_changed); DSS pushes it to viewers. Roster writes signal only real changes (groups.rssame_facts).- Migrations:
crates/macro_db_client/migrations/20261027061310_whatsapp_linked.sql(the first schema, with its entity type validation), then20261027194950_whatsapp_attachments_as_static_files.sql(attachments keep a staticfile_id), then*_external_chat.sql(the genericexternal_chat*tables, the view ruleexternal_chat_access_levelthat entity_access also calls, andwhatsapp_roster/whatsapp_chat_membership; released files queue inexternal_chat_file_deletion) and its entity type validation, then*_whatsapp_lookup.sql(phone-number lookups). Deleting a user cascades to their account, chats (with their grants, entity record and sharing settings) and sends; aliases outlive the account that saw them.
Boundaries
- Depends on:
external_chat(models, ports, generic table helpers),entity_access_db_utils(the adopter's owner grant),entity_registry_db_utils, andshare_permission_db_utils. - Used by: DSS (
src/external_chat.rscomposition), the session service.
Checks
cargo test -p whatsapp_linked --all-features(SQLX_OFFLINEunset); its Postgres tests also coverexternal_chat's reads and writes end to end.- Check
--no-default-features --features portsandinboundindependently; domain dependencies must be enabled byports, not only by the Postgres adapter.
Gotchas
- Pairing reads and account controls require a human session (the
authority rules, send budget and
SendRateLimiterareexternal_chat's). - Lock accounts before groups, then child rows; lock every group in a batch in UUID order. Pairing expiry locks affected accounts before pairing rows. Media completion takes the group lock before attachment/message writes.
- Every session-service write takes the account row lock at the caller's
lease_epoch;ExternalChatError::Fencedmeans stop the account now. - Adding a chat takes the account row exclusively, against those share-mode
fences: a chat-list update and an add running side by side could otherwise
each miss the other's write and leave the chat in
waiting_for_message. dispatch_started_atis written before submission. A dispatched send without an outcome becomesunknownon takeover and is never resent; a later echo with itsallocated_source_idsettles it.- View access is independent of WhatsApp membership (see
crates/external_chat); only the adopter receives an owner grant. Queries look chats up by(provider, remote_id). - Store messages/reactions/attachments/poll votes in
external_chat_message,external_chat_reaction,external_chat_attachmentandexternal_chat_poll_vote; never native comms tables. - Attachment bytes cross Postgres (
external_chat_media_blob, ≤ 32 MiB) because the session service has no file storage;external_chat'sMediaServicein DSS turns them into static files.events::Media::locatoris sealed by the session service; never read it.src/outbound/pg/media.rs: download claims. Not implemented: participant-receipt UI.
Related
- Docs:
docs/architecture/external-chats.md,docs/architecture/whatsapp-linked-devices.md· Rules:.agents/rules/observability.md