How a WhatsApp message moves through Neo

Inbound receipt

Meta verification uses the configured verification token. Message callbacks require the provider signature. The adapter parses a normalized event, redacts sensitive invite or identity text, and commits a durable inbox envelope before acknowledging Meta.

sequenceDiagram
  participant M as Meta
  participant A as API
  participant Q as inbox_events
  participant W as Worker
  participant C as Conversation
  M->>A: Signed webhook
  A->>A: Verify, parse, redact
  A->>Q: Durable receipt
  A-->>M: 200
  W->>Q: Ordered claim
  W->>C: Process one conversation turn
  C->>Q: State, decision, and outbox

Session identity and ordering

A WhatsApp session is unique by channel and canonical phone identity. The database stores state/schema versions, automation status, and the latest provider marker. PostgreSQL worker claims and advisory locks serialize one conversation. Compare-and-swap state updates reject stale writes.

Late messages are retained as read-only evidence; they cannot execute an old confirmation against newer state.

Native payload precedence

Signed native product selection, catalogue cart, Flow completion, and interactive reply payloads carry stronger transport meaning than a model guess about their text representation. They bypass irrelevant clarification and run deterministic handlers.

The default-off dynamic buyer checkout chooses one shop before products and prevents cross-shop composition. Its completion stages only the cart, quote, and pending confirmation. Native referred products and store-scoped carts remain compatibility fallbacks.

Reply surfaces

Buttons and lists are used only when the next step has bounded choices that the response actually presents. Product no-stock outcomes show the exact executed query and attach the six-row category list directly, so one tap opens Fashion, Beauty, Food, Gadgets, Home, and Deals; targeted questions and informational notices remain plain text. Structured checkout, seller-identity, and shop-first discovery tasks use signed WhatsApp Flows.

A valid native one-store cart opens one buyer checkout Flow for address, a fresh delivery quote, payment method, and review. The returned WhatsApp summary exposes Pay Now, Edit Checkout, and Cancel; only Pay Now creates the awaiting-payment order and payment request, without claiming the order is confirmed. Only provider-confirmed payment produces the buyer's payment and order confirmation plus bound tracking action. A definitive Meta Flow rejection preserves the cart behind Resume Checkout and Get Help, while ambiguous outcomes reconcile without risking a duplicate reply. Pure greetings preserve active workflow state and controls. Outbound messages are persisted with a stable relationship to the inbound event and response sequence.

Evidence and tests

• src/whatsapp.ts
• src/buyer-checkout-flow.ts
• src/whatsapp-flow-endpoint.ts
• src/provider-runtime.ts
• src/durable-queue.ts
• src/meta-commerce.ts
• test/buyer-checkout-flow.test.ts
• test/whatsapp-flow-endpoint.test.ts
• test/whatsapp.test.ts
• test/provider-runtime.test.ts
• test/phase2-postgres-runtime.test.ts