Client struct is the core of whatsapp-rust, managing connections, encryption, state, and all protocol-level operations.
Overview
The Client handles:- WebSocket connection lifecycle and automatic reconnection
- Noise Protocol handshake and encryption
- Signal Protocol E2E encryption for messages
- App state synchronization
- Device state persistence
- Event dispatching
Most users should use the
Bot builder instead of creating a Client directly. The Bot provides a simplified API with sensible defaults.Creating a Client
State manager for device credentials, sessions, and app state
Factory for creating WebSocket connections
HTTP client for media operations and version fetching
Optional WhatsApp version override (primary, secondary, tertiary)
Returns the client Arc and a receiver for history/app state sync tasks
Connection Management
run
disconnect()is called- Auto-reconnect is disabled and connection fails
- Client receives a logout/removal event (516 stream error)
connect
ClientError::AlreadyConnected- Already connected- Connection/handshake failures
disconnect
wait_for_socket
Maximum time to wait
Ok if socket ready, Err on timeout
wait_for_connected
Connection State
is_connected
true if the Noise socket is established.
is_logged_in
true if authenticated with WhatsApp servers.
Auto-Reconnection
The client includes automatic reconnection handling with exponential backoff.How it works
- On disconnect: The client detects unexpected disconnections and automatically attempts to reconnect
- Backoff delay: Each failed attempt increases the delay (2s, 4s, 6s… up to 30s max)
- Expected disconnects: Protocol-expected disconnects (e.g., 515 stream error after pairing) trigger immediate reconnection without backoff
- Keepalive monitoring: A keepalive loop sends periodic pings (every 20-30s) and forces reconnection if no response is received for 180 seconds
Controlling auto-reconnect
Reconnection behavior
| Scenario | Behavior |
|---|---|
| Unexpected disconnect | Reconnect with exponential backoff |
| 515 stream error (after pairing) | Immediate reconnect |
| Keepalive timeout (180s) | Force disconnect and reconnect |
disconnect() called | No reconnect attempt |
| Auto-reconnect disabled | No reconnect attempt |
Messaging
send_message
Recipient JID (user@s.whatsapp.net or group@g.us)
Protobuf message content
Message ID on success
send_message_with_options
Configuration for message sending behavior
src/send.rs:SendOptions for available options.
edit_message
ID of the message to edit
New message content
revoke_message
RevokeType::Everyone or RevokeType::MeFeature APIs
The Client provides namespaced access to feature-specific operations:blocking
block(jid: &Jid)- Block a contactunblock(jid: &Jid)- Unblock a contactget_blocklist()- Get all blocked contactsis_blocked(jid: &Jid)- Check if contact is blocked
groups
query_info(jid: &Jid)- Get cached group infoget_metadata(jid: &Jid)- Fetch group metadata from serverget_participating()- List all groups you’re increate_group(options: GroupCreateOptions)- Create a new groupset_subject(jid: &Jid, subject: GroupSubject)- Change group nameset_description(jid: &Jid, desc: Option<GroupDescription>, prev: Option<String>)- Change descriptionleave(jid: &Jid)- Leave a groupadd_participants(jid: &Jid, participants: &[Jid])- Add membersremove_participants(jid: &Jid, participants: &[Jid])- Remove memberspromote_participants(jid: &Jid, participants: &[Jid])- Make members adminsdemote_participants(jid: &Jid, participants: &[Jid])- Remove admin statusget_invite_link(jid: &Jid, reset: bool)- Get/reset invite link
presence
set(status: PresenceStatus)- Set presence statusset_available()- Set status to available/onlineset_unavailable()- Set status to unavailable/offlinesubscribe(jid: &Jid)- Subscribe to contact’s presence updates
contacts
get_user_info(jids: &[Jid])- Get profile info for usersget_profile_picture(jid: &Jid)- Get profile picture URLis_on_whatsapp(phones: &[String])- Check phone numbers
tc_token
request_tokens(jids: &[Jid])- Request tokens for contactsprune_expired()- Remove expired tokens
Device State
get_push_name
get_pn
get_lid
persistence_manager
History Sync
set_skip_history_sync
skip_history_sync_enabled
true if history sync is currently being skipped.
App State
fetch_props
fetch_privacy_settings
clean_dirty_bits
Protocol Operations
send_node
Binary protocol node to send
ClientError::NotConnected- Not connectedClientError::EncryptSend- Encryption/send failure
register_handler
Handler implementing the EventHandler trait
register_chatstate_handler
Spam Reporting
send_spam_report
The spam report request containing:
message_id- ID of the message being reportedmessage_timestamp- Timestamp of the messagespam_flow- Context where report was initiated (MessageMenu, GroupInfoReport, etc.)from_jid- Optional sender JIDgroup_jid- Optional group JID for group spamparticipant_jid- Optional participant JID in group contextraw_message- Optional raw message bytesmedia_type- Optional media type if reporting media
SpamReportResult indicating success or failure
Example:
MessageMenu- Reported from message context menuGroupInfoReport- Reported from group info screenGroupSpamBannerReport- Reported from group spam bannerContactInfo- Reported from contact info screen
Passive Mode
set_passive
false (active), the server starts sending offline messages.
Prekeys
send_digest_key_bundle
Error Types
See Also
- Bot - High-level builder with event handlers
- Events - Event system and types
- Sending Messages - Sending and receiving messages
- Group Management - Working with groups