Struct BotBuilder 

pub struct BotBuilder<B = Missing, T = Missing, H = Missing, R = Missing> { /* private fields */ }

Builder for Bot using the typestate pattern.

The four type parameters (B, T, H, R) track whether the required fields (backend, transport_factory, http_client, runtime) have been provided. The build() method is only available when all four are Provided, turning missing-field errors into compile-time errors.

Implementations

impl<T, H, R> BotBuilder<Missing, T, H, R>

pub fn with_backend( self, backend: Arc<dyn Backend>, ) -> BotBuilder<Provided, T, H, R>

Use a backend implementation for storage. This is the only way to configure storage - there are no defaults.

Arguments

• backend - The backend implementation that provides all storage operations

Example

let backend = Arc::new(SqliteStore::new("whatsapp.db").await?);
let bot = Bot::builder()
    .with_backend(backend)
    .build()
    .await?;

impl<B, H, R> BotBuilder<B, Missing, H, R>

pub fn with_transport_factory<F>( self, factory: F, ) -> BotBuilder<B, Provided, H, R>

where F: TransportFactory + 'static,

Set the transport factory for creating network connections. This is required to build a bot.

Arguments

• factory - The transport factory implementation

Example

use whatsapp_rust_tokio_transport::TokioWebSocketTransportFactory;

let bot = Bot::builder()
    .with_backend(backend)
    .with_transport_factory(TokioWebSocketTransportFactory::new())
    .build()
    .await?;

impl<B, T, R> BotBuilder<B, T, Missing, R>

pub fn with_http_client<C>(self, client: C) -> BotBuilder<B, T, Provided, R>

where C: HttpClient + 'static,

Configure the HTTP client used for media operations and version fetching.

Arguments

• client - The HTTP client implementation

Example

use whatsapp_rust_ureq_http_client::UreqHttpClient;

let bot = Bot::builder()
    .with_backend(backend)
    .with_http_client(UreqHttpClient::new())
    .build()
    .await?;

impl<B, T, H> BotBuilder<B, T, H, Missing>

pub fn with_runtime<Rt: Runtime>( self, runtime: Rt, ) -> BotBuilder<B, T, H, Provided>

Set the async runtime implementation to use.

This is required to build a bot.

impl<B, T, H, R> BotBuilder<B, T, H, R>

pub fn on_event<F, Fut>(self, handler: F) -> Self

where F: Fn(Event, Arc<Client>) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

pub fn with_enc_handler<Eh>( self, enc_type: impl Into<String>, handler: Eh, ) -> Self

where Eh: EncHandler + 'static,

Register a custom handler for a specific encrypted message type

Arguments

• enc_type - The encrypted message type (e.g., “frskmsg”)
• handler - The handler implementation for this type

Returns

The updated BotBuilder

pub fn with_version(self, version: (u32, u32, u32)) -> Self

Override the WhatsApp version used by the client.

By default, the client will automatically fetch the latest version from WhatsApp’s servers. Use this method to force a specific version instead.

Arguments

• version - A tuple of (primary, secondary, tertiary) version numbers

Example

let bot = Bot::builder()
    .with_backend(backend)
    .with_version((2, 3000, 1027868167))
    .build()
    .await?;

pub fn with_device_props( self, os_name: Option<String>, version: Option<AppVersion>, platform_type: Option<PlatformType>, ) -> Self

Override the device properties sent to WhatsApp servers. This allows customizing how your device appears on the linked devices list.

Arguments

• os_name - Optional OS name (e.g., “macOS”, “Windows”, “Linux”)
• version - Optional app version as AppVersion struct
• platform_type - Optional platform type that determines the device name shown on the phone’s linked devices list (e.g., Chrome, Firefox, Safari, Desktop)

Important: The platform_type determines what device name is shown on the phone. Common values: Chrome, Firefox, Safari, Edge, Desktop, Ipad, etc. If not set, defaults to Unknown which shows as “Unknown device”.

You can pass None for any parameter to keep the default value.

Example

use waproto::whatsapp::device_props::{self, PlatformType};

// Show as "Chrome" on linked devices
let bot = Bot::builder()
    .with_backend(backend)
    .with_device_props(
        Some("macOS".to_string()),
        Some(device_props::AppVersion {
            primary: Some(2),
            secondary: Some(0),
            tertiary: Some(0),
            ..Default::default()
        }),
        Some(PlatformType::Chrome),
    )
    .build()
    .await?;

// Show as "Desktop" on linked devices
let bot = Bot::builder()
    .with_backend(backend)
    .with_device_props(None, None, Some(PlatformType::Desktop))
    .build()
    .await?;

pub fn with_pair_code(self, options: PairCodeOptions) -> Self

Configure pair code authentication to run automatically after connecting.

When set, the pair code request will be sent automatically after establishing a connection, and the pairing code will be dispatched via Event::PairingCode. This runs concurrently with QR code pairing - whichever completes first wins.

Arguments

• options - Configuration for pair code authentication

Example

use whatsapp_rust::pair_code::{PairCodeOptions, PlatformId};

let bot = Bot::builder()
    .with_backend(backend)
    .with_transport_factory(transport)
    .with_http_client(http_client)
    .with_pair_code(PairCodeOptions {
        phone_number: "15551234567".to_string(),
        show_push_notification: true,
        custom_code: Some("ABCD1234".to_string()),
        platform_id: PlatformId::Chrome,
        platform_display: "Chrome (Linux)".to_string(),
    })
    .on_event(|event, client| async move {
        match event {
            Event::PairingCode { code, timeout } => {
                println!("Enter this code on your phone: {}", code);
            }
            _ => {}
        }
    })
    .build()
    .await?;

pub fn skip_history_sync(self) -> Self

Skip processing of history sync notifications from the phone.

When enabled, the client will acknowledge all incoming history sync notifications (so the phone considers them delivered) but will not download or process any historical data (INITIAL_BOOTSTRAP, RECENT, FULL, PUSH_NAME, etc.). A debug log entry is emitted for each skipped notification. This is useful for bot use cases where message history is not needed.

Default: false (history sync is processed normally).

Example

let bot = Bot::builder()
    .with_backend(backend)
    .with_transport_factory(transport)
    .with_http_client(http_client)
    .skip_history_sync()
    .build()
    .await?;

pub fn with_push_name(self, name: impl Into<String>) -> Self

Set an initial push name on the device before connecting.

This is included in the ClientPayload during registration, allowing the mock server to deterministically assign phone numbers based on push name (same push name = same phone, enabling multi-device testing).

pub fn with_cache_config(self, config: CacheConfig) -> Self

Configure cache TTL and capacity settings.

By default, all caches match WhatsApp Web behavior. Use this method to customize cache durations for your use case.

Example

use whatsapp_rust::{CacheConfig, CacheEntryConfig};

// Disable TTL for group and device caches (good for bots with few groups)
let bot = Bot::builder()
    .with_backend(backend)
    .with_transport_factory(transport)
    .with_http_client(http_client)
    .with_cache_config(CacheConfig {
        group_cache: CacheEntryConfig::new(None, 1_000),
        device_cache: CacheEntryConfig::new(None, 5_000),
        ..Default::default()
    })
    .build()
    .await?;

impl BotBuilder<Provided, Provided, Provided, Provided>

pub async fn build(self) -> Result<Bot, BotBuilderError>