Recognising who sent a WhatsApp message
The sending number is an Identity — one address on one channel — and identity.py resolves it to a Person in the workspace's relationships. If that address is already known, the message joins that person's history across every channel. If it is not, a Person is created with the number as its first identity and whatever the profile offered as a provisional name.
Identity, Person, Company#
- Identity
- One address on one channel: a WhatsApp mobile, an email address, a phone line. It belongs to exactly one Person.
- Person
- A human. Carries several identities, a lifecycle stage, a timeline and everything Connect remembers about them.
- Company
- An organisation. People belong to it; conversations roll up to it.
Keeping these three apart is what makes a WhatsApp message useful rather than a loose chat. Because the identity resolves to a Person rather than standing alone, the reply Connect drafts can see that this is the same human who raised a support case by email in March, and the Customer 360 view shows one history instead of three.
How the match is made#
Matching works from the number, normalised, and nothing else is treated as an identifier. A WhatsApp profile name is a hint — people set them to nicknames, business names and emoji — so it may become a provisional display name on a brand-new record, but it never causes two records to be joined.
This is deliberate and it is the conservative choice in both directions. Connect will not merge two people because their names look alike, and it will not split one person because they changed their profile. The cost is that a customer who writes from a second number arrives as a second Person until somebody merges them; the benefit is that no stranger inherits somebody else's history.
A QR-linked number adds one more source of names and no more identifiers. Meta shares the WhatsApp Business app's own address book at onboarding and again as it changes, so a thread can be titled the way the business already had that person saved on the handset rather than by the name the sender chose for their profile. _apply_state_sync only ever fills a name that is missing; it never joins two records, and the number remains the only thing resolution works from.
When the sender is unknown#
A message arrives from a mobile no identity matches.
Result A Person is created in that workspace, with the number as its first identity. Nothing is merged and nothing is guessed about who they work for.
The conversation proceeds like any other.
Result Knowledge grounds the answer; memory at the workspace and channel tiers applies. There is no contact-tier memory yet, because there was no contact until a moment ago.
Somebody later recognises the person on
#/relationships.Result Merging joins the identities, and the whole WhatsApp history moves with it onto the surviving record.
Correcting a wrong attachment#
Two things go wrong, and they have different fixes. If two records are the same human, merge them from the relationship screen — relationship_console.py owns duplicates, and merging moves identities, conversations and memory onto one record. If one record is two humans, which happens when a line is reassigned or a shared handset is used, the number has to be detached from the Person it no longer belongs to before anything else is corrected.
Either way the correction is made against the record, not against the individual message, and the engine reads the corrected state next time it picks up work. The WhatsApp message attached to the wrong person sets out the order to do this in and what changes as a result.
A merge is not silent. It is recorded, so months later the question "why does this timeline contain a conversation from a stranger I do not recognise" has an answer that does not depend on anybody's memory.
Questions#
Does Connect look the number up anywhere public to find out who owns it?
No. Resolution is against your own workspace's identities. Research on an organisation is a prospecting activity with its own evidence rules — see Evidence-first prospecting — and it is not applied to a person who wrote to you.
Someone messages from a personal number about a company account. Does Connect know?
Not from the number alone. Once you attach that Person to the Company, or tell Connect in memory, it does. Until then it treats them as a Person with no organisation, which is honest rather than helpful.
What if the same human writes from two numbers at once?
Two Persons, two threads, until they are merged. The reply on each thread reflects what that thread knows, so the two conversations can differ — which is usually the thing that makes somebody notice the duplicate.