ADR-006 — Identity Resolution via Channel Contact Profile

Status: Accepted
Date: 2026-05-21

Context

When a customer contacts support, the agent needs to look up their orders. The customer may mention an email, phone, or order number in the chat. The risk: resolving identity from what the customer claims in the message body could expose another customer's orders.

Decision

Agents always resolve customer identity from the channel contact profile, never from the message body.

Rationale

The Chatwoot contact profile captures the customer's email and phone at conversation start — from checkout widget integration, WhatsApp business account, or manual CRM entry. This is a verified identity source. What the customer types mid-chat is not.

Resolution Flow

getConversation(id) → ConversationDTO.contact.email + contact.phone
         ↓
findOrdersByEmail(contact.email)    ← from Chatwoot profile
findOrdersByPhone(contact.phone)    ← from Chatwoot profile

The agent never calls findOrdersByEmail() with a value extracted from the chat message text.

Conflict Handling

Scenario	Action
Email matches, phone returns nothing	Proceed with email result
Phone matches, email returns nothing	Proceed with phone result
Both match, same customer ID	Proceed
Both match, different customer IDs	Do not proceed — set conversation to needs_human, add internal note explaining the conflict
Neither matches	Escalate to human queue with note

Consequences

• ConversationDTO must always carry contact.email and contact.phone
• Both findOrdersByEmail and findOrdersByPhone are required on CommerceAdapterContract
• The agent prompt explicitly forbids using customer-supplied identifiers for lookups