# Identifiers

Source: https://docs.revoplyai.com/get-started/identifiers/

> Phone numbers, WhatsApp ids, other channels' user ids and our own ids, and when a phone number is null.

## Phone numbers: `phone` [#phone-numbers-phone]

`phone` is always an [E.164](https://en.wikipedia.org/wiki/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-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 [#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 [#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.