Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wppconnect-team/wa-js/llms.txt

Use this file to discover all available pages before exploring further.

The WPP.newsletter module exposes the WhatsApp Channels feature — previously known as newsletters — as a programmable API. Channels are one-way broadcast feeds that any WhatsApp user can follow. If you own a channel, you can create, edit, and delete it and inspect its subscriber list. If you are a follower, you can subscribe, unsubscribe, and mute notifications. The search function is available to all users and lets you discover channels from the in-app directory.
Channel IDs always end with @newsletter (e.g. 120363xxxxxx@newsletter). Every function that accepts a newsletterId or id parameter requires this suffix.

​
Ownership vs. following

There are two distinct relationships a WhatsApp account can have with a channel:
  • Owner — created the channel. Can call edit, destroy, and getSubscribers.
  • Follower — subscribed to the channel. Can call follow, unfollow, and mute.
Attempting to call owner-only functions on a channel you only follow will result in a permission error from WhatsApp’s backend.

​
Functions

​
create

Creates a new WhatsApp Channel owned by the authenticated account and returns metadata about the newly created channel. 
WPP.newsletter.create(name, opts?)
​
name
string
required
Display name for the new channel.
​
opts
object
Returns Promise<ResultCreateNewsletter>
​
idJid
string
The full channel JID, e.g. 120363xxxxxx@newsletter.
​
inviteCode
string
Short invite code used to construct the public link.
​
inviteLink
string
Full public URL: https://whatsapp.com/channel/{inviteCode}.
​
name
string
Channel display name.
​
state
string
Current state of the channel (e.g. ACTIVE).
​
subscribersCount
number
Number of followers at creation time.
​
description
string | null
The description you provided, or null.
​
timestamp
number
Unix timestamp (seconds) of channel creation.
const channel = await WPP.newsletter.create('Tech Daily', {
  description: 'Daily technology news and analysis',
  picture: '<base64_image_string>',
});

console.log(channel.inviteLink);
// https://whatsapp.com/channel/AbCdEfGhIjKlMnOp

​
edit

Updates one or more metadata fields of a channel you own. Pass only the fields you want to change; omitted fields are left untouched. 
WPP.newsletter.edit(newsletterId, opts)
​
newsletterId
string
required
The @newsletter JID of the channel to edit.
​
opts
object
required
Returns Promise<ResultCreateNewsletter> — the full updated channel metadata (same shape as create). 
// Rename the channel
await WPP.newsletter.edit('120363xxxxxx@newsletter', {
  name: 'Tech Daily — Rebranded',
});

// Update description only
await WPP.newsletter.edit('120363xxxxxx@newsletter', {
  description: 'Updated description text',
});

// Set a new picture from a URL
await WPP.newsletter.edit('120363xxxxxx@newsletter', {
  picture: 'https://example.com/banner.jpg',
});

// Remove the current picture
await WPP.newsletter.edit('120363xxxxxx@newsletter', {
  picture: null,
});

​
destroy

Permanently deletes a channel you own. This action cannot be undone. 
WPP.newsletter.destroy(id)
​
id
string
required
The @newsletter JID of the channel to delete. Must contain the literal string newsletter or a WPPError is thrown before the request is made.
Returns Promise<boolean> — true on success, false if the underlying request fails.
destroy is permanent. All channel history, posts, and subscriber associations are removed. There is no confirmation step.
const deleted = await WPP.newsletter.destroy('120363xxxxxx@newsletter');
console.log(deleted); // true

​
follow

Subscribes the authenticated account to a channel. The account will begin receiving channel updates in its Channels tab. 
WPP.newsletter.follow(id)
​
id
string
required
The @newsletter JID of the channel to follow.
Returns Promise<boolean> — true on success. Throws a typed WPPError for specific backend conditions:
Error codeHTTP statusMeaning
newsletter_follower_limit419Channel has reached its follower capacity
newsletter_closed405Channel is closed to new followers
newsletter_geosuspended451Channel is not available in your country
newsletter_follow_failedotherUnexpected error
try {
  await WPP.newsletter.follow('120363xxxxxx@newsletter');
  console.log('Now following the channel');
} catch (err) {
  if (err.code === 'newsletter_geosuspended') {
    console.warn('Channel unavailable in your region');
  }
}

​
unfollow

Unsubscribes the authenticated account from a channel. Calling this function when already unfollowed is treated as a success (idempotent). 
WPP.newsletter.unfollow(id)
​
id
string
required
The @newsletter JID of the channel to unfollow.
Returns Promise<boolean> — true on success or if already unfollowed. 
await WPP.newsletter.unfollow('120363xxxxxx@newsletter');

​
mute

Mutes or unmutes update notifications for a channel. When muted, posts from the channel are still delivered but no notification sound or banner is shown. 
WPP.newsletter.mute(newsletterId, value?)
​
newsletterId
string
required
The @newsletter JID of the channel.
​
value
boolean
true to mute, false to unmute. Omitting this parameter defaults to muting the channel.
Returns Promise<ChatModel> — the updated chat model for the channel. 
// Mute a channel
await WPP.newsletter.mute('120363xxxxxx@newsletter', true);

// Unmute a channel
await WPP.newsletter.mute('120363xxxxxx@newsletter', false);

// Mute with default (omit the boolean)
await WPP.newsletter.mute('120363xxxxxx@newsletter');
Searches the WhatsApp Channel directory by keyword. Supports optional category filtering and cursor-based pagination. 
WPP.newsletter.search(query, options?)
​
query
string
required
Non-empty search string. Whitespace is trimmed automatically.
​
options
object
Returns Promise<NewsletterSearchResult>
​
newsletters
object[]
Array of matching channel objects.
​
pageInfo
object
Present when the result set can be paginated.
// Basic search
const result = await WPP.newsletter.search('technology');
console.log(result.newsletters.length);

// Filtered search with a limit
const filtered = await WPP.newsletter.search('news', {
  categories: ['NEWS'],
  limit: 5,
});

// Paginate through results
const page1 = await WPP.newsletter.search('sports');
if (page1.pageInfo?.hasNextPage) {
  const page2 = await WPP.newsletter.search('sports', {
    cursorToken: page1.pageInfo.endCursor,
  });
}

​
getSubscribers

Returns a sample of up to 9 subscribers for a channel you own. This function calls WhatsApp’s LIMITED subscription tier, which returns a representative subset rather than the full list. 
WPP.newsletter.getSubscribers(id)
​
id
string
required
The @newsletter JID of the channel. Must contain the string newsletter.
Returns Promise<any> — the raw subscriber array from WhatsApp’s API, or false on error.
getSubscribers is only meaningful when called on a channel you own. Calling it on a channel you merely follow will either fail or return an empty array depending on the backend response.
const subscribers = await WPP.newsletter.getSubscribers('120363xxxxxx@newsletter');
if (subscribers) {
  console.log(`Sample subscriber count: ${subscribers.length}`);
}

​
Error handling

All functions throw WPPError instances with a machine-readable code string. Catch them to branch on specific failure modes: 
import { WPPError } from '@wppconnect/wa-js';

try {
  await WPP.newsletter.follow('120363xxxxxx@newsletter');
} catch (err) {
  if (err instanceof WPPError) {
    switch (err.code) {
      case 'invalid_newsletter_id':
        console.error('Bad channel ID format');
        break;
      case 'newsletter_geosuspended':
        console.error('Channel not available in this region');
        break;
      default:
        console.error('Unexpected error:', err.message);
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us