Skip to main content
A conversation is the WhatsApp thread between your business and a contact. Almost every send and action endpoint (/conversation/*) takes it in the request body under the conversation object.

​
Identifying a conversation

The conversation object accepts one of four identifiers. The resolver evaluates them in this order: uuid → whatsapp_user_id → username → phone: whatsapp_user_id looks up by exact match and username by a case-insensitive match (case is ignored); phone is normalized to digits. When the contact has a BSUID, phone and whatsapp_user_id identify different values (see Note).
​
uuid
string
The UUID from a GET /conversations. The most direct and stable path (it can become stale if two conversations of the same contact are merged — see the merge note below).
​
whatsapp_user_id
string
The contact’s BSUID (Meta’s opaque identity). Resolves by exact match against the stored BSUID; if it does not resolve, the endpoint returns 404 without falling back to phone. Recommended identifier going forward.
​
username
string
The contact’s public WhatsApp username, with or without a leading @ and case-insensitive. Best-effort resolution against the last username observed by the platform (users can change their handle); if several contacts share it, the endpoint returns 409 (USERNAME_AMBIGUOUS).
​
phone
string
Number in E.164 format (+5215512345678). Normalized to digits before the lookup. Useful when all you have is the phone.
The phone number can be duplicated across contacts (recycled numbers or separate identities sharing a number): in that case the API returns 409 (PHONE_NUMBER_AMBIGUOUS) instead of guessing — identify the conversation by whatsapp_user_id or uuid. Also, whatsapp_user_id can change if the user re-registers their WhatsApp account (identity rotation on Meta’s side). Use the uuid as the stable key in your system and whatsapp_user_id as the preferred resolution identifier.
phone and whatsapp_user_id are different identifiers: phone is the phone number (wa_id without +) and whatsapp_user_id is the contact’s BSUID. They coincide only while the contact has no BSUID. In responses, whatsapp_user_id returns the real BSUID when present, with a fallback to the phone so there is always a resolvable value. Watch the round-trip: if the contact has no BSUID yet, this field carries the phone; re-send it as phone then, not as whatsapp_user_id — the resolver matches whatsapp_user_id by exact match and would return 404.
When the same contact ended up recorded twice by identity (for example, first only with their phone and later with their BSUID), the two conversations are merged automatically into one: the full history moves to the survivor. The absorbed conversation’s uuid stops resolving and returns 404; the phone and the BSUID migrate to the survivor. If a uuid you stored starts returning 404, re-resolve the conversation by phone or whatsapp_user_id.

​
The 24h window

This is WhatsApp’s core concept and it decides what you can send.
1

The contact messages you

WhatsApp opens a 24-hour window. Each new message from the contact resets the timer.
2

Window open

You can send free-form messages: text, media, and quick replies.
3

24h pass with no reply

The window closes. The only allowed message is a template approved by Meta.
4

Sending a template reopens the window

You can send free-form messages again.
Sending text, media, or a quick reply with the window closed fails with WINDOW_CLOSED (422). Send a template first to reopen it.

​
Checking the window status

Before sending a free-form message, you can verify whether the window is open with POST /conversation/status:
The response includes window.status (open or closed) and window.hours_remaining, plus the assignment, mailbox, tags, and inbox_status of the conversation. Use it to decide between a free-form message and a template.

​
Next steps

Send messages

Text, media, quick replies, and templates.

Templates

How to send templates when the 24h window is closed.