JIDs, helpers & constants

A JID (Jabber ID) is how WhatsApp addresses every entity. zapo exports a set of helpers to build and classify them, all from the package root:

import { parsePhoneJid, isGroupJid, splitJid } from 'zapo-js'

JID shapes

Entity	Example
User (phone)	`5511999999999@s.whatsapp.net`
Group	`123456789-987654@g.us`
Newsletter / channel	`120363000000000000@newsletter`
Status broadcast	`status@broadcast`
LID (privacy id)	`123456789@lid`

Building JIDs

// Phone number → user JID
parsePhoneJid('5511999999999')        // '5511999999999@s.whatsapp.net'

// Normalize anything into a recipient JID (accepts a number or string)
normalizeRecipientJid('5511999999999')

// Strip a device suffix down to the base user JID
toUserJid('5511999999999:12@s.whatsapp.net') // '5511999999999@s.whatsapp.net'

// Build a device-scoped JID
buildDeviceJid('5511999999999', 's.whatsapp.net', 12)

Parsing & splitting

splitJid('5511999999999@s.whatsapp.net')  // { user, server }
parseJidFull(jid)                         // ParsedJid with full breakdown
parseSignalAddressFromJid(jid)            // { user, server, device }

Classifying JIDs

Boolean predicates for routing logic:

Helper	True for
`isGroupJid(jid)`	Group (`@g.us`)
`isGroupOrBroadcastJid(jid)`	Group or broadcast
`isBroadcastJid(jid)`	Broadcast list
`isStatusBroadcastJid(jid)`	`status@broadcast`
`isNewsletterJid(jid)`	Newsletter (`@newsletter`)
`isLidJid(jid)`	LID (`@lid`)
`isBotJid(jid)`	A bot (`@bot`)
`isHostedDeviceJid(jid)`	Hosted device

client.on('message', (event) => {
  if (isGroupJid(event.key.remoteJid)) {
    console.log('a group message')
  }
})

Constants

The full set of protocol constants is exported as frozen WA_* objects (the library uses these instead of TypeScript enums). The most commonly used:

Constant	Contains
`WA_DEFAULTS`	Default timeouts, the status-broadcast JID, the default device browser, …
`WA_BROWSERS`	Browser identifiers for the device fingerprint.
`WA_PRIVACY_CATEGORIES` / `WA_PRIVACY_VALUES`	Privacy setting names and allowed values.
`WA_DISCONNECT_REASONS` / `WA_LOGOUT_REASONS`	Reason strings on connection events.
`WA_MESSAGE_TYPES` / `WA_MESSAGE_TAGS`	Message classification.
`WA_NODE_TAGS` / `WA_XMLNS`	Protocol node tags and XML namespaces.
`WA_APP_STATE_COLLECTIONS`	App-state collection names.

import { WA_DEFAULTS, WA_LOGOUT_REASONS } from 'zapo-js'

await client.logout(WA_LOGOUT_REASONS.USER_INITIATED)

Associated string-literal types are also exported for annotation: WaPrivacyCategory, WaPrivacySettingName, WaPrivacyValue, WaDisconnectReason, WaLogoutReason, WaConnectionCode, WaStreamErrorCode, WaFailureReasonCode, and ParsedJid.

Message helpers

Two helpers for inspecting and targeting messages, exported from the package root:

Export	Signature	Description
`getContentType`	`(content?: Proto.IMessage) => keyof Proto.IMessage \| undefined`	Returns the populated content-type key (`'conversation'`, `'imageMessage'`, `'extendedTextMessage'`, …) of a message, or `undefined` for an empty message. Skips `senderKeyDistributionMessage` so group messages report their real payload kind.
`resolveMessageTarget`	`(ref: WaMessageTargetInput) => WaMessageKey`	Normalizes a reply/edit/reaction/revoke/pin target into a bare `WaMessageKey`. Accepts an explicit `WaMessageKey` (returned as-is) or a received `message` event (`rawNode`-bearing reference — its `key` is returned). Throws when an event is passed without a valid `key.id`.

import { getContentType, resolveMessageTarget } from 'zapo-js'

client.on('message', (event) => {
  console.log(getContentType(event.message)) // e.g. 'extendedTextMessage'
  const key = resolveMessageTarget(event)    // identical to event.key for real events
})

Other utilities

Export	Purpose
`proto`	The full protobuf namespace — build raw `Proto.IMessage` payloads.
`delay(ms)`	Promise-based sleep.
`parseUsyncResultEnvelope`	Parse a USync IQ result envelope.
`WA_VERSION`	The bundled default WhatsApp Web version string the client advertises when `version` is omitted.

Device identity helpers

Two low-level helpers reachable via the zapo-js/protocol subpath — useful when authoring a plugin that needs the same deviceBrowser / deviceOsDisplayName / devicePlatform resolution the client factory and auth client use, so its own payloads agree with the pairing ClientPayload.

Export	Signature	Description
`resolveWaDeviceIdentity`	`(options: WaDeviceIdentityOptions) => WaDeviceIdentity`	Resolves a fully-populated `{ browser, osDisplayName, platform }` from raw options, applying the same defaults the client uses (browser falls back to `WA_DEFAULTS.DEVICE_BROWSER`, OS name to the runtime OS, platform inferred from the browser).
`getWaBrowserDisplayName`	`(browser: string) => string`	The human-readable browser name advertised during pairing (e.g. `'chrome'` → `'Chrome'`). Unknown inputs are echoed back unchanged.

import { resolveWaDeviceIdentity, getWaBrowserDisplayName } from 'zapo-js/protocol'

const device = resolveWaDeviceIdentity({ deviceBrowser: 'firefox' })
// { browser: 'firefox', osDisplayName: '<runtime OS>', platform: '3' }
getWaBrowserDisplayName('firefox') // 'Firefox'

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

JIDs, helpers & constants

JID shapes

Building JIDs

Parsing & splitting

Classifying JIDs

Constants

Message helpers

Other utilities

Device identity helpers

​JID shapes

​Building JIDs

​Parsing & splitting

​Classifying JIDs

​Constants

​Message helpers

​Other utilities

​Device identity helpers

JID shapes

Building JIDs

Parsing & splitting

Classifying JIDs

Constants

Message helpers

Other utilities

Device identity helpers