Identify the whatsapp sender by phone number and create or associate the profile
The system uses the sender's WhatsApp id (`wa_id`, their phone number) — a reliable identifier — to find the matching Contact or create a new one, rather than trusting the sender's editable WhatsApp display name.
When this happens: UC-16.5 main flow, step 4.
How it works
- Normalizes the inbound
wa_idto E.164 and looks upContactChannelIdentityrows withIdentifierKind ∈ {Phone, WhatsAppId}for the tenant. - EasyCRM finds a match on an existing Contact's phone number and associates the message with that Contact.
Other paths
No existing match
No match is found. EasyCRM creates a new Contact with WhatsApp, seeded from the WhatsApp profile display name, and a new ContactChannelIdentity (WhatsAppId, the E.164 wa_id). Also records the same number under Phone when the Contact has no other phone on file, so the Contact is reachable on phone-based channels without re-entry.
Good to know
- The WhatsApp profile display name is never used as a matching key — only the
wa_id(phone number) is. (FR-16-006, BRD §3.8) - Identification happens before conversation resolution, so
Conversation.Contactis always set from the first message.