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 thenewsletter() method:
Creating a newsletter
NewsletterMetadata contains the channel’s JID (with @newsletter server), name, subscriber count, and invite code.
See Newsletter API reference for details.
Listing subscribed newsletters
Fetching metadata
By JID
By invite code
Joining and leaving
Join a newsletter
Leave a newsletter
Updating a newsletter
You can update the name and/or description of a newsletter you own: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 unifiedclient.send_message() method, just like regular and group messages.
Text messages
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, usemessage.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: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 theserver_id from a previous response to paginate backwards:
Live updates
Subscribe to real-time updates for a newsletter to receive changes to reaction counts, forward counts, and poll tallies:NewsletterLiveUpdate events with the current counters of each changed message. Handle them in your event handler:
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.
Error handling
Newsletter methods returnNewsletterError. Match NotFound to detect a channel that doesn’t exist:
NewsletterError for all variants.
Key differences from groups
Next steps
- Newsletter API reference — Full API details and types
- Events — Handle newsletter live update events
- Sending messages — Send messages to groups and contacts
- MEX API — Understand the GraphQL layer used by newsletters