Understanding Chat IDs

Every conversation is addressed with a chat ID. Use the identifier returned by an event or lookup when you have one; only construct an ID from a phone number when you are deliberately addressing a direct contact.

Accepted API formatsCopy Anchor Link

The current ChatId schema accepts these forms:

The schema is a validation contract for method inputs. It does not prove that every WhatsApp account, device, or incoming payload uses every form shown here. In particular, a LID is an opaque WhatsApp identifier: this guide does not claim that all LIDs are colon-separated or that a LID can be derived from a phone number.

Phone numbers and direct-contact IDsCopy Anchor Link

For a direct contact, use the country code, remove the leading +, spaces, dashes, and parentheses, then append @c.us:

function phoneToChatId(phone: string): string {
  const digits = phone.replace(/\D/g, '');
  return `${digits}@c.us`;
}

phoneToChatId('+44 7700 900000'); // '447700900000@c.us'

The runtime also has a codec for bare numeric input. It preserves already formatted IDs; for bare digits it applies heuristic rules, including a special case for 18 digits as a group ID and 14 digits (except numbers beginning with 62) as a LID. Prefer an explicit suffix when you know the identifier because those heuristics cannot establish what a real WhatsApp account represents.

Group IDsCopy Anchor Link

Group IDs are assigned by WhatsApp. Keep the full value exactly as returned by message.from, message.chatId, a group lookup, or a group method; do not rebuild one from a group name, participant numbers, or a timestamp assumption.

client.onMessage((message) => {
  if (message.isGroupMsg) {
    console.log('Group ID:', message.chatId);
  }
});

An invite URL is an invite token, not a group ID. If the workflow is to join a group, pass the URL to joinGroupViaLink and keep the returned identifier only after checking the method's result. The method is license-gated and can return a failure value, so a successful HTTP request alone is not proof that a group was joined.

const result = await client.joinGroupViaLink(
  'https://chat.whatsapp.com/REDACTED_INVITE_TOKEN'
);

if (typeof result === 'string') {
  console.log('Joined group:', result);
} else {
  console.error('The invite could not be resolved:', result);
}

Incoming fields and LIDsCopy Anchor Link

Message events expose the conversation through fields such as from and chatId. Representative sanitized payloads for the documented contact and group forms look like this:

{
  "from": "447700900000@c.us",
  "chatId": "447700900000@c.us",
  "isGroupMsg": false
}

{
  "from": "447123456789-1445627445@g.us",
  "chatId": "447123456789-1445627445@g.us",
  "isGroupMsg": true
}

The supported source and schema do not establish one universal incoming LID representation beyond the numeric @lid input accepted by the current API. When an event contains a LID, pass the exact from or chatId value to the next method and record the release and event payload before documenting a new shape. Do not split, rewrite, or infer a phone number from it.

Common mistakesCopy Anchor Link

RelatedCopy Anchor Link

• Messages guide: Send and receive messages with chat IDs
• Groups guide: Work with group chats and invite links
• Client messages reference: Exact method parameters and return types