Identifiers
Phone numbers, WhatsApp ids, other channels' user ids and our own ids, and when a phone number is null.
Phone numbers: phone
phone is always an E.164 number, such as
+966501234567, or null. It is never a WhatsApp user id, and never a number without its
country code.
phone is null when:
- the customer wrote on Messenger, Instagram, Telegram or the website widget: those channels do not share a phone number;
- WhatsApp withheld the number and named the customer by a user id instead (see below);
- the number on a contact was saved without a country code, such as
0501234567. We do not guess the country.
WhatsApp ids: whatsAppId
WhatsApp does not always tell a business the customer's number. It names every customer by one of:
| Form | Example | Seen on |
|---|---|---|
wa_id: the number | 966501234567 | WhatsApp Business numbers and WhatsApp QR |
| Business-scoped user id (BSUID) | EG.1525166372698999 | WhatsApp Business numbers, when the number is withheld |
@lid | 123456789012345@lid | WhatsApp QR, when the number is withheld |
In message.received, conversation.started, conversation.handover,
conversation.resolved and flow.* events, contact.whatsAppId is the
id the conversation is filed under: for a number, the digits without + (and phone holds
the same number in E.164); for a BSUID or an @lid, the id as WhatsApp sent it (and
phone is null). It is null on every other channel.
In contact.* events, whatsAppId is the BSUID or @lid a contact is filed under, and
null when only their number is known. In appointment.* events it is always null, and
phone is set only when the booking recorded the number with its country code.
A BSUID's digits and an @lid's digits are not phone numbers. Do not dial them, and do not
match them against the numbers in your CRM.
Other channels
Messenger, Instagram and Telegram name customers by ids they issue for your page, account
or bot: a page-scoped id (PSID), an Instagram-scoped id (IGSID) or a Telegram chat id.
These are not phone numbers and are not sent as phone or whatsAppId. Use contact.id
to refer to such a customer. Website widget visitors have no contact: their
contact.id is null.
Our ids
| Id | Format | Example |
|---|---|---|
company.id | UUID | 0b3d6f2e-8a41-4c75-9e20-5f7a1c3d9b84 |
channelId | UUID | 7c1e4b2a-9d3f-4e58-a6b1-2f0c8d7e5a13 |
contact.id | UUID | 3f6a2d18-0b7c-4e91-8a5d-c24e1f9b7a60 |
conversation.id | Opaque string | WhatsApp_3f6a2d18-0b7c-4e91-8a5d-c24e1f9b7a60 |
message.id | Opaque string; received messages start with m_ | m_wamid.HBgMOTY2NTAxMjM0NTY3FQIAEhgg… |
Event id | evt_ and 32 hex characters | evt_5dabddce7c097ab703f21e8fdf0ab52b |
X-Revoply-Delivery | UUID | 5a9e2c7b-1f34-4d86-b0a5-3c8e7d2f1b69 |
flow.id, run.id | UUID | b16d4f8a-2c9e-4b73-a5d1-0e8f3c7a9b25 |
| Flow trigger token | rvh_ and 43 URL-safe characters | rvh_EXAMPLE… |
| Webhook signing secret | whsec_ and 43 URL-safe characters | whsec_EXAMPLE… |
Treat every id as an opaque string. Conversation and message ids can contain _, .,
+, = and @, can be long (store them as text, up to 1,500 bytes), and their shape
differs between older and newer conversations: never parse a channel or a phone number out
of them. URL-encode them when you put them in a URL.