# Conversation identity and message IDs

> Address conversations by ID, phone number or BSUID, and match messages across responses and events.

Every conversation and message has a Polymorfa ID. Use it to send, reply,
react and match events, and treat phone numbers, BSUIDs and usernames as
aliases that can appear, change or be hidden.

All IDs are opaque decimal strings. Keep them as strings, including in
JavaScript, where converting them to numbers can lose precision.

## Conversation identity

A conversation is identified within one connected Number by:

| Field | What it is |
| --- | --- |
| `id` | The Polymorfa conversation ID. Always present on received messages. |
| `phoneNumber` | E.164, including `+`. Omitted when the person's phone number is hidden. |
| `bsuid` | A business-scoped user ID, scoped to the connected business portfolio. |
| `username` | A WhatsApp username, when known. Not a send destination. |

### Send to a conversation

Send with `conversation.id`, `conversation.phoneNumber` or
`conversation.bsuid`. At least one is required. If you supply several, they
must already identify the same conversation; supplying aliases does not link
accounts.

On a Meta Cloud API Number:

- a conversation known only by its BSUID is sent to that BSUID;
- when a phone number is also known, the message goes to the phone number;
- to reply to someone who messaged you without a visible phone number, send to
  the received `conversation.id`.

WhatsApp does not deliver one-tap, zero-tap or copy-code authentication
templates to a BSUID. Those sends fail with `invalid_parameter`.

On a Linked Devices Number, a BSUID works only when the Number already knows a
routable identity for it.

### Phone lookup and returned metadata

Linked Devices Numbers and verified Hybrid Numbers with an eligible Linked
connection resolve phone lookups with WhatsApp before sending.

`conversation.phoneNumber` is a lookup input. The `phoneNumber` in a response
or webhook is WhatsApp's reported phone for the resolved account and can differ
from the number you entered.

Keep the returned `conversation.id` for later messages and replies. Match
conversations by connected Number and ID, rather than comparing the entered
phone string with the returned one.

### Read a received conversation

Received messages identify their conversation with `id` and any available
`phoneNumber`, `bsuid` or `username`. Group messages add the author under
`conversation.sender`, with the same fields. Send requests and send results
omit `sender`. A hidden phone number is omitted, and a BSUID is never converted
into a Linked Devices user ID.

Store people by connected Number and `id`, and update aliases when they
appear. See [User identities](https://docs.polymorfa.com/messaging/user-identities#upsert-rule).

## Message identifiers

Message responses and events carry:

| Field | What it is |
| --- | --- |
| `id` | The Polymorfa message ID. Use it for message actions and `quotedMessage.id`. |
| `whatsapp_ids` | The exact WhatsApp references Polymorfa observed: `linked_devices`, `official_api`, or both. Unknown references are omitted. |
| `whatsapp_id` | A temporary single reference for older integrations. Read `whatsapp_ids` instead. |

The Polymorfa `id` does not encode test mode or connection type, and it is not
interchangeable with a WhatsApp reference. Keep it as a string, even when it
contains only digits. Acknowledgements return `messages`,
an array of `{ id, whatsapp_ids, whatsapp_id? }`; `whatsapp_id` is omitted
when its reference is unavailable.

Polymorfa keeps message and routing identifiers even when hosted message
storage is off. This does not store message content.

### Match a message across events

Use the Polymorfa `id` to match a message across responses and events.
`message.ack` lists the receipted messages by `id` in `messages`, and a
received reaction names its message in `reactionTo`. When a contact sends an HD
photo or video, the HD copy names the standard message in
`association.parentMessageId`; see [HD image pairs](https://docs.polymorfa.com/messaging/media#hd-image-pairs).

Channel messages use the same `id` and a `position` cursor for paging. See
[Channels](https://docs.polymorfa.com/messaging/channels).

## See also

- [Send messages](https://docs.polymorfa.com/messaging/send)
- [Receive messages](https://docs.polymorfa.com/messaging/receive)
- [User identities](https://docs.polymorfa.com/messaging/user-identities)
