Sending and message actions

Examples on this page target source snapshot 35a69a14, not a crates.io release. Use the current API guide to select the matching dependency.

send

Use send_text for text or send_message for protobuf content with default options. Use send(SendRequest) when you need options. The request owns the protobuf; the result shares the encoded message through an Arc.

use whatsapp_rust::{Client, Jid, MessageId, SendOptions, SendRequest};
use whatsapp_rust::proto_helpers::MessageBuilderExt;
use whatsapp_rust::waproto::whatsapp::Message;

async fn send(client: &Client, chat: &Jid) -> whatsapp_rust::anyhow::Result<()> {
    client.send_text(chat, "Hello").await?;
    let options = SendOptions::default()
        .with_message_id(MessageId::new("CONTENT")?)
        .with_ephemeral_expiration(86_400);
    let sent = client.send(
        SendRequest::new(chat, Message::text("Disappearing message"))
            .with_options(options),
    ).await?;
    println!("{}", sent.message_id.as_str());
    Ok(())
}

SendOptions

Start with SendOptions::default() and use with_* setters. The type is non-exhaustive, so downstream struct literals are unsupported. Options cover a content MessageId, disappearing-message duration, extra stanza nodes, stanza type, group metadata freshness and device freshness. Setting an expiration on the message does not change the chat timer. Use set_chat_disappearing_timer for a DM or groups().set_ephemeral for a group. A send does not establish the recipient’s retention policy. For a DM with no usable recipient device, handle SendError::NoRecipientDevice and deliberately retry with with_device_freshness(Freshness::Refresh). Reusing the cached device list can repeat the same failure. See error handling.

SendResult

message_id: MessageId identifies this send’s envelope. to is its destination, message is the shared encoded protobuf, and recipient_fanout reports device encryption coverage for the DM branch. Fanout counts are not delivery receipts. Group sends, status posts and newsletter plaintext have different routing and do not report DM fanout. message_ref() borrows chat addressing for later operations; it can reject destinations that need another reference type. newsletter_ref() keeps channel client and server content IDs separate. stanza_id() identifies the outer operation for ACK correlation. An edit, revoke or pin result describes the new operation, not the original content. Keep the target reference separately.

edit_message

Pass EditRequest::new(target, replacement). Obtain the target from an inbound message, MessageContext, a send result, or validated addressing metadata.

use whatsapp_rust::{Client, EditOptions, EditRequest, Jid, StanzaId};
use whatsapp_rust::proto_helpers::MessageBuilderExt;
use whatsapp_rust::waproto::whatsapp::Message;

async fn edit(client: &Client, chat: &Jid) -> whatsapp_rust::anyhow::Result<()> {
    let original = client.send_text(chat, "Draft").await?;
    let target = original.message_ref()?;
    let options = EditOptions::default().with_stanza_id(StanzaId::new("EDIT-OPERATION")?);
    let edit = client.edit_message(
        EditRequest::new(target, Message::text("Published"))
            .with_options(options),
    ).await?;
    println!("edit operation: {}", edit.message_id);
    Ok(())
}

EditOptions

The target’s MessageId identifies content. EditOptions::with_stanza_id identifies the new edit operation. Defaults generate a fresh operation ID; overriding it changes server deduplication behavior. For an encrypted edit, use EditRequest::with_secret(original_creator, original_secret). Supply the creation’s exact cryptographic creator, even when its visible sender has a PN/LID alias. This path does not look up or substitute an identity. Community announcement edits require that association.

send_reaction

send_reaction(&MessageRef, emoji) addresses chat content. An empty emoji removes a reaction. The reference preserves the original sender and inbound metadata needed for group, status and comment routing.

revoke_message

revoke_message(&MessageRef) selects sender scope for your own content and admin scope for another group author’s content. A reference grants no server permissions. Revoke another author’s DM content with this API is unsupported.

pin_message

pin_message(&MessageRef, PinDuration) accepts Hours24, Days7 or Days30. Use the original group author in a received group reference.

unpin_message

unpin_message(&MessageRef) sends a new operation targeting the same content.

keep_message

keep_message(&MessageRef, keep) keeps or unkeeps disappearing content. Server rules still determine whether the operation is accepted.

use whatsapp_rust::{Client, MessageRef, PinDuration};

async fn act(client: &Client, target: &MessageRef<'_>) -> whatsapp_rust::anyhow::Result<()> {
    client.send_reaction(target, "👍").await?;
    client.pin_message(target, PinDuration::Days7).await?;
    client.unpin_message(target).await?;
    client.keep_message(target, true).await?;
    Ok(())
}

Raw interoperability

Use the explicitly named *_raw methods when integrating stored byte/string keys. Their arguments differ by operation; they do not replace a correctly scoped MessageRef. See the source reference for exact signatures. Channel actions use NewsletterMessageRef, not MessageRef.

Forwarding and metadata

forward_message prepares and sends forwarded content with default options. prepare_for_forward prepares it without sending, strips the source secret and quote chain, and updates the forward marker. Use the resulting protobuf in a SendRequest when you need custom options. The send pipeline derives stanza metadata for polls, events, pins, media and business content. Extra nodes do not bypass validation; a conflicting automatically derived business or DM bot node is rejected. See business messages, media, polls, events and newsletter actions.

Source reference

Send options, results and routing · Request constructors · Editing · Revokes, pins and keeps · Reactions

Decrypt-fail suppression

The send pipeline derives decrypt-fail="hide" for eligible add-ons and infrastructure content. It unwraps content before classification and attaches the attribute to encrypted nodes. Revokes are excluded from the edit-based rule. See the pinned send source for the complete predicate; callers do not need a second copied list of protobuf variants.

Generate a content ID

use whatsapp_rust::{Client, SendOptions};

fn send_options(client: &Client) -> SendOptions {
    SendOptions::default().with_message_id(client.generate_message_id())
}

The generator returns MessageId, ready for SendOptions. Retransmission keeps the original content ID. A new edit or ACK-correlated operation uses its own StanzaId.

Core

Messaging

Features

Storage & Backends

Core Modules

Sending and message actions

send

SendOptions

SendResult

edit_message

EditOptions

send_reaction

revoke_message

pin_message

unpin_message

keep_message

Raw interoperability

Forwarding and metadata

Source reference

Decrypt-fail suppression

Generate a content ID

​send

​SendOptions

​SendResult

​edit_message

​EditOptions

​send_reaction

​revoke_message

​pin_message

​unpin_message

​keep_message

​Raw interoperability

​Forwarding and metadata

​Source reference

​Decrypt-fail suppression

​Generate a content ID

send

SendOptions

SendResult

edit_message

EditOptions

send_reaction

revoke_message

pin_message

unpin_message

keep_message

Raw interoperability

Forwarding and metadata

Source reference

Decrypt-fail suppression

Generate a content ID