Skip to content
Shortcut: /, ⌘K or Ctrl+K

User identities

Use one user ID while retaining phone numbers and usernames as optional aliases.

View as Markdown

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.

JSON
{
  "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:

Shell
curl "https://api.polymorfa.com/messaging/{session}/identities/resolve?phoneNumber=%2B15550001111" \
  -H "Authorization: Bearer $POLYMORFA_TOKEN"
Shell
curl "https://api.polymorfa.com/messaging/{session}/identities/resolve?username=example" \
  -H "Authorization: Bearer $POLYMORFA_TOKEN"

The response uses the same identity shape:

JSON
{
  "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:

Shell
curl "https://api.polymorfa.com/messaging/{session}/users/739182640518203/security-code" \
  -H "Authorization: Bearer $POLYMORFA_TOKEN"
JSON
{
  "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:

JSON
{
  "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
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/contacts/$CONTACT_ID/block" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
Graph API
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:

  1. Upsert by connected Number and id.
  2. Update phoneNumber, bsuid, and username only when they are present.
  3. 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:

JSON
{
  "id": "739182640518203",
  "device": 4
}

See also#