Skip to main content

Overview

This guide covers sending messages, including text, reactions, channel comments, quotes, album messages (grouped media), sticker packs, and message editing operations using the whatsapp-rust library.

Text message shortcuts

For the common case of sending or replying with plain text, prefer the high-level helpers:

MessageContext reply helpers (inside event handlers)

When you’re already inside an on_message handler:

Client::send_text (from any Client reference)

wa::Message::text / wa::Message::text_with_context

Build a text message without hand-assembling the protobuf struct:
These are equivalent to building wa::Message { conversation: Some(...) } and wa::Message { extended_text_message: buffa::MessageField::some(...) } by hand, but less verbose.

Sending text messages

Simple text message

Use the conversation field for plain text messages, or wa::Message::text("...") for shorter syntax:
send_message returns a SendResult containing the message_id and recipient to JID. Use result.message_key() to get a wa::MessageKey for follow-up operations like album child linking.

Extended text message

For messages with formatting, links, or context (replies/quotes):

Quoted Replies

Replying to a message

Use build_quote_context to create a basic reply:

Cross-platform quoted replies with remoteJid

For quoted replies that display correctly on all platforms (including iOS), use build_quote_context_with_info. It matches WhatsApp Web’s behavior: it sets participant correctly (channel JID for newsletters, sender for everything else) and emits remote_jid only for cross-chat quotes — when the quoted message lives in a different chat than the one you’re sending to. The function takes both the quoted message’s chat (quoted_chat_jid) and the chat you’re sending into (target_chat_jid). For an in-place reply these are the same JID, and remote_jid is omitted; for a cross-chat quote (for example, quoting a status update into a DM) they differ, and remote_jid is set to the quoted chat:
The build_quote_context_with_info function handles two important details:
  • remote_jid is set only when quoted_chat_jid and target_chat_jid refer to different chats (cross-chat quote). For same-chat replies it is omitted, matching WhatsApp Web.
  • participant is set to the sender JID for normal chats, or the newsletter JID for newsletter quotes.
Pass the same JID for both quoted_chat_jid and target_chat_jid when replying in-place. Use different JIDs only when forwarding a quote across chats (for example, quoting a status into a DM).

Setting context on media messages

You can add quote context to any message type using set_context_info:

Reactions

Sending a reaction

Use client.send_reaction() to react to a DM, group, or status@broadcast message. The helper builds the ReactionMessage payload, stamps sender_timestamp_ms, and routes the stanza through the standard send path.
For groups and status@broadcast, target_key.participant must point to the original sender so the receipt can be attributed. In DMs, leave participant as None. If you’re already inside an event handler, MessageContext::react fills in chat, target_key, and participant from the incoming message automatically:

Reactions in Community Announcement Groups

Community Announcement Groups (CAGs) — the default announcement subgroup of a community — require encrypted reactions. send_reaction handles this transparently: it detects CAG chats automatically and sends the reaction as an encrypted enc_reaction_message envelope instead of a plaintext stanza. No change to your call is needed. The only requirement is that the target post’s messageSecret was captured when the post was received. If it was not captured (for example, msg_secret_policy is disabled without a resolver, or the post arrived before the current session), the call returns an error rather than emitting a plaintext reaction the channel would reject.
See Community management — CAG reactions for details.

Removing a reaction

Pass an empty emoji to revoke a previous reaction (matches WhatsApp Web’s empty-text-as-revoke semantics):
Newsletter (channel) reactions use a different plaintext stanza format. Use client.newsletter().send_reaction() for newsletters instead.

Channel Comments

Channel comments are encrypted threaded replies under a Community Announcement Group (CAG) post. Use client.comments() to send them:
For arbitrary message bodies:
The parent_key.participant field must identify the post author so receivers can derive the HKDF decryption key from the envelope. When from_me is true and participant is absent the library resolves the author to your own identity. Incoming encrypted comments are decrypted transparently. The comment body is dispatched as part of an Event::Messages batch and the parent post key is available on MessageInfo::comment_target:
See Community management — Channel comments for full details.

Editing messages

Use client.edit_message to replace the content of a message you previously sent. Pass the chat JID, the original message ID, and the new content as a plain wa::Message — the client builds the correct wire envelope, resolves the participant JID (LID or PN) for groups, and sends the edit with a fresh stanza ID so the server does not deduplicate it against the original.
Message editing only works for text messages (conversation or extended_text_message) sent by you within the last 15 minutes.
Do not hand-roll the edit envelope by wrapping a ProtocolMessage inside Message.edited_message (a FutureProofMessage) and passing it to send_message. That shape is the history/storage form; on the wire WhatsApp expects a top-level protocolMessage with type = MESSAGE_EDIT. client.edit_message produces the correct shape — manual envelopes will be silently dropped by the server.

Pinning the outer stanza id

client.edit_message always mints a fresh outer stanza id — that’s what stops the server from deduplicating the edit against the original message. If you need to control that id yourself (for example, to collide it with an existing message so clients re-render that slot), use client.edit_message_with_options with EditOptions:
Pinning stanza_id to an id borrowed from another message is best-effort: the server and recipient clients decide whether the collision is honored. The library does not persist retry-cache or outbound-secret state under the borrowed id, so the original message’s retry content and secret are left intact. Leave stanza_id as None (or use plain edit_message) unless you specifically need this.

Deleting messages (revoke)

Delete your own message

See Send API reference for full details.

Admin delete (group only)

Group admins can delete messages from other participants:
Admin revoke only works in group chats. The original_sender must match the JID format (LID or phone number) of the message being deleted.

Sending to newsletters

Newsletter messages are sent through the same client.send_message() method. The library automatically detects newsletter JIDs and sends messages as plaintext (no Signal encryption):
The correct stanza type (text, media, reaction, poll), mediatype attributes, and <meta> nodes (for polls, events, etc.) are inferred automatically from the message content. See the Newsletters guide for more details.
Newsletter reactions use a different protocol format. Use client.newsletter().send_reaction() for reactions instead of send_message().

Album messages

Album messages let you send multiple images and/or videos as a grouped media album — the collapsed album bubble that WhatsApp displays when someone sends several photos at once. An album consists of:
  1. A parent AlbumMessage declaring the expected image and video counts
  2. Multiple child messages (individual media messages) wrapped with wrap_as_album_child and linked to the parent

Sending an album

How it works

The wrap_as_album_child function (from whatsapp_rust::proto_helpers) takes a media wa::Message and a parent wa::MessageKey, then:
  1. Wraps the inner message in an associated_child_message (FutureProofMessage envelope)
  2. Attaches a MessageAssociation with type MediaAlbum pointing to the parent
  3. Lifts any existing message_context_info from the inner message to the outer wrapper
The parent AlbumMessage declares the total expected counts so WhatsApp clients know how many media items to group together. Each child is sent as a separate message linked back to the parent via MessageAssociation.

Mixed albums (images and videos)

You can mix images and videos in the same album:

Sticker packs

Sticker packs let you send a collection of stickers as a single message — the inline sticker pack bubble that WhatsApp displays with a tray icon, pack name, and publisher info. A sticker pack requires:
  1. Sticker images — 512x512 WebP files
  2. Cover image — WebP file used as the tray icon
  3. Thumbnail — JPEG uploaded separately with the same media_key as the ZIP
  4. Metadata — pack ID, name, and publisher

Sending a sticker pack

How it works

The sticker pack flow uses two helper functions from wacore::sticker_pack:
  • create_sticker_pack_zip — bundles stickers and a cover image into a ZIP file. Filenames use base64url(sha256).webp, and identical stickers are deduplicated. Returns a StickerPackZipResult containing the ZIP bytes and proto metadata.
  • build_sticker_pack_message — constructs a wa::Message with a StickerPackMessage from the ZIP result and upload responses.
The thumbnail must be uploaded with MediaType::StickerPackThumbnail and the same media_key as the ZIP upload. The UploadResponse implements Into<MediaUploadInfo> for convenience.

Sticker format requirements

Sticker metadata

Each sticker supports optional metadata:
Pack-level metadata supports optional description and caption:
Animated stickers are automatically detected from the WebP data. The is_animated field on each sticker proto entry is set based on whether the WebP file contains animation frames. You can also use whatsapp_rust::webp::is_animated() directly to check WebP files before processing.

Forwarding messages

Use forward_message to forward any received message to a chat. It produces the same on-wire result as tapping Forward in the official clients:
The helper takes care of the WhatsApp forwarding rules so you don’t have to rebuild the message by hand:
  • Sets context_info.is_forwarded = true so recipients see the Forwarded label.
  • Bumps the forwarding score. Once the score reaches 5, it jumps to the 127 sentinel that clients render as Forwarded many times.
  • Strips the reply/quote chain and mentions from the source.
  • Drops the source message_secret so the send path mints a fresh one.
  • Unwraps ephemeral and view-once wrappers before sending the inner content.
  • Promotes a bare conversation to extended_text_message so the forward marker can attach.
Media is relayed from the same CDN blob, so forwarding an image, video, document, audio, or sticker is instant regardless of file size — nothing is downloaded or re-uploaded.

Manually forwarding media

If you need to customize fields (for example, change a caption) before forwarding, you can still build the wa::Message yourself and pass it to send_message. Reusing the original CDN fields keeps the send instant:
Note that this path does not apply the Forwarded marker or the forwarding-score bump. Use forward_message whenever you want the recipient to see the standard forward indicator. See Media handling — CDN reuse for details on supported media types and when to fall back to download + re-upload.

Ephemeral (disappearing) messages

WhatsApp supports disappearing messages that automatically delete after a set duration. When a chat has disappearing messages enabled, you should set the ephemeral expiration on outgoing messages so recipients see the correct countdown timer.

Sending a disappearing message

Use send_message_with_options with ephemeral_expiration set to the chat’s timer value:
This sets contextInfo.expiration on the protobuf message, which tells WhatsApp clients to display the disappearing countdown.

Common timer values

Getting the chat’s ephemeral timer

For groups, read the timer from group metadata:
For incoming messages, read it from MessageInfo:

Configuring disappearing messages

Per-group: Use set_ephemeral to enable or disable disappearing messages on a group:
Account-level default: Use set_default_disappearing_mode to set the default for all new 1-on-1 chats:
The account-level default only applies to new chats. Existing chats keep their current setting. To change a specific group’s timer, use set_ephemeral.

Listening for timer changes

When a contact changes their default disappearing messages setting, you receive a DisappearingModeChanged event:
When a group’s ephemeral setting changes, you receive a GroupUpdate event with a GroupNotificationAction::Ephemeral action containing the new expiration value. See Events reference for details.

Creating groups with disappearing messages

You can enable disappearing messages at group creation time:
See Send API reference for the full SendOptions type.

Send Options

Specifying a custom message ID

You can override the auto-generated message ID by setting message_id via SendOptions. This is useful for resending a failed message with the same ID or ensuring idempotency:

Overriding the stanza type

The library infers the <message type="..."> attribute from the protobuf content of every send. If you’re sending a message variant the classifier can’t recognize, set stanza_type_override to force a specific wire type:
Leave this as None for every supported message type — the classifier already picks the right value, and the override is not preserved across the retry path. See Stanza types for the available variants.

Adding extra stanza nodes

For advanced use cases, you can include custom XML nodes:
See Send API reference for full details.
SendOptions and EditOptions are #[non_exhaustive] — build them by chaining the with_* setters off ::default() rather than a struct literal (even with ..Default::default()), since new fields can be added in future releases without breaking existing call sites.

Message preparation helpers

Preparing messages for quoting

The prepare_for_quote method strips nested context info:
This ensures:
  • Nested mentions are stripped
  • Quote chains are broken (except for bot messages)
  • Content fields (text, caption, media) are preserved

Preparing messages for forwarding

prepare_for_forward is the lower-level helper that powers forward_message. It returns a forward-ready wa::Message (forward marker set, score bumped, quote chain stripped, source message_secret dropped) without sending anything. Reach for it when you need to attach extra fields — for example, a custom caption or stanza nodes — before calling send_message_with_options:
For the common case, prefer client.forward_message(to, &message) — it unwraps wrapper bodies (ephemeral, view-once) and sends in one call. See WAProto API reference for message type details.

Error Handling

All send-path methods return Result<T, SendError>. Callers using ? into an anyhow context compile unchanged — SendError implements Into<anyhow::Error>.
For typed error matching:
See the Error Types reference for the complete SendError definition and all domain error types.

Best Practices

Next Steps