WhatsApp (Multi-Device) Integration
Relevant source files
The following files were used as context for generating this wiki page:
The WhatsApp (Multi-Device) integration provides a modern bridge for WhatsApp within the Matterbridge ecosystem. Unlike the legacy implementation, this module utilizes the whatsmeow library to interact with the WhatsApp Multi-Device (MD) API, allowing the bridge to operate as a linked device without requiring a constant active connection from the primary mobile phone.
This integration is built as an optional module within Matterbridge. Due to licensing constraints involving GPL3 dependencies in the underlying whatsmeow library, users must build the binary themselves using the whatsappmulti build tag.
Sources: README.md:195-200, vendor/go.mau.fi/whatsmeow/README.md:1-5
Architecture and Core Components
The integration is centered around the Bwhatsapp struct, which encapsulates the connection state, user mappings, and group information. It acts as a wrapper for the whatsmeow.Client, handling authentication via QR codes and managing the mapping between WhatsApp-specific Protocol Buffers and Matterbridge's internal message structures.
Core Data Structures
| Structure | Description |
|---|---|
Bwhatsapp | The primary bridge instance containing the whatsmeow.Client, user avatars, and joined group information. |
whatsmeow.Client | The underlying client that handles the WebSocket connection and WhatsApp protocol logic. |
proto.Message | The Protocol Buffer definition for WhatsApp messages, encompassing text, media, and context information. |
config.Message | The internal Matterbridge message structure used to relay data between different chat protocols. |
Sources: bridge/whatsappmulti/whatsapp.go:37-52, vendor/go.mau.fi/whatsmeow/binary/proto/def.proto:492-545
Connection Flow
The connection process involves initializing a device store (typically SQLite), generating a QR code for initial pairing, and establishing a persistent WebSocket connection.
Message Handling Logic
Message handling is divided into incoming events (from WhatsApp to other bridges) and outgoing messages (from other bridges to WhatsApp).
Incoming Messages (WhatsApp -> Bridge)
The eventHandler processes various WhatsApp events including standard messages and group updates. Text messages, images, videos, audio, and documents are parsed from the proto.Message format into the config.Message format.
- Text Messages: Handles both simple
Conversationfields andExtendedTextMessagewhich may include link previews or mentions. - Mentions: Automatically replaces phone-number based mentions with meaningful notify names to protect user privacy when bridging to other protocols.
- Media Handling: Media is downloaded via
b.wc.Download, and then processed using Matterbridge's internal helper functions for storage or relay.
Sources: bridge/whatsappmulti/handlers.go:21-40, bridge/whatsappmulti/handlers.go:102-140
Outgoing Messages (Bridge -> WhatsApp)
When Matterbridge sends a message to WhatsApp, it identifies the message type based on the presence of file attachments or specific events.
Configuration and Building
The WhatsApp Multi-Device bridge requires specific configuration parameters and a custom build process.
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
Number | String | The phone number associated with the account. |
EditSuffix | String | Optional suffix added to edited messages (default: " (edited)"). |
Sources: bridge/whatsappmulti/whatsapp.go:32-34, bridge/whatsappmulti/whatsapp.go:300-305
Building with Support
Due to the GPL3 license of the underlying libraries, pre-built binaries do not include this integration. It must be built manually:
go install -tags whatsappmulti github.com/42wim/matterbridge@master
Sources: README.md:200-210
User and Contact Management
The integration maintains a local cache of contacts and avatars to facilitate faster message rendering and identity resolution. It uses the usync protocol to fetch user information such as statuses and profile picture URLs.
- Avatar Retrieval: Avatars are fetched asynchronously during connection using
GetProfilePicThumb. - Identity Resolution: The bridge resolves JIDs (Jabber IDs) into sender names. It attempts to use notify names from the contact list to avoid exposing raw phone numbers.
Sources: bridge/whatsappmulti/whatsapp.go:132-156, vendor/go.mau.fi/whatsmeow/user.go:214-250
Summary
The WhatsApp (Multi-Device) integration allows Matterbridge to function as a modern WhatsApp client. By leveraging the whatsmeow library and the Multi-Device API, it ensures stable bridging without requiring the primary mobile device to be online. It handles complex message types including media and threaded replies, while providing privacy protections through mention sanitization.
Sources: bridge/whatsappmulti/whatsapp.go:331-338, vendor/go.mau.fi/whatsmeow/README.md:15-30