Protobuf Definitions (WAProto)

The WAProto module is a core component of the project responsible for defining and handling the Protocol Buffer (Protobuf) structures used by WhatsApp for binary communication. It encompasses the schemas for messages, metadata, handshakes, and client-server synchronization logic.

This module provides a structured way to encode and decode data payloads, ensuring compatibility with different versions of the WhatsApp Web client. It includes automated scripts to fetch the latest definitions directly from WhatsApp's source code and compile them into static JavaScript modules for use throughout the library.

Architecture and Generation Flow

The project employs an automated pipeline to keep Protobuf definitions up to date with WhatsApp's frequent revisions. This process involves scraping WhatsApp Web's service worker, extracting internal specifications, and generating both .proto files and static JavaScript code.

Automated Update Pipeline

1. Extraction: The system fetches sw.js from https://web.whatsapp.com to identify the current client revision. It then retrieves the main application script (bootstrap URL) to find modules containing internalSpec declarations.
2. Parsing: Using the acorn library, the scripts parse the JavaScript source and walk the AST to extract message and enum specifications.
3. Synthesis: These specifications are stringified into .proto syntax, complete with package names and necessary imports.
4. Compilation: The generate-proto.js script cleans the generated files and uses the pbjs compiler to produce static JavaScript modules.

The diagram above illustrates the automated transformation of WhatsApp Web's internal JavaScript specifications into library-compatible Protobuf modules.
Sources: scripts/index.js:77-133, scripts/generate-proto.js:43-73

Core Data Structures

The Protobuf definitions are categorized into several functional packages, each handling specific aspects of the protocol.

Bot and Rich Message Metadata

The BotMetadata package defines structures for AI-initiated conversations, progress indicators, and rich response components like tables and LaTeX.

Sources: WAProto/BotMetadata/BotMetadata.proto:7-50, WAProto/BotMetadata/BotMetadata.proto:145-200

Wa6 Handshake and Payload

The Wa6 package is critical for the initial connection and session establishment.

This class diagram highlights the relationship between connection payloads and agent details required for authentication.
Sources: WAProto/Wa6/Wa6.proto:4-20, WAProto/Wa6/Wa6.js:134-180

Message Composition Utility Integration

Utilities in the library consume these definitions to build valid message objects. The message-composer.js and rich-message-utils.js files map high-level user data to specific Protobuf sub-messages.

Rich Sub-Message Types

The library uses an internal enumeration to handle various rich content types that correspond to the Protobuf definitions in AIRichResponseMessage.

• TEXT (2): Standard markdown text sections.
• IMAGE (3): Inline images with alignment metadata.
• TABLE (4): Structured data grids with optional headers.
• CODE (5): Syntax-highlighted code blocks.
• LATEX (8): Mathematical expressions.

Sources: lib/Utils/message-composer.js:68-80, lib/Utils/rich-message-utils.js:52-100

Message Generation Logic

Functions like prepareRichResponseMessage wrap these sub-messages into the standard botForwardedMessage structure required by the protocol.

const richResponseMessage = WAProto.proto.AIRichResponseMessage.create({
    submessages,
    messageType: WAProto.proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
    unifiedResponse: {
        data: Buffer.from(JSON.stringify(unified))
    },
    contextInfo: {
        isForwarded: true,
        forwardingScore: 1,
        forwardedAiBotMessageInfo: { botJid: '867051314767696@bot' },
        forwardOrigin: 4
    }
})

Sources: lib/Utils/rich-message-utils.js:317-331

System Module Aggregation

The index.d.ts file serves as the unified entry point for all Protobuf namespaces, exporting them under a single proto object.

The aggregation structure allows the rest of the codebase to access any Protobuf type via proto.[Namespace].[Type].
Sources: WAProto/index.d.ts:28-56

Conclusion

The WAProto module provides a robust, automated infrastructure for maintaining WhatsApp Protobuf definitions. By combining AST-based extraction from client source code with a standard Protobuf compilation pipeline, it ensures the library can accurately encode and decode complex data structures ranging from basic chat messages to sophisticated AI-driven rich responses and secure handshakes. These definitions form the underlying language for all binary communication within the project.