Skip to main content
Examples on this page target source snapshot 7e5c198e, not a crates.io release. Use the current API guide to select the matching dependency.

Overview

Newsletters (also called channels) are broadcast-style messaging in WhatsApp. Unlike groups, newsletter messages are plaintext (no Signal E2E encryption) and flow one-way from admins to subscribers. This guide covers creating newsletters, managing subscriptions, sending messages, and handling live updates.

Accessing the Newsletter API

All newsletter operations are accessed through the newsletter() method:
See Newsletter API reference for the full API.

Creating a newsletter

The returned NewsletterMetadata contains the channel’s JID (with @newsletter server), name, subscriber count, and invite code. See Newsletter API reference for details.

Listing subscribed newsletters

See Newsletter API reference for details.

Fetching metadata

By JID

By invite code

See Newsletter API reference for all metadata fields.

Joining and leaving

Join a newsletter

Leave a newsletter

See Newsletter API reference for details.

Updating a newsletter

You can update the name and/or description of a newsletter you own:
Pass None for fields you don’t want to change. See Newsletter API reference for details.

Sending messages

Newsletter messages are plaintext — they bypass Signal encryption entirely. You send newsletter messages through the unified client.send_message() method, just like regular and group messages.

Text messages

The library automatically detects that the recipient is a newsletter JID and sends the message as plaintext (no Signal encryption). It also infers the correct type attribute (text, media, reaction, poll) and mediatype attribute from the message content. Stanza-level <meta> nodes (for polls, events, etc.) are also injected automatically, matching WhatsApp Web behavior.
For media messages (images, videos, etc.), you must upload the media separately using the newsletter-specific upload endpoint before sending. Text messages work directly.

Reactions, votes, edits and revokes

For a fetched newsletter message, use message.message_ref(&newsletter_jid)?; for an inbound envelope use inbound.newsletter_ref()?. Pass the result to the newsletter facade. Reactions and poll votes use its server content ID and return a new operation StanzaId. Edits and revokes use its client content MessageId. The IDs are independent and optional; a missing required domain is rejected, not guessed from another field. Use the newsletter action examples and migration guide.

Fetching message history

Retrieve past messages with pagination support:
Each NewsletterMessage also carries the message’s message_id (for edit_message and revoke_message), the <plaintext> media_type hint, <meta> metadata (original_timestamp, last_edit_timestamp_ms, poll_type, content_type, question_type, message_association_type, is_wamo_sub, admin_profile), and the opaque rcat bytes. See NewsletterMessage for the full field list.
forwards_count, views_count, and responses_count are Option<u64>. None means the server sent no counter, which is not the same as Some(0). views_count and responses_count are typically only populated when the viewer’s role in the channel entitles them to those figures.
An edited message updates timestamp and carries EditAttribute::AdminEdit in edit; last_edit_timestamp_ms records the edit time in milliseconds, while every other timestamp on NewsletterMessage is in seconds. A revoked message carries EditAttribute::AdminRevoke, has an empty <plaintext/>, message = None, and no forward counter.

Pagination

Use the server_id from a previous response to paginate backwards:
See Newsletter API reference for details.

Live updates

Subscribe to real-time updates for a newsletter to receive changes to reaction counts, forward counts, and poll tallies:
The server sends NewsletterLiveUpdate events with the current counters of each changed message. Handle them in your event handler:
Each update only includes messages whose counters changed. votes is empty for messages that aren’t polls. Each tally is keyed by the same option_hash as the history tallies from get_messages. forwards_count is None when the server omits the counter. Live updates don’t include views_count or responses_count.
The subscription duration (typically 300 seconds) is returned by the server. You need to re-subscribe periodically to continue receiving live updates.
See Events reference for the full event type.

Error handling

Newsletter methods return NewsletterError. Match NotFound to detect a channel that doesn’t exist:
See NewsletterError for all variants.

Key differences from groups

Next steps