Chatstate

The Chatstate struct provides methods for sending typing indicators and recording notifications to recipients.

Access

Access chatstate operations through the client:

let chatstate = client.chatstate();

Methods

send

Send a chat state update to a recipient.

pub async fn send(
    &self,
    to: &Jid,
    state: ChatActivity,
) -> Result<(), ChatStateError>

Parameters:

to - Recipient JID (user or group)
state: ChatActivity - Type of chat state to send

Returns:

Result<(), ChatStateError>; Ok(()) on success; a ChatStateError if the client is disconnected or the JID is invalid

Example:

use whatsapp_rust::ChatActivity;

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;

// Send typing indicator
client.chatstate().send(&recipient, ChatActivity::Typing).await?;

// Send recording indicator
client.chatstate().send(&recipient, ChatActivity::RecordingAudio).await?;

// Send paused (stopped typing)
client.chatstate().send(&recipient, ChatActivity::Idle).await?;

send_composing

Convenience method to send typing indicator.

pub async fn send_composing(&self, to: &Jid) -> Result<(), ChatStateError>

Example:

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;
client.chatstate().send_composing(&recipient).await?;

send_recording

Convenience method to send audio recording indicator.

pub async fn send_recording(&self, to: &Jid) -> Result<(), ChatStateError>

Example:

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;
client.chatstate().send_recording(&recipient).await?;
println!("Showing 'recording audio' indicator");

send_paused

Convenience method to send paused/stopped typing indicator.

pub async fn send_paused(&self, to: &Jid) -> Result<(), ChatStateError>

Example:

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;
client.chatstate().send_paused(&recipient).await?;
println!("Cleared typing indicator");

Receiving chat state events

ChatStateEvent

Incoming chatstate stanzas (typing indicators from other users) are dispatched as ChatStateEvent values. Register a handler with subscribe_chatstate_handler to receive them.

#[derive(Debug, Clone)]
pub struct ChatStateEvent {
    /// The chat where the event occurred (user JID for 1:1, group JID for groups)
    pub chat: Jid,
    /// For group chats, the participant who triggered the event
    pub participant: Option<Jid>,
    /// The chat state (typing, recording_audio, or idle)
    pub state: ChatActivity,
}

Jid

The chat where the event occurred. For direct messages this is the sender’s JID; for groups this is the group JID.

Option<Jid>

For group chats, the participant who triggered the event. None for 1:1 chats.

ChatActivity

The parsed chat state; see ChatActivity below.

Example:

use whatsapp_rust::{ChatActivity, ChatStateEvent};
use std::sync::Arc;

let subscription = client.subscribe_chatstate_handler(Arc::new(|event: ChatStateEvent| {
    match event.state {
        ChatActivity::Typing => {
            println!("{} is typing in {}", event.participant.as_ref().unwrap_or(&event.chat), event.chat);
        }
        ChatActivity::RecordingAudio => {
            println!("{} is recording audio", event.chat);
        }
        ChatActivity::Idle => {
            println!("{} stopped typing", event.chat);
        }
        _ => {}
    }
}));

ChatActivity

Use the same activity value for incoming events and outgoing updates.

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ChatActivity {
    Typing,        // User is typing text
    RecordingAudio, // User is recording a voice message
    Idle,          // User stopped typing/recording (default)
}

ChatActivity is #[non_exhaustive], so match statements should include a wildcard arm. Wire format mapping:

XML stanza	ChatActivity
`<composing/>`	`Typing`
`<composing media="audio"/>`	`RecordingAudio`
`<paused/>`	`Idle`

use whatsapp_rust::{Client, ChatActivity, ChatStateError, wacore_binary::Jid};

async fn send_activity(client: &Client, chat: &Jid, activity: ChatActivity) -> Result<(), ChatStateError> {
    client.chatstate().send(chat, activity).await
}

Activity representation

Persisted event JSON changes intentionally. See the before/after migration examples before updating external consumers. ChatActivity is shared by sending, ChatStateEvent.state, and ChatPresenceUpdate.state. It describes activity in one chat. Global online/offline availability uses PresenceStatus separately. Serde serializes the activities as "typing", "recording_audio", and "idle". These names are semantic values. Use into_child_node() and from_child_node(&NodeRef) for the protocol projection. Recording audio produces <composing media="audio"/>. The parser treats unknown media on composing as typing and unknown child tags as idle. Keep the raw node separately if you need to preserve unknown attributes.

Wire Format

Composing (Typing)

<chatstate to="15551234567@s.whatsapp.net">
  <composing/>
</chatstate>

Recording (Voice)

<chatstate to="15551234567@s.whatsapp.net">
  <composing media="audio"/>
</chatstate>

Note: Recording uses <composing media="audio"> rather than a separate tag.

Paused (Stopped)

<chatstate to="15551234567@s.whatsapp.net">
  <paused/>
</chatstate>

Usage Patterns

Typing indicator lifecycle

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;

// User starts typing
client.chatstate().send_composing(&recipient).await?;

// User is typing... (you may want to throttle these)
std::thread::sleep(std::time::Duration::from_secs(2));

// User stopped typing (optional, will auto-clear)
client.chatstate().send_paused(&recipient).await?;

// Send the actual message
let mut message = wa::Message::default();
message.conversation = Some("Hello!".to_string());
client.send_message(recipient.clone(), message).await?;

Recording Audio

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;

// Start recording
client.chatstate().send_recording(&recipient).await?;

// Record audio...
let audio_data = record_audio();

// Stop indicator (optional)
client.chatstate().send_paused(&recipient).await?;

// Upload and send audio message
let upload = client.upload(audio_data, MediaType::Audio, Default::default()).await?;
let message = {
    let mut value = wa::Message::default();
    value.audio_message = buffa::MessageField::some({
        let mut value = wa::message::AudioMessage::default();
        value.url = Some(upload.url.clone());
        value.direct_path = Some(upload.direct_path.clone());
        value.media_key = Some(upload.media_key_vec());
        value.file_enc_sha256 = Some(upload.file_enc_sha256_vec());
        value.file_sha256 = Some(upload.file_sha256_vec());
        value.file_length = Some(upload.file_length);
        value.mimetype = Some("audio/ogg; codecs=opus".to_string());
        value.ptt = Some(true);
        value
    });
    value
};
client.send_message(recipient.clone(), message).await?;

Throttling

To avoid spamming chat state updates:

use std::time::{Duration, Instant};

struct ChatStateThrottler {
    last_sent: Option<Instant>,
    interval: Duration,
}

impl ChatStateThrottler {
    fn new() -> Self {
        Self {
            last_sent: None,
            interval: Duration::from_secs(3),
        }
    }
    
    fn should_send(&mut self) -> bool {
        if let Some(last) = self.last_sent {
            if last.elapsed() < self.interval {
                return false;
            }
        }
        self.last_sent = Some(Instant::now());
        true
    }
}

// Usage
let mut throttler = ChatStateThrottler::new();
let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;

// In your typing event handler
if throttler.should_send() {
    client.chatstate().send_composing(&recipient).await?;
}

Group Chats

Chat state indicators work in group chats as well:

let group_jid: Jid = "123456789@g.us".parse()?;

// Show typing in group
client.chatstate().send_composing(&group_jid).await?;

// Send message
let mut message = wa::Message::default();
message.conversation = Some("Hello everyone!".to_string());
client.send_message(group_jid.clone(), message).await?;

Error Handling

All methods return Result<(), ChatStateError>. You’ll encounter these most often:

Not connected; you are not connected to WhatsApp
Invalid JID; the recipient JID is malformed
Network errors; connection dropped mid-send

use whatsapp_rust::ChatStateError;

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;

match client.chatstate().send_composing(&recipient).await {
    Ok(_) => println!("Sent typing indicator"),
    Err(ChatStateError::Client(e)) => {
        eprintln!("Client error: {}", e);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Best Practices

Throttle updates: Don’t send chat state updates more than once every 2-3 seconds
Clear on send: Send ChatActivity::Idle before sending the actual message
Auto-timeout: Consider auto-clearing typing indicators after 10-15 seconds of inactivity
Don’t spam: Only send when state actually changes
Groups: Be mindful that all group members will see the indicator

Complete Example

use std::time::Duration;

let recipient: Jid = "15551234567@s.whatsapp.net".parse()?;

// Simulate user typing
println!("User starts typing...");
client.chatstate().send_composing(&recipient).await?;

// Simulate typing delay
tokio::time::sleep(Duration::from_secs(2)).await;

// User still typing (throttled)
println!("Still typing...");

// User finishes and sends message
client.chatstate().send_paused(&recipient).await?;
let mut message = wa::Message::default();
message.conversation = Some("Hello there!".to_string());
client.send_message(recipient.clone(), message).await?;
println!("Message sent");

// Or simulate voice recording
println!("\nUser starts recording...");
client.chatstate().send_recording(&recipient).await?;

tokio::time::sleep(Duration::from_secs(3)).await;

client.chatstate().send_paused(&recipient).await?;
println!("Recording stopped (would send audio here)");

Retain subscription while receiving chatstate updates. Dropping it unregisters the handler; an in-flight dispatch can still complete. client.chatstate().subscribe_handler(handler) follows the same Subscription contract.

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Methods

send

send_composing

send_recording

send_paused

Receiving chat state events

ChatStateEvent

ChatActivity

Activity representation

Wire Format

Composing (Typing)

Recording (Voice)

Paused (Stopped)

Usage Patterns

Typing indicator lifecycle

Recording Audio

Throttling

Group Chats

Error Handling

Best Practices

Complete Example

​Access

​Methods

​send

​send_composing

​send_recording

​send_paused

​Receiving chat state events

​ChatStateEvent

​ChatActivity

​Activity representation

​Wire Format

​Composing (Typing)

​Recording (Voice)

​Paused (Stopped)

​Usage Patterns

​Typing indicator lifecycle

​Recording Audio

​Throttling

​Group Chats

​Error Handling

​Best Practices

​Complete Example

Access

Methods

send

send_composing

send_recording

send_paused

Receiving chat state events

ChatStateEvent

ChatActivity

Activity representation

Wire Format

Composing (Typing)

Recording (Voice)

Paused (Stopped)

Usage Patterns

Typing indicator lifecycle

Recording Audio

Throttling

Group Chats

Error Handling

Best Practices

Complete Example