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.
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.
Channel messages use the same id and a position cursor for paging. See Channels.