DOCSEARCHbyAlgolia
Submit Docs

WPP4Delphi

repository·main·Indexed 42 days ago

https://github.com/wppconnect-team/wpp4delphi

A Delphi and Lazarus component that enables native WhatsApp automation by embedding a Chromium browser via CEF4Delphi and injecting WA-JS. It provides a high-level Object Pascal interface to WhatsApp Web, allowing developers to send and receive messages, manage groups, and handle media without requiring external paid APIs.

Tokens
4.6K
Snippets
4
Records
20
Agent score
53%

What's inside WPP4Delphi

  1. Overview of WPP4Delphi

    main

    WPP4Delphi is a Delphi/Lazarus component package (TWPPConnect) that exposes WhatsApp Web functionalities as a native API. It works by embedding a Chromium browser (via CEF4Delphi) that loads web.whatsapp.com and injects the wa-js library to execute commands.

    Key Capabilities:

    • Send and receive messages (text, media, interactive).
    • Manage chats, groups, and communities.
    • Handle polls, calls, and product catalogs.
    • Upload media and manage contacts.
    • Avoid the need for expensive external APIs by using the WhatsApp Web interface directly.

  2. What is WPP4Delphi?

    main
    WPP4Delphi is a Delphi/Lazarus (VCL/LCL) component that exposes WhatsApp Web as a native API. It works by embedding a Chromium browser via CEF4Delphi to load web.whatsapp.com and injecting WA-JS into it. The TWPPConnect component then calls WA-JS from Object Pascal, translating asynchronous responses into Delphi/Lazarus objects and events. This allows for WhatsApp automation without requiring a paid external API.

  3. Understand the WPP4Delphi Data Flow

    main

    The component operates through an asynchronous bridge between Delphi and the embedded Chromium browser:

    1. Command Initiation: A public method (e.g., TWPPConnect.SendTextMessage) is called. This method selects a JavaScript template from uTWPPConnect.Constant and sends it to the browser via TFrmConsole.ExecuteJS.
    2. JS Execution: The injected wa-js library executes the command on the WhatsApp Web page.
    3. Response Bridge: The result is returned from the browser process to Delphi via the CEF message bridge.
    4. Deserialization: TFrmConsole receives the JSON string, identifies the response type using a TTypeHeader, and instantiates the corresponding Delphi data class (from uTWPPConnect.Classes) using RTTI.
    5. Event Dispatch: The deserialized object is passed to the specific On* event handler subscribed to by your application.

  4. Understand WPP4Delphi limitations and requirements

    main

    Before integrating WPP4Delphi, be aware of the following:

    • Dependency on WhatsApp Web: This is not an official WhatsApp product. It relies on WA-JS working with WhatsApp Web, which is subject to changes by Meta.
    • Resource Usage: Because it embeds Chromium (via CEF4Delphi), the host application will have a significantly higher memory footprint and larger binary size compared to a pure HTTP API.
    • Session Model: Each instance of TWPPConnect or TFrmConsole supports exactly one session. To handle multiple WhatsApp sessions, you must create multiple instances of the component.
    • OS Compatibility: The embedded CEF binary is compatible with Windows 7, Windows 8, and Windows Server 2012 or newer.

  5. Access the latest JS files for WPP4Delphi

    main

    The latest JavaScript files required for use with the Delphiana community can be found in the Source/JS directory. For the most up-to-date content, you can also access the official documentation site or download the js.abr file directly from the GitHub repository.

    Official Documentation: https://wppconnect-team.github.io/

    Direct Download (js.abr): https://raw.githubusercontent.com/wppconnect-team/WPP4Delphi/main/Source/JS/js.abr

  6. Lazarus / Free Pascal Compatibility

    main

    The TWPP4DelphiCollection is compatible with Lazarus and FPC 3.2.2 using the Packages/twpp4delphicollection.lpk package. The project uses {$IFDEF FPC} branches to ensure the same source units work across both compilers.

    Key Compatibility Implementations:

    • JSON: Uses a custom RTTI engine in uTWPPConnect.JsonCompat.pas because FPC lacks REST.Json.
    • Threading: Uses native Free Pascal closures in uTWPPConnect.ThreadCompat.pas to replace Delphi's anonymous methods.
    • Data: Swaps TFDMemTable (FireDAC) for FPC's built-in TBufDataset.

    Required Lazarus Packages (Install in this order):

    1. dcpcrypt (or an equivalent DCPcrypt fork with an .lpk)
    2. indylaz (Indy for Lazarus)
    3. CEF4Delphi (build packages/cef4delphi_lazarus.lpk)
    4. Packages/twpp4delphicollection.lpk

    Build Command:

    lazbuild --build-ide= twpp4delphicollection.lpk

  8. Install WPP4Delphi in Delphi or Lazarus

    main

    WPP4Delphi is a Delphi/VCL package and cannot be installed via a CLI build tool. Follow these steps to integrate it into your IDE:

    1. Install CEF4Delphi: Perform the Build and Install of its .dpk.
    2. Configure Library Path: Add the following directories to your IDE's Library Path:
      • Source\Model
      • Source\Services
      • Source\View
      • Source\Other
      • Packages\Compilados\<Dxx> (where <Dxx> matches your Delphi version, e.g., VD23 for Delphi 12).
    3. Install the Package: Open Packages\TWPP4DelphiCollection.dpk, then perform Build (Shift+F9) and Install.
    4. Handle CEF Versions: If using CEF4Delphi version > 120, you must define the compilation directive CEFCurrentVersion before building.
    5. Setup Demo/Runtime: Compile the Demo project once, then copy ConfTWPPConnect.ini and the CEF binaries to your application's output folder.

    Lazarus Support: Use the alternative package located in Packages/Compilados/lazarus or the .lpk/.lpi project in the Packages root.

    Boss Installation: If using Boss, run:

    boss install github.com/wppconnect-team/WPP4Delphi

    Note: mainsrc is ./Source and the project is ./Packages/TWPP4DelphiCollection.dproj.

    boss install github.com/wppconnect-team/WPP4Delphi

  9. Install WPP4Delphi in Delphi (Step-by-Step)

    main

    To install the component in Delphi, follow these steps:

    1. Prepare Dependencies: Download and extract CEF4Delphi sources and the corresponding CEF Binaries (Version 109.0.5414.120 is recommended for Windows 7/8/Server 2012 compatibility).
    2. Configure Library Path (CEF4Delphi): In Delphi, go to Tools > Options > Library Path and add the ... extbackslash CEF4Delphi\source folder.
    3. Install CEF4Delphi: Open ... extbackslash CEF4Delphi\packages\CEF4Delphi.dpk in Delphi, perform a Build (Shift+F9), and then right-click the project in the Project Manager to select Install.
    4. Configure Library Path (WPP4Delphi): Add the following WPP4Delphi source folders to your Library Path:
      • ...\WPP4Delphi\Source\Model
      • ...\WPP4Delphi\Source\Services
      • ...\WPP4Delphi\Source\View
      • ...\WPP4Delphi\Packages\Compilados
      • ...\WPP4Delphi\Source\Other
      • Note: Inside Packages\Compilados, add the subfolder corresponding to your Delphi version (e.g., D27, D28).
    5. Install WPP4Delphi Component: Open ...\WPP4Delphi\Packages\TWPP4DelphiCollection.dpk, perform a Build (Shift+F9), and then Install.
    6. Runtime Setup:
      • Compile your application/demo.
      • Copy the ConfTWPPConnect.ini file from ...\WPP4Delphi\Demo\BIN to your application's executable folder.
      • Copy the extracted CEF Binaries to your application's executable folder.

  10. Configure TWPPConnect Properties

    main

    The TWPPConnect component provides several published properties for configuration:

    PropertyTypeDescription
    VersionStringComponent version (read-only)
    InjectJSTWPPConnectJSConfiguration for JS injection
    ConfigTWPPConnectConfigGeneral configuration (timeouts, crash monitor, etc.)
    AjustNumberTWPPConnectAdjusteNumberRules for phone number normalization
    FormQrCodeTypeTFormQrCodeTypeQR Code display style (default: Ft_Desktop)
    LanguageInjectTLanguageInjectInjected interface language (default: TL_Portugues_BR)

  11. Configure the `ConfTWPPConnect.ini` file

    main

    The ConfTWPPConnect.ini file is used for component persistence. It must reside in the same folder as your executable. On the first installation, manually copy the seed file from Demo\BIN\ConfTWPPConnect.ini to your output folder. The component will automatically read, complete, and rewrite keys during execution.

    [Path Defines] Section

    Use this section to configure CEF4Delphi paths and flags. If left blank, the component uses default paths relative to the executable.

    KeyTypeDescription
    FrameWorkstringPath to CEF4Delphi framework
    BinarystringPath to CEF binaries
    LocalesstringPath to CEF locales
    CachestringPath to Chromium cache
    Data UserstringPath to user profile
    Log FilestringPath to log file
    Log ConsolestringPath to JS console log (defaults to <exe_folder>\LogTWppConnect\)
    GPUboolEnable Chromium GPU acceleration (default: True)
    Log SeverityboolVerbose CEF logging (default: False)
    Log Console ActiveboolEnable/disable JS console logging (default: False)
    Auto Receiver attachedboolMirrors TWPPConnectConfig.ReceiveAttachmentAuto
    Auto Receiver attached PathstringMirrors TWPPConnectConfig.ReceiveAttachmentPath

    [Config] Section

    Use this section to enable or disable specific asynchronous events from WA-JS to reduce JS↔Delphi traffic. Set to 1 to enable, or leave blank to use the component's internal default. Setting it to 0 explicitly disables the event.

    KeyDescription
    Evento_msg_ack_changeMessage acknowledgement change
    Evento_msg_revokeMessage revocation
    Evento_new_messageNew message received
    Evento_new_reactionNew reaction
    Evento_active_chatActive chat change
    Evento_update_labelLabel update
    Evento_presence_changePresence change
    Evento_group_participant_changedGroup participant change
    Evento_live_location_startLive location start
    Evento_order_payment_statusOrder payment status
    SecondsMonitorPolling interval in seconds (blank uses default)
    SecondsMonitorNewPolling interval in seconds (blank uses default)