User identities
Use one user ID while retaining phone numbers and usernames as optional aliases.
Use id to identify a user, group, or bot within a connected Number. IDs are opaque decimal strings. Keep them as strings, including in JavaScript; converting them to numbers can lose precision. Phone numbers, business-scoped user IDs (bsuid), and usernames are separate, optional aliases.
{
"id": "739182640518203",
"phoneNumber": "+15550001111",
"username": "example"
}Use the connected Number and id as your contact's key. Update phoneNumber, bsuid, and username when present; a changed or hidden alias does not create a new user.
Presence updates through a known phone-number alias apply to an active subscription for the same user. They do not subscribe to additional contacts.
Resolve an alias#
These reads require the contacts:read scope.
Resolve a phone number or username before creating a local contact:
curl "https://api.polymorfa.com/messaging/{session}/identities/resolve?phoneNumber=%2B15550001111" \
-H "Authorization: Bearer $POLYMORFA_TOKEN"curl "https://api.polymorfa.com/messaging/{session}/identities/resolve?username=example" \
-H "Authorization: Bearer $POLYMORFA_TOKEN"The response uses the same identity shape:
{
"data": {
"id": "739182640518203",
"phoneNumber": "+15550001111",
"username": "example"
}
}Some usernames require a four-digit key. A response with "keyRequired": true contains no guessed identity. Repeat the lookup with usernameKey=1234 after obtaining the key from the user.
You can also pass an existing id to read its known aliases.
Verify a user's encryption identity#
Request WhatsApp's identity verification code with the stable user ID:
curl "https://api.polymorfa.com/messaging/{session}/users/739182640518203/security-code" \
-H "Authorization: Bearer $POLYMORFA_TOKEN"{
"data": {
"id": "739182640518203",
"phoneNumber": "+15550001111",
"username": "example",
"numericCode": "123456789012345678901234567890123456789012345678901234567890",
"qrCode": "base64-encoded-display-payload"
}
}Compare numericCode with the code shown by the other user. To use qrCode, base64-decode it and render the resulting bytes as the QR content for comparison. A changed code means the account's identity or linked-device set changed and must be verified again. The endpoint accepts a user ID from the same Number; resolve phone numbers and usernames first. Polymorfa returns WhatsApp's display payload and never exposes the underlying identity-key payload.
Hidden phone numbers#
A missing phoneNumber does not mean the user is unresolved. Continue using their id. To ask a contact without a known phone number to share their phone number, send a consent request:
{
"conversation": { "id": "739182640518203" },
"content": { "requestPhoneNumber": {} }
}The recipient can decline. If they accept, Polymorfa emits a message.received webhook with type: "phone_number_shared"; the sender's id is unchanged and phoneNumber is added as an alias.
Official API identity changes#
The Official API behavior below requires enrollment in the Official API beta. An SDK upgrade does not grant access.
An Official API event includes parentBsuid when WhatsApp supplies a parent business-scoped user ID (CC.ENT.…). Keep it as metadata beside the person's id and bsuid. Polymorfa refuses parent IDs as recipients with parent_bsuid_not_supported; use the person's ordinary bsuid or id. Parent IDs are also unsupported for blocking and unblocking.
When WhatsApp reports a phone number or BSUID change, contact.update includes identityChange.reason (phone_number_changed or user_id_changed), the provider notification's messageId, and optional identityChange.previous with the earlier id, bsuid, and parentBsuid. The event's top-level identity is the new identity. Keep the old record and review the reported relationship; Polymorfa does not merge the two identities automatically. A username change alone does not change a BSUID.
Keep optional phone numbers separate from BSUIDs. In the TypeScript SDK, check your installed package's types before you read newly added event fields such as parentBsuid and identityChange; when the package lacks them, read the raw event body.
Block and unblock a contact#
Use the person's public contact ID from the same Number with API Block contact or API Unblock contact. Both require contacts:manage. For an Official API Number, Polymorfa sends the request to WhatsApp using the known phone number or ordinary BSUID. A Hybrid Number prefers its enabled Official connection when that contact has a phone number or ordinary BSUID. Contacts known only by a Linked Devices identity use that connection.
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/contacts/$CONTACT_ID/block" \
-H "Authorization: Bearer $POLYMORFA_KEY"curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/block_users" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"block_users": [{ "user": "+15550001111" }]
}'The Graph methods use POST and DELETE /{version}/{phoneNumberId}/block_users, with a JSON body containing block_users: [{ "user_id": "US.synthetic1" }] for a BSUID, or block_users: [{ "user": "+15550001111" }] for a phone number. Both methods require the body, including DELETE. Supply 1 to 1,000 entries. If an entry contains both fields, WhatsApp gives user precedence. Changes need messages:write and the blocked-user list needs sessions:read.
WhatsApp requires recent contact activity for blocking. Native requests report conversation_window_closed when WhatsApp rejects the activity window. If a request returns service_unavailable after dispatch, its effect is unconfirmed. Reconcile the contact's blocked state before repeating the change. Polymorfa does not automatically repeat an ambiguous provider write.
Upsert rule#
For every contact, participant, sender, voter, presence source, and blocklist entry:
- Upsert by connected Number and
id. - Update
phoneNumber,bsuid, andusernameonly when they are present. - Never create a second record because an alias appeared, changed, or disappeared.
This rule prevents one person from becoming separate phone-number, username, and ID records.
Linked devices#
Device lookups return the user's id, any known aliases, and a numeric device value. Together, they identify a linked device:
{
"id": "739182640518203",
"device": 4
}