Contacts

Who you are talking to, and how to identify them.

Find a person

Everyone who has messaged your number is a person in the Inbox. Search by name, or by the exact WhatsApp ID:

curl -H "Authorization: Token $SERVICE_TOKEN" "$INBOX/api/v1/persons/?search=anna"

To get one person, use GET /api/v1/persons/{wa_id}/.

Reference: List persons

Identifying a person

WhatsApp users can set a username and keep their phone number hidden from businesses. When they do, you may never see their number — so the Inbox cannot rely on phone numbers to identify people. Every contact, chat and message carries three identifiers instead:

Field	What it is	Always there?
wa_id	The ID the API uses everywhere: in paths such as /chats/{wa_id}/, in the wa_id filter on /messages/, and as the recipient when you send. It is the phone number when WhatsApp shares it, and the BSUID when it does not	Yes
bsuid	The Business-Scoped User ID: a stable ID WhatsApp assigns to this person for your business portfolio, such as US.13491208655302741918	Yes, once the person has messaged you
phone_number	The phone number, in international format without +	Only when WhatsApp shares it

What to store

• Store bsuid as your long-term key for a person. It does not depend on whether WhatsApp shows you their number.

• Store wa_id alongside it, and use it for API calls. Pass it back exactly as you received it.

• Treat phone_number as optional profile data. Do not use it as a key, and do not build logic that assumes every chat has one.

Things that break if you assume phone numbers

• Validating wa_id as digits only — a BSUID contains a country prefix and a dot, and can include ENT, as in US.ENT.11815799212886844830

• Matching incoming chats to your CRM by phone number only — match on bsuid first, and fall back to phone_number when it is present

• Deriving country or formatting a number for display from wa_id

In webhook payloads, the BSUID arrives in the standard WhatsApp fields, such as contacts[].user_id and messages[].from_user_id.

When and why WhatsApp shares or hides a phone number — including the 30-day window and Meta's contact book — is explained in Usernames & BSUID.