Quickstart

This guide will help you create a simple WhatsApp bot that responds to messages. You’ll learn the core concepts and have a working bot by the end.

Basic example

Add the dependencies — one crate is enough; whatsapp-rust re-exports the entire stack:

Cargo.toml

[dependencies]
whatsapp-rust = "0.6"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Here’s a minimal bot that responds to “ping” messages:

src/main.rs

use whatsapp_rust::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bot = Bot::builder()
        .with_backend(SqliteStore::new("whatsapp.db").await?)
        .on_qr_code(|code, _timeout| async move {
            println!("Scan this QR code with WhatsApp:\n{code}");
        })
        .on_message(|ctx| async move {
            if ctx.message.text_content() == Some("ping") {
                if let Err(e) = ctx.reply("pong").await {
                    eprintln!("Failed to reply: {e}");
                }
            }
        })
        .build()
        .await?;

    // Runs until logout or client.disconnect() from another task.
    bot.run().await;
    Ok(())
}

Step-by-step breakdown

Set up the storage backend

The bot needs persistent storage for session data, keys, and state:

let backend = SqliteStore::new("whatsapp.db").await?;

This creates a SQLite database file named whatsapp.db in your current directory. The session will persist across restarts.

Configure the bot builder

The Bot::builder() pattern lets you configure all components:

let bot = Bot::builder()
    .with_backend(backend)

With the default cargo features, only the backend is required. The Tokio WebSocket transport, ureq HTTP client, and Tokio runtime are pre-wired. Use with_transport_factory, with_http_client, and with_runtime to override any of them (for example when targeting WASM or a custom transport).

Typed registrars cover the common cases — no match &*event needed:

.on_qr_code(|code, _timeout| async move {
    println!("QR Code:\n{code}");
})
.on_message(|ctx| async move {
    // ctx.message, ctx.info, ctx.reply(...), ctx.react(...)
    println!("From {}: {:?}", ctx.info.source.sender, ctx.message.text_content());
})
.on_connected(|_client| async {
    println!("Connected successfully!");
})

Available typed registrars: on_message, on_qr_code, on_pair_code, on_connected, on_logged_out. Use on_event or on_event_for as catch-alls for events without a typed registrar. Multiple handlers of any kind accumulate — registering a second one no longer silently replaces the first.on_message delivers a ready MessageContext with ctx.reply(text), ctx.reply_quoting(text), ctx.react(emoji), and ctx.send_message(msg) helpers.

Build and run the bot

Build the bot and start the event loop:

.build()
.await?;

bot.run().await;

bot.run().await runs the bot on the current task until it disconnects or logs out. To run in the background instead, use bot.spawn(), which returns a BotHandle with client(), shutdown(), and abort().

Responding to messages

Let’s extend the bot to respond to “ping” with “pong” using the on_message helper and ctx.reply:

use whatsapp_rust::prelude::*;

.on_qr_code(|code, _timeout| async move {
    println!("QR Code:\n{code}");
})
.on_message(|ctx| async move {
    if ctx.message.text_content() == Some("ping") {
        if let Err(e) = ctx.reply("pong").await {
            eprintln!("Failed to send reply: {e}");
        }
    }
})

Key methods

msg.text_content() — Extract text from any message type (conversation, extended text, etc.)
ctx.reply(text) — Send a plain-text reply in the same chat without quoting
ctx.reply_quoting(text) — Send a plain-text reply that quotes the received message
ctx.react(emoji) — React to the received message
ctx.send_message(msg) — Send an arbitrary wa::Message to the source chat
client.send_text(jid, text) — Send a plain-text message from a Client reference
info.source.chat — The JID (identifier) of the chat where the message came from
info.source.sender — The JID of the user who sent the message

For raw protobuf access (advanced cases), build a wa::Message directly:

use whatsapp_rust::prelude::*;

.on_message(|ctx| async move {
    if ctx.message.text_content() == Some("ping") {
        let reply = wa::Message {
            conversation: Some("pong".to_string()),
            ..Default::default()
        };
        if let Err(e) = ctx.send_message(reply).await {
            eprintln!("Failed to send reply: {e}");
        }
    }
})

Or with the MessageBuilderExt helpers:

use whatsapp_rust::prelude::*; // re-exports MessageBuilderExt

let msg = wa::Message::text("pong");
let msg_with_quote = wa::Message::text_with_context("pong", ctx.build_quote_context());

Authentication methods

QR code pairing (default)

The bot automatically generates QR codes when not authenticated. Display them with on_qr_code:

.on_qr_code(|code, timeout| async move {
    println!("Scan this QR code (valid {}s):\n{code}", timeout.as_secs());
})

Pair code (phone number)

Alternatively, link using a phone number and 8-digit code:

use whatsapp_rust::prelude::*;
use whatsapp_rust::pair_code::PairCodeOptions;

let bot = Bot::builder()
    .with_backend(SqliteStore::new("whatsapp.db").await?)
    .with_pair_code(PairCodeOptions {
        phone_number: "15551234567".to_string(),
        ..Default::default()
    })
    .on_pair_code(|code, _timeout| async move {
        println!("Enter this code on your phone: {code}");
    })
    .build()
    .await?;

PairCodeOptions derives companion_platform_id and companion_platform_display from the device’s PlatformType by default (Chrome with Chrome (Linux) for the stock web profile). You can override the wire id when needed:

use whatsapp_rust::pair_code::PairCodeOptions;
use wacore::companion_reg::CompanionWebClientType;

PairCodeOptions {
    phone_number: "15551234567".to_string(),
    show_push_notification: true,
    custom_code: Some("ABCD1234".to_string()), // or None for random
    // `None` auto-derives from `Device.device_props.platform_type`.
    platform_id: Some(CompanionWebClientType::Chrome),
}

platform_id accepts the CompanionWebClientType wire enum (single-byte ASCII ids). The display string is always derived — there is no separate platform_display field.

Pair code and QR code authentication run concurrently. Whichever method completes first will be used.

Running the bot

First run - Authentication

On the first run, the bot will generate a QR code:

cargo run

Scan the QR code with WhatsApp on your phone:

Open WhatsApp on your phone
Go to Settings → Linked Devices
Tap “Link a Device”
Scan the QR code displayed in your terminal

Subsequent runs - Auto-login

After pairing, the session is saved. The bot will automatically reconnect:

cargo run

You should see:

Connected successfully!

Test the bot

Send “ping” to your bot from any WhatsApp chat. It should reply with “pong”!

Demo binary CLI flags

The repository includes a demo bot example (examples/demo.rs) that supports CLI arguments for authentication:

cargo run --example demo                                      # QR code pairing only
cargo run --example demo -- --phone 15551234567               # Pair code + QR code (concurrent)
cargo run --example demo -- -p 15551234567                    # Short form
cargo run --example demo -- -p 15551234567 --code MYCODE12    # Custom 8-char pair code
cargo run --example demo -- -p 15551234567 -c MYCODE12        # Short form

The demo bot responds to 🦀ping with a quoted 🏓 Pong! reply, edits the reply to append the send latency, and supports media ping/pong via CDN reuse.

Using MessageContext

on_message delivers a ready MessageContext, so you no longer need to extract it from Arc<Event> manually. Use typed handler functions for cleaner separation:

use whatsapp_rust::prelude::*;

.on_message(|ctx| async move {
    handle_message(ctx).await;
})

Then define focused handler functions:

async fn handle_message(ctx: MessageContext) {
    if ctx.message.text_content() == Some("ping") {
        if let Err(e) = ctx.reply("pong").await {
            eprintln!("Failed to send: {e}");
        }
    }
}

MessageContext provides convenience methods including send_message (auto-targets the source chat), reply, reply_quoting, react, build_quote_context, edit_message, and revoke_message.

Media forwarding with CDN reuse

You can also forward media instantly by reusing the original CDN fields — no download or re-upload needed:

Constructing a message with a sub-message field (like image_message below) requires MessageField. whatsapp-rust re-exports it directly from prelude, so use whatsapp_rust::prelude::* is enough — no extra Cargo.toml entry needed. See Installation.

/// Reuses the original CDN blob, only swaps the caption.
/// Instant regardless of file size.
fn build_media_reply(message: &wa::Message) -> Option<wa::Message> {
    let base = message.get_base_message();
    if let Some(img) = base.image_message.as_option() {
        return Some(wa::Message {
            image_message: MessageField::some(wa::message::ImageMessage {
                caption: Some("Received your image!".to_string()),
                ..img.clone()
            }),
            ..Default::default()
        });
    }
    None
}

See the media forwarding guide for more details.

Background operation and graceful shutdown

Use spawn() to run the bot in the background while your code continues, and shutdown() for a clean stop:

use whatsapp_rust::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bot = Bot::builder()
        .with_backend(SqliteStore::new("whatsapp.db").await?)
        .on_message(|ctx| async move {
            let _ = ctx.reply("hello").await;
        })
        .build()
        .await?;

    let handle = bot.spawn(); // bot runs in the background; client is available via handle.client()

    whatsapp_rust::shutdown_signal().await;
    handle.shutdown().await; // graceful: flushes pending state, then stops
    Ok(())
}

BotHandle also exposes abort() as an escape hatch (skips the flush). Awaiting the handle resolves to () once the run loop exits.

Prefer shutdown_signal() over a bare tokio::signal::ctrl_c(): it resolves on SIGTERM as well as SIGINT. Supervisors like docker stop, Kubernetes, and systemd stop a process with SIGTERM first — a Ctrl+C-only wait never sees it, so cleanup is skipped and the process is hard-killed once the stop grace period elapses. Requires the signal feature, on by default.

Complete example with logging

Here’s a production-ready example with proper logging, reactions, message editing, and media CDN reuse:

src/main.rs

use log::{error, info};
use whatsapp_rust::prelude::*;
use whatsapp_rust::pair_code::PairCodeOptions;

const PING_TRIGGER: &str = "🦀ping";
const PONG_TEXT: &str = "🏓 Pong!";
const REACTION_EMOJI: &str = "🏓";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info"))
        .format(|buf, record| {
            use std::io::Write;
            writeln!(
                buf,
                "{} [{:<5}] [{}] - {}",
                wacore::time::now_utc().format("%H:%M:%S"),
                record.level(),
                record.target(),
                record.args()
            )
        })
        .init();

    let store = SqliteStore::new("whatsapp.db").await?;
    info!("SQLite backend initialized");

    let bot = Bot::builder()
        .with_backend(store)
        .on_qr_code(|code, _timeout| async move {
            println!("\n{code}\n");
        })
        .on_connected(|_client| async {
            info!("Bot connected!");
        })
        .on_logged_out(|_info| async {
            error!("Bot was logged out!");
        })
        .on_message(|ctx| async move {
            handle_message(ctx).await;
        })
        .build()
        .await?;

    info!("Starting bot...");
    bot.run().await;
    Ok(())
}

async fn handle_message(ctx: MessageContext) {
    // Try CDN-reuse media reply first (instant, no download needed)
    if let Some(reply) = build_media_pong(&ctx.message) {
        if let Err(e) = ctx.send_message(reply).await {
            error!("Failed to send media pong: {e}");
        }
        return;
    }

    if ctx.message.text_content() == Some(PING_TRIGGER) {
        if let Err(e) = ctx.react(REACTION_EMOJI).await {
            error!("Failed to send reaction: {e}");
        }
        if let Err(e) = ctx.reply_quoting(PONG_TEXT).await {
            error!("Failed to send pong: {e}");
        }
    }
}

/// Reuses the original CDN blob, only swaps the caption.
/// Instant regardless of file size — no download or re-upload.
fn build_media_pong(message: &wa::Message) -> Option<wa::Message> {
    let base = message.get_base_message();
    if let Some(img) = base.image_message.as_option()
        && img.caption.as_deref() == Some(PING_TRIGGER)
    {
        return Some(wa::Message {
            image_message: MessageField::some(wa::message::ImageMessage {
                caption: Some(PONG_TEXT.to_string()),
                ..img.clone()
            }),
            ..Default::default()
        });
    }
    if let Some(vid) = base.video_message.as_option()
        && vid.caption.as_deref() == Some(PING_TRIGGER)
    {
        return Some(wa::Message {
            video_message: MessageField::some(wa::message::VideoMessage {
                caption: Some(PONG_TEXT.to_string()),
                ..vid.clone()
            }),
            ..Default::default()
        });
    }
    None
}

Configuring log targets

whatsapp-rust uses the log crate with module-specific targets for fine-grained filtering. You can use RUST_LOG to control which components emit log output.

Available log targets

Target	Description
`Client/Keepalive`	Keepalive ping/pong and dead socket detection
`Client/Recv`	Incoming frame processing (unmarshal, decompress)
`Client/Send`	Outgoing message encryption and dispatch
`Client/OfflineSync`	Offline message sync progress and timing
`Client/AppState`	App state sync (contacts, settings, etc.)
`Client/AccountSync`	Account-level sync operations
`Client/PairCode`	Pair code authentication flow
`Client/Pair`	QR code pairing flow
`Client/Receipt`	Receipt processing (read, delivered, played)
`Client/TcToken`	Trusted contact token operations
`Client/Group`	Group metadata and participant operations
`Client/Contacts`	Contact sync and lookup
`Client/Business`	Business profile updates
`Client/PDO`	Peer Data Operations — message recovery from primary phone via bare-JID peer messaging and retry fallback
`Client/IQ`	IQ stanza send/receive
`Client/Ack`	Stanza acknowledgment
`Client/Status`	Status/story operations
`Client/Picture`	Profile picture updates
`Client/UnifiedSession`	Session establishment
`Blocking`	Block/unblock operations
`Chatstate`	Typing indicator events
`PresenceHandler`	Presence update processing
`AppState`	App state patch encoding/decoding
`Bot/PairCode`	Bot-level pair code handling

Filtering examples

# Show only connection and messaging logs
RUST_LOG="Client/Keepalive=debug,Client/Send=debug,Client/Recv=trace" cargo run

# Debug offline sync issues
RUST_LOG="Client/OfflineSync=debug" cargo run

# Quiet mode: only errors and warnings
RUST_LOG="warn" cargo run

# Verbose: all client internals at debug level
RUST_LOG="debug" cargo run

During shutdown or disconnect, the client automatically downgrades sync errors from error to debug level to reduce noise. This means you won’t see spurious error logs when the client is intentionally disconnecting.

Running with Docker

You can also run the bot using Docker instead of compiling locally:

docker build -t whatsapp-rust .
docker run -v ./data:/data whatsapp-rust

Session data is stored in the /data directory inside the container. Mount a volume to persist it across restarts. The container shuts down gracefully on docker stop — the bot disconnects cleanly from WhatsApp before exiting. See the installation guide for more details.

Benchmarking

The repository includes a benchmark example at examples/benchmark.rs that you can use for quick integration-level performance testing. It uses an in-memory backend and supports a custom WebSocket URL via the WHATSAPP_WS_URL environment variable:

cargo run --example benchmark --features danger-skip-tls-verify

The benchmark example requires the danger-skip-tls-verify feature flag because it’s designed for use with local test servers.

For more comprehensive integration benchmarks with allocation tracking, the bench-integration test suite measures real-world scenarios (connect, send, receive, reconnect) and reports wall-clock time plus heap allocation counts per operation:

# Requires a mock server (e.g., Bartender)
MOCK_SERVER_URL="wss://127.0.0.1:8080/ws/chat" \
  cargo run -p bench-integration --release

For low-level protocol benchmarks, the wacore crate includes an iai-callgrind benchmark suite that measures instruction counts for the full send/receive pipeline (DM and group messaging with various participant counts), binary protocol encoding, Signal Protocol operations, and reporting token generation:

# Run all wacore benchmarks (requires valgrind and iai-callgrind-runner)
cargo bench --workspace

See the wacore benchmarks documentation for details on each suite, allocation optimizations, and CI integration.

Next steps

Sending messages

Learn about different message types and how to send them

Media handling

Upload and download images, videos, and documents

Group management

Create and manage WhatsApp groups

Client API reference

Explore all available client methods

Getting Started

Core Concepts

Guides

Advanced

Basic example

Step-by-step breakdown

Responding to messages

Key methods

Authentication methods

QR code pairing (default)

Pair code (phone number)

Running the bot

Demo binary CLI flags

Using MessageContext

Media forwarding with CDN reuse

Background operation and graceful shutdown

Complete example with logging

Configuring log targets

Available log targets

Filtering examples

Running with Docker

Benchmarking

Next steps

Sending messages

Media handling

Group management

Client API reference

​Basic example

​Step-by-step breakdown

​Responding to messages

​Key methods

​Authentication methods

​QR code pairing (default)

​Pair code (phone number)

​Running the bot

​Demo binary CLI flags

​Using MessageContext

​Media forwarding with CDN reuse

​Background operation and graceful shutdown

​Complete example with logging

​Configuring log targets

​Available log targets

​Filtering examples

​Running with Docker

​Benchmarking

​Next steps

Sending messages

Media handling

Group management

Client API reference

Basic example

Step-by-step breakdown

Responding to messages

Key methods

Authentication methods

QR code pairing (default)

Pair code (phone number)

Running the bot

Demo binary CLI flags

Using MessageContext

Media forwarding with CDN reuse

Background operation and graceful shutdown

Complete example with logging

Configuring log targets

Available log targets

Filtering examples

Running with Docker

Benchmarking

Next steps