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.lists module lets you create named tabs that filter the WhatsApp chat list — the same feature exposed in the app’s own “Filters” tab bar. Lists work on both personal and WhatsApp Business accounts. When a list is active, the chat list shows only the conversations that belong to it. Unlike WPP.labels, lists are not visual tags on individual chats; they are organizational containers that produce a separate filtered view.
WPP.lists uses the same underlying LabelStore as WPP.labels, but it operates only on entries with type === 5 (WhatsApp’s internal ListType.CUSTOM). Functions do not overlap and will not interfere with Business labels.

​
Lists vs. labels

FeatureWPP.listsWPP.labels
Account typePersonal and BusinessBusiness only
AppearanceNamed tab at the top of the chat listColored chip tags on each chat row
Multiple per chatNoYes
Color pickerAutomatic (palette index)Manual or automatic
Filters viewYes — activates a filtered chat listNo
Use WPP.lists when you need named chat list filter tabs that work regardless of account type. Use WPP.labels when you need per-chat color-coded tagging in a Business account.

​
Functions

​
create

Creates a new named list and optionally populates it with an initial set of chats. Returns the numeric string ID assigned to the new list. 
WPP.lists.create(name, chatIds?, colorIndex?)
​
name
string
required
Display name for the new list. Whitespace is trimmed. An empty or whitespace-only string throws WPPError with code list_name_required.
​
chatIds
(string | Wid)[]
default:"[]"
Array of chat IDs to add to the list immediately after creation. Accepts JID strings (e.g. '15551234567@c.us') or Wid objects. Omit or pass an empty array to create an empty list.
​
colorIndex
number
Non-negative integer index into the WhatsApp color palette. Omit to auto-assign the next available color. Passing a negative value or a non-integer throws WPPError with code list_invalid_color.
Returns Promise<string> — the numeric string ID of the new list (e.g. '42'). 
// Create an empty list
const listId = await WPP.lists.create('Family');
console.log(listId); // '42'

// Create a list and pre-populate it
const id = await WPP.lists.create('Team', [
  '15551111111@c.us',
  '15552222222@c.us',
]);

// Create with a specific color
const coloredId = await WPP.lists.create('Work', [], 3);

​
list

Returns all custom lists defined for the current account. This function is synchronous. 
WPP.lists.list()
Returns ListInfo[] — an array of list descriptor objects (not a Promise).
​
id
string
Numeric string ID of the list.
​
name
string
Display name of the list.
​
colorIndex
number
Integer index into the WhatsApp color palette.
const allLists = WPP.lists.list();
for (const l of allLists) {
  console.log(`[${l.id}] ${l.name} (color index: ${l.colorIndex})`);
}
list() is synchronous and reads directly from the in-memory LabelStore. It returns immediately without awaiting any network request.

​
addChats

Adds one or more chats to an existing list. 
WPP.lists.addChats(listId, chatIds)
​
listId
string
required
Numeric string ID of the target list (e.g. '42').
​
chatIds
(string | Wid)[]
required
Array of chat JID strings or Wid objects to add. An empty array is a no-op.
Returns Promise<void> Throws WPPError with code list_not_found if listId does not correspond to an existing list. 
await WPP.lists.addChats('42', [
  '15551111111@c.us',
  '15559999999@c.us',
]);

​
removeChats

Removes one or more chats from a list without deleting the list itself. 
WPP.lists.removeChats(listId, chatIds)
​
listId
string
required
Numeric string ID of the list.
​
chatIds
(string | Wid)[]
required
Array of chat JID strings or Wid objects to remove. An empty array is a no-op.
Returns Promise<void> Throws WPPError with code list_not_found if listId does not correspond to an existing list. 
await WPP.lists.removeChats('42', ['15559999999@c.us']);

​
rename

Renames an existing list. The list ID and color are unchanged. 
WPP.lists.rename(listId, newName)
​
listId
string
required
Numeric string ID of the list to rename.
​
newName
string
required
New display name. Whitespace is trimmed. An empty or whitespace-only string throws WPPError with code list_name_required.
Returns Promise<void> Throws WPPError with code list_not_found if listId does not correspond to an existing list. 
await WPP.lists.rename('42', 'Close Family');

​
remove

Permanently deletes a list by ID. Chats that were inside the list are not affected — they remain in the main chat list. 
WPP.lists.remove(listId)
​
listId
string
required
Numeric string ID of the list to delete.
Returns Promise<void> Throws WPPError with code list_not_found if listId does not correspond to an existing list. 
await WPP.lists.remove('42');

​
Full workflow example

The example below sets up two lists for a remote team, adds contacts to each, and later cleans up one of them. 
// 1. Create the lists
const workId   = await WPP.lists.create('Work Contacts');
const projectId = await WPP.lists.create('Project Alpha', [
  '15551000001@c.us',
  '15551000002@c.us',
]);

// 2. Add a late joiner to the project list
await WPP.lists.addChats(projectId, ['15551000003@c.us']);

// 3. Inspect all current lists
const allLists = WPP.lists.list();
console.log(allLists);
// [{ id: '42', name: 'Work Contacts', colorIndex: 0 },
//  { id: '43', name: 'Project Alpha', colorIndex: 1 }]

// 4. Rename a list when the project is renamed
await WPP.lists.rename(projectId, 'Project Beta');

// 5. Remove a contact who left the project
await WPP.lists.removeChats(projectId, ['15551000002@c.us']);

// 6. Delete a list that is no longer needed
await WPP.lists.remove(workId);

​
Error reference

Thrown by create and rename when the provided name is an empty string or contains only whitespace.
Thrown by create when colorIndex is provided but is not a non-negative integer.
Thrown by addChats, removeChats, rename, and remove when the specified listId does not match any list in the local LabelStore. This typically means the list was already deleted or the ID is incorrect.

Build docs developers (and LLMs) love

Get started for freeTalk to us