Skip to main content

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

Send a reaction to a specific newsletter message using its server_id:
See Send API reference for details.

Editing and revoking messages

Channels use a plaintext edit/revoke flow that’s separate from DM and group messages. Call the helpers on client.newsletter() and pass the original message’s message_id (the wire stanza id returned by send_message, not the server_id used for reactions):
Don’t call Client::edit_message or Client::revoke_message with a newsletter JID. The E2E send path now rejects channel JIDs outright (including from pin_message) so you get a clear error rather than a malformed encrypted stanza. Always go through client.newsletter() for channel edits and revokes.

Fetching message history

Retrieve past messages with pagination support:

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 reaction count changes:
The server sends NewsletterLiveUpdate events with updated reaction counts. Handle them in your event handler:
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 operations return MexError for metadata/management operations and anyhow::Error for message operations:

Key differences from groups

Next steps