JID Utilities

Overview

JIDs (Jabber IDs) are unique identifiers used in WhatsApp to identify users, groups, and other entities. A JID typically follows the format user@server where:

user: The unique identifier (phone number for users, group ID for groups)
server: The WhatsApp server domain (e.g., s.whatsapp.net, g.us, lid)

The JID utilities module provides functions to parse, normalize, and validate WhatsApp JIDs.

All JID utility functions accept unknown types and safely handle type conversion, making them safe to use with any input.

Functions

decode()

Decodes a JID string into its constituent parts.

function decode(jid: unknown): IJidDecoded

jid

unknown

required

The JID to decode. Can be any type - will be converted to string internally.

IJidDecoded

object

An object containing the decoded JID components:

jid

string

The user/group identifier part (before the @ symbol)

server

string

The server domain part (after the @ symbol)

Example

import { decode } from 'wapi/utils/jid';

const decoded = decode('1234567890@s.whatsapp.net');
console.log(decoded);
// { jid: '1234567890', server: 's.whatsapp.net' }

normalize()

Normalizes a JID by removing device identifiers and ensuring consistent formatting.

function normalize(jid: unknown): string

jid

unknown

required

The JID to normalize. Can be any type - will be converted to string internally.

string

The normalized JID in the format user@server

Example

import { normalize } from 'wapi/utils/jid';

const normalized = normalize('1234567890:0@s.whatsapp.net');
console.log(normalized);
// '1234567890@s.whatsapp.net'

Normalizing JIDs is important when storing or comparing them, as WhatsApp may send JIDs with device identifiers that should be ignored for identification purposes.

isGroup()

Checks if a JID represents a WhatsApp group.

function isGroup(jid: unknown): jid is `${string}@g.us`

jid

unknown

required

The JID to check. Can be any type - will be converted to string internally.

boolean

true if the JID is a group (server is g.us), false otherwise

Example

import { isGroup } from 'wapi/utils/jid';

console.log(isGroup('120363012345678901@g.us'));
// true

console.log(isGroup('1234567890@s.whatsapp.net'));
// false

Group JIDs always use the g.us server domain. Don’t confuse them with broadcast lists or other WhatsApp entities.

isPn()

Checks if a JID represents a personal/private number (regular WhatsApp user).

function isPn(jid: unknown): jid is `${string}@s.whatsapp.net`

jid

unknown

required

The JID to check. Can be any type - will be converted to string internally.

boolean

true if the JID is a personal number (server is s.whatsapp.net), false otherwise

Example

import { isPn } from 'wapi/utils/jid';

console.log(isPn('1234567890@s.whatsapp.net'));
// true

console.log(isPn('120363012345678901@g.us'));
// false

isLid()

Checks if a JID represents a LID (Local ID) - used for WhatsApp’s newer identity system.

function isLid(jid: unknown): jid is `${string}@lid`

jid

unknown

required

The JID to check. Can be any type - will be converted to string internally.

boolean

true if the JID uses the lid server domain, false otherwise

Example

import { isLid } from 'wapi/utils/jid';

console.log(isLid('abc123xyz@lid'));
// true

console.log(isLid('1234567890@s.whatsapp.net'));
// false

LIDs are part of WhatsApp’s newer identity system and may be encountered when working with certain types of accounts or business features.

Type Definitions

IJidDecoded

Interface representing a decoded JID.

interface IJidDecoded {
  jid: string;      // The user/group identifier
  server: string;   // The server domain
}

Common Patterns

Validating and Normalizing User Input

import { normalize, isPn } from 'wapi/utils/jid';

command('add', async (ctx) => {
  const userInput = ctx.args[0]; // e.g., "1234567890@s.whatsapp.net"
  
  // Normalize to remove device IDs
  const normalized = normalize(userInput);
  
  // Validate it's a personal number
  if (!isPn(normalized)) {
    await ctx.reply('Please provide a valid user JID!');
    return;
  }
  
  // Safe to use
  await addUserToList(normalized);
});

Creating Type-Safe Handlers

import { isGroup, isPn, isLid } from 'wapi/utils/jid';

function handleMessageByType(jid: string, message: string) {
  if (isGroup(jid)) {
    // Handle group message
    console.log('Group message:', message);
  } else if (isPn(jid)) {
    // Handle private message
    console.log('Private message:', message);
  } else if (isLid(jid)) {
    // Handle LID message
    console.log('LID message:', message);
  } else {
    console.log('Unknown JID type');
  }
}

Core Classes

Authentication

Utilities

JID Utilities

Overview

Functions

decode()

Example

normalize()

Example

isGroup()

Example

isPn()

Example

isLid()

Example

Type Definitions

IJidDecoded

Common Patterns

Validating and Normalizing User Input

Creating Type-Safe Handlers

See Also

Build docs developers (and LLMs) love

Core Classes

Authentication

Utilities

​Overview

​Functions

​decode()

​Example

​normalize()

​Example

​isGroup()

​Example

​isPn()

​Example

​isLid()

​Example

​Type Definitions

​IJidDecoded

​Common Patterns

​Validating and Normalizing User Input

​Creating Type-Safe Handlers

​See Also

Build docs developers (and LLMs) love

Overview

Functions

decode()

Example

normalize()

Example

isGroup()

Example

isPn()

Example

isLid()

Example

Type Definitions

IJidDecoded

Common Patterns

Validating and Normalizing User Input

Creating Type-Safe Handlers

See Also