@raphaelvserafim/whatsapp-binary

WhatsApp Binary XML Protocol — encoder, decoder, and protocol constants.

This library handles the transport layer of the WhatsApp Web protocol: the proprietary binary XML (XMPP) encoding used to communicate over WebSocket.

Install

npm install @raphaelvserafim/whatsapp-binary

What's inside

Encoder / Decoder

Encode and decode WhatsApp's proprietary binary XML nodes.

import { encodeBinaryNode, decodeBinaryNode } from '@raphaelvserafim/whatsapp-binary'

// Encode a node to binary
const binary = encodeBinaryNode({
  tag: 'message',
  attrs: { to: '[email protected]', type: 'text' },
  content: [{ tag: 'body', attrs: {}, content: 'Hello' }],
})

// Decode binary back to node
const node = decodeBinaryNode(binary)

Protocol Constants

All values from the WhatsApp XMPP transport layer, typed and documented.

import {
  ReceiptType,
  PresenceType,
  DisconnectReason,
  EncryptionType,
  ParticipantAction,
  StanzaType,
  NackReason,
  NotificationType,
  JidSuffix,
} from '@raphaelvserafim/whatsapp-binary'

ReceiptType.READ         // 'read'
ReceiptType.READ_SELF    // 'read-self'
ReceiptType.PLAYED       // 'played'

PresenceType.COMPOSING   // 'composing'
PresenceType.RECORDING   // 'recording'

EncryptionType.SKMSG     // 'skmsg' (sender key / group)
EncryptionType.PKMSG     // 'pkmsg' (pre-key / first message)

DisconnectReason.LOGGED_OUT          // 401
DisconnectReason.CONNECTION_REPLACED // 440

ParticipantAction.ADD     // 'add'
ParticipantAction.PROMOTE // 'promote'

JidSuffix.PHONE       // '@s.whatsapp.net'
JidSuffix.LID         // '@lid'
JidSuffix.GROUP       // '@g.us'
JidSuffix.NEWSLETTER  // '@newsletter'

JID Utilities

Parse, encode, and inspect WhatsApp JIDs.

import { jidDecode, jidEncode, jidNormalizedUser, isJidGroup, isLidUser } from '@raphaelvserafim/whatsapp-binary'

jidDecode('5511999999999:[email protected]')
// { user: '5511999999999', device: 2, server: 's.whatsapp.net' }

jidEncode('5511999999999', 's.whatsapp.net', 2)
// '5511999999999:[email protected]'

isJidGroup('[email protected]')  // true
isLidUser('12345:0@lid')         // true

Node Utilities

Traverse and extract data from binary nodes.

import { getBinaryNodeChild, getBinaryNodeChildren, getAllBinaryNodeChildren } from '@raphaelvserafim/whatsapp-binary'

const child = getBinaryNodeChild(node, 'enc')
const children = getBinaryNodeChildren(node, 'participant')

Architecture

WhatsApp Web uses two protocol layers:

| Layer | Package | What it does | |-------|---------|-------------| | Data | @raphaelvserafim/whatsapp-proto | Protobuf schemas — message structure, enums, status codes | | Transport | @raphaelvserafim/whatsapp-binary (this) | Binary XML — encoding, decoding, XMPP protocol constants |

Values that exist in the protobuf schema (message status, call outcomes, event responses) live in whatsapp-proto. Values that are XMPP transport attributes (receipt types, presence, disconnect reasons) live here.

Reference

Receipt Types

| Constant | Value | Description | |----------|-------|-------------| | READ | 'read' | Message read (blue ticks enabled) | | READ_SELF | 'read-self' | Message read (blue ticks disabled) | | PLAYED | 'played' | Audio/video was played | | SENDER | 'sender' | Sent by us from another device | | PEER_MSG | 'peer_msg' | Peer-to-peer protocol message | | HIST_SYNC | 'hist_sync' | History sync acknowledgment | | INACTIVE | 'inactive' | Not marking as online |

Encryption Types

| Constant | Value | Description | |----------|-------|-------------| | SKMSG | 'skmsg' | Sender key message (group) | | PKMSG | 'pkmsg' | Pre-key message (key exchange) | | MSG | 'msg' | Normal encrypted message | | PLAINTEXT | 'plaintext' | Unencrypted |

Disconnect Reasons

| Constant | Value | Description | |----------|-------|-------------| | CONNECTION_CLOSED | 428 | Normal close | | CONNECTION_LOST | 408 | Timeout | | CONNECTION_REPLACED | 440 | Another device connected | | LOGGED_OUT | 401 | User logged out | | BAD_SESSION | 500 | Server error | | RESTART_REQUIRED | 515 | Server restart | | MULTIDEVICE_MISMATCH | 411 | Device mismatch |

NACK Reason Codes

| Constant | Value | Description | |----------|-------|-------------| | PARSING_ERROR | 487 | Failed to parse message | | UNRECOGNIZED_STANZA | 488 | Unknown stanza | | INVALID_PROTOBUF | 491 | Malformed protobuf | | MISSING_MESSAGE_SECRET | 495 | Missing encryption secret | | SIGNAL_ERROR_OLD_COUNTER | 496 | Replay attack detected | | MESSAGE_DELETED_ON_PEER | 499 | Message no longer exists | | UNHANDLED_ERROR | 500 | Server error |

License

MIT