# 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.

```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:

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

```bash
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:

```bash
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
`POST /messaging/{session}/contacts/{contactId}/block` or
`POST /messaging/{session}/contacts/{contactId}/unblock`. 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.

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/contacts/$CONTACT_ID/block" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```bash 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" }]
  }'
```

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Not supported.

[Block](https://docs.polymorfa.com/api/graph/blocklist/block),
[Unblock](https://docs.polymorfa.com/api/graph/blocklist/unblock) and
[List blocked contacts](https://docs.polymorfa.com/api/graph/blocklist/list-blocked-contacts)
work on Meta Cloud API Numbers. Linked Devices Numbers return capability error
`131026`.

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

- [Conversation identity and message IDs](https://docs.polymorfa.com/messaging/ids)
- [Contacts and groups](https://docs.polymorfa.com/messaging/contacts-and-groups)
- [Identities API reference](https://docs.polymorfa.com/api/identities/resolve-identity)
