WPPConnect

https://github.com/wppconnect-team/wppconnect
Admin
WPPConnect is an open source project that exports functions from WhatsApp Web to Node.js, enabling...
Tokens:82,886
Snippets:607
Trust Score:8.5
License:LGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example with error handling

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/catalog-layer.md

Complete example with error handling for product creation and fetching products.

```javascript
create({ session: 'catalog' }).then(async (client) => {
  try {
    await client.createProduct('Cup', '<base64>', 'Ceramic cup', 99.9, false, 'https://shop.example', 'SKU-1');
  } catch (error) {
    console.error('Product creation failed (business accounts only):', error);
  }

  const products = await client.getProducts('5521988556558@c.us', 10);
  console.log(products);
});
```

--------------------------------

### Download and write media file

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

Example showing how to receive a message, download its media as base64 using downloadMedia, and then write the buffer to a file. Steps are to get a message via onMessage, call downloadMedia with the message id, and use fs.writeFileSync.

```javascript
const msg = await client.onMessage((m) => m); // received message
const base64 = await client.downloadMedia(msg.id);
// write file
await fs.writeFileSync('media.bin', Buffer.from(base64, 'base64'));
```

--------------------------------

### Install WPPConnect via Package Managers

Source: https://github.com/wppconnect-team/wppconnect/blob/master/docs/getting-started/installation.md

Standard installation commands for npm and Yarn package managers.

```bash
npm i --save @wppconnect-team/wppconnect
```

```bash
yarn add @wppconnect-team/wppconnect
```

--------------------------------

### UILayer usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/ui-layer.md

Example usage of the UILayer methods. Creates a client with session 'ui', opens a chat, opens at a specific message, gets and sets the theme (dark), gets and sets auto-download settings, gets the active chat, and closes the chat. Note that setTheme and setAutoDownloadSettings force a reload of WhatsApp Web.

```javascript
create({ session: 'ui' }).then(async (client) => {
  await client.openChat('5531999999999@c.us');      // visually open chat
  await client.openChatAt('5531999999999@c.us', '06D3AB3D0EEB9D077A3F9A3EFF4DD030');

  const theme = await client.getTheme();
  if (theme !== 'dark') {
    await client.setTheme('dark'); // reloads WhatsApp Web
  }

  const settings = await client.getAutoDownloadSettings();
  console.log(settings);
  await client.setAutoDownloadSettings({
    photos: 'onWifi',
    audio: 'onWifi',
    videos: 'onWifi',
    documents: 'onWifi',
  });

  console.log(await client.getActiveChat());
  await client.closeChat();
});
```

--------------------------------

### Install WPPConnect Nightly Release

Source: https://github.com/wppconnect-team/wppconnect/blob/master/docs/getting-started/installation.md

Direct installation command for the latest nightly build tarball.

```bash
> npm i --save https://github.com/wppconnect-team/wppconnect/releases/download/nightly/wppconnect-nightly.tgz
```

--------------------------------

### start method signature

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/host-layer.md

Starts the WhatsApp client. Idempotent, calls initWhatsapp, exposes page functions, and starts a 5-second check interval.

```typescript
public async start()
```

--------------------------------

### Example with error handling

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/status-layer.md

JavaScript example showing how to create a client for status, send an image status, and handle errors with specific codes such as 'empty_file' and 'invalid_image'.

```javascript
create({ session: 'status' }).then(async (client) => {
  try {
    await client.sendImageStatus('./story.jpg', { caption: 'Good morning' });
  } catch (error) {
    if (error.code === 'empty_file') console.error('File missing');
    else if (error.code === 'invalid_image') console.error('Not a supported image');
    else console.error(error);
  }
});
```

--------------------------------

### sendFile usage examples

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Examples of sending a file from a path, from base64 with filename and caption, and with template buttons.

```javascript
// From a path
await client.sendFile('5531999999999@c.us', './someFile.txt');

// From base64 with filename
await client.sendFile('5531999999999@c.us', 'data:text/plain;base64,V1BQQ29ubmVjdA==', {
  filename: 'notes.txt',
  caption: 'hello',
});

// With template buttons
await client.sendFile('5531999999999@c.us', 'data:text/plain;base64,V1BQQ29ubmVjdA==', {
  useTemplateButtons: true,
  buttons: [{ id: 'your custom id 1', text: 'Some text' }],
  title: 'Title text',
  footer: 'Footer text',
});
```

--------------------------------

### start

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/host-layer.md

Starts the WhatsApp Web session by initializing the page and setting up QR code and link code handlers. It is idempotent and begins a periodic check interval.

```APIDOC
## start

### Description
Starts the WhatsApp Web session by initializing the page and setting up QR code and link code handlers. It is idempotent and begins a periodic check interval.

### Method
start

### Endpoint
HostLayer.start()

### Parameters
None

### Request Example
```typescript
await hostLayer.start();
```

### Response
#### Success Response
- **Promise<void>** - Resolves when the session has started.

#### Response Example
```typescript
await hostLayer.start();
```
```

--------------------------------

### Initialize a basic Wppconnect client

Source: https://github.com/wppconnect-team/wppconnect/blob/master/docs/getting-started/creating-client.md

Use the create method to start a new WhatsApp session and return a promise.

```javascript
// Supports ES6
// import { create, Whatsapp } from '@wppconnect-team/wppconnect';
const wppconnect = require('@wppconnect-team/wppconnect');

wppconnect
  .create()
  .then((client) => client.start())
  .catch((error) => console.log(error));
```

--------------------------------

### Forward Messages Example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Example usage of forwardMessagesV2 to forward multiple messages to a chat.

```javascript
const ids = await client.forwardMessagesV2('5531999999999@c.us', [
  'true_5531900000000@c.us_3EB01DE65ACC6_out',
]);
```

--------------------------------

### sendListMessage JavaScript example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Example of sending a list message via client.sendListMessage.

```javascript
await client.sendListMessage('5531999999999@c.us', {
  buttonText: 'Click here',
  description: 'Choose one option',
  sections: [
    {
      title: 'Section 1',
      rows: [{ rowId: 'my_custom_id', title: 'Test 1', description: 'Description 1' }],
    },
  ],
});
```

--------------------------------

### Typing indicator example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Example usage of startTyping and stopTyping to keep the typing indicator active for 5 seconds.

```javascript
// Keep typing for 5 seconds, then stop
await client.startTyping('[number]@c.us', 5000);
await sleep(5000);
await client.stopTyping('[number]@c.us');
```

--------------------------------

### Configure advanced create() options

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/configuration.md

Advanced configuration example for create(). Sets headless mode, browser arguments, keeps the browser open (autoClose: 0), pins a WhatsApp Web version, and configures a proxy with credentials.

```javascript
const { create } = require('@wppconnect-team/wppconnect');

create({
  session: 'production',
  headless: true,
  useChrome: true,
  browserArgs: ['--no-sandbox', '--disable-gpu'],
  autoClose: 0,                     // keep browser open
  deviceSyncTimeout: 240000,
  waitForLogin: true,
  folderNameToken: './.wpp/tokens',
  whatsappVersion: '2.3000.10305x', // pin a WA-Web version
  deviceName: 'ProductionBot',
  disableGoogleAnalytics: true,
  proxy: { url: 'http://127.0.0.1:8080', username: 'u', password: 'p' },
}).then((client) => console.log('ready')).catch(console.error);
```

--------------------------------

### Send Image as Sticker Example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Example usage of sendImageAsSticker to send a sticker from a base64 image.

```javascript
await client.sendImageAsSticker('000000000000@c.us', 'base64....', {
  quotedMsg: 'msgId',
});
```

--------------------------------

### Wait for login and read host device info

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/host-layer.md

This example demonstrates how to create a session with waitForLogin set to true, then retrieve the connection state and host device information after the login is successful.

```javascript
// Wait until the device is usable, then read host info
create({ session: 'host', waitForLogin: true })
  .then(async (client) => {
    const state = await client.getConnectionState(); // SocketState
    const device = await client.getHostDevice();      // HostDevice
    console.log(state, device.platform, device.battery);
  })
  .catch((error) => console.error('login failed:', error.message));
```

--------------------------------

### Install WPPConnect npm package

Source: https://github.com/wppconnect-team/wppconnect/blob/master/README.md

Install the WPPConnect npm package to use its WhatsApp Web functions in a Node.js project.

```bash
npm i --save @wppconnect-team/wppconnect
```

--------------------------------

### Community Management Example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/community-layer.md

Demonstrates creating a community, adding subgroups, retrieving participants, promoting/demoting a participant, removing subgroups, and deactivating the community with error handling.

```javascript
create({ session: 'community' }).then(async (client) => {
  const community = await client.createCommunity(
    'My Community',
    'Community description',
    ['120363023902497372@g.us', '120363023902497373@g.us']
  );

  await client.addSubgroupsCommunity(community.id, ['120363023902497374@g.us']);

  const participants = await client.getCommunityParticipants(community.id);
  console.log('participants:', participants.length);

  // Promote a member to community admin, then demote them again
  await client.promoteCommunityParticipant(community.id, '5531999999999@c.us');
  await client.demoteCommunityParticipant(community.id, '5531999999999@c.us');

  await client.removeSubgroupsCommunity(community.id, ['120363023902497374@g.us']);

  // If the community check fails, guard with try/catch
  try {
    await client.deactivateCommunity(community.id);
  } catch (error) {
    console.error('deactivation failed (may have no admin rights):', error);
  }
});
```

--------------------------------

### create(createOption: CreateOptions): Promise<Whatsapp>

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/create.md

Entry point to start a bot session, taking a CreateOptions object and returning a Promise resolving to a Whatsapp instance.

```APIDOC
## create(createOption: CreateOptions)

### Description
Start the bot. Returns a Whatsapp page, with this parameter you will be able to access the bot functions.

### Method
create

### Parameters
#### Path Parameters
- none

#### Query Parameters
- none

#### Request Body (Options object)
- **createOption** (CreateOptions) - Required - Configuration options for the bot session.

### Request Example
_No request body_ (the options are passed as function argument)

### Response
#### Success Response (Promise<Whatsapp>)
- **Whatsapp** (object) - The Whatsapp page instance with bot control functions.

#### Response Example
```typescript
const client = await create({ session: 'test' });
```
```

--------------------------------

### sendVideoStatus usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/status-layer.md

JavaScript example for sending a video status with a caption. Delegates to WPP.status.sendVideoStatus and throws an Error with .code === 'empty_file' when the file is unreadable.

```javascript
await client.sendVideoStatus('data:video/mp4;base64,<a long base64 file...>', {
  caption: 'example test',
});
```

--------------------------------

### sendMute usage examples

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/profile-layer.md

Examples showing how to mute a contact for a specific duration and how to unmute by setting the time to 0.

```javascript
await client.sendMute('5531999999999@c.us', 8, 'hours');   // mute 8 hours
await client.sendMute('5531999999999@c.us', 0, 'hours');   // unmute
```

--------------------------------

### createProduct usage

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/catalog-layer.md

Example usage of the createProduct method.

```javascript
await client.createProduct(
  'Product name',
  'image in base64',
  'product description',
  89.9,
  true,
  'https://wppconnect.io',
  'AKA001'
);
```

--------------------------------

### decryptAndSaveFile usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

JavaScript example showing how to call decryptAndSaveFile with a message and a destination path, handling errors with try/catch. Logs the result or a decryption failure.

```javascript
try {
  await client.decryptAndSaveFile(imageMessage, './downloads/photo.jpg');
  console.log('Saved decrypted media');
} catch (e) {
  console.error('Decryption failed:', e);
}
```

--------------------------------

### sendTextStatus usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/status-layer.md

JavaScript example that sends a status text with a background color and a selected font.

```javascript
await client.sendTextStatus(`Bootstrap primary color: #0275d8`, {
  backgroundColor: '#0275d8',
  font: 2,
});
```

--------------------------------

### getMessages usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

JavaScript example showing how to fetch the last 20 messages from a chat and then paginate to 20 messages before a known message ID. Uses the client.getMessages method.

```javascript
// last 20 messages
const messages = await client.getMessages('5531999999999@c.us');

// paginate: 20 messages before a known message id
const older = await client.getMessages('5531999999999@c.us', {
  count: 20,
  direction: 'before',
  id: messages[0].id,
});
```

--------------------------------

### sendOrderMessage JavaScript example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Example of sending an order message with product and custom items, price as integer without decimals.

```javascript
await client.sendOrderMessage('[number]@c.us', [
  { type: 'product', id: '67689897878', qnt: 2 },
  { type: 'custom', name: 'Item de cost test', price: 120000, qnt: 2 },
], { tax: 10000, shipping: 4000, discount: 10000 });
```

--------------------------------

### Instantiate and Use MemoryTokenStore with wppconnect.create

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/token-store.md

JavaScript example showing how to create a MemoryTokenStore instance and pass it to wppconnect.create, which uses token storage in memory for the 'mySession' session.

```javascript
const myTokenStore = new wppconnect.tokenStore.MemoryTokenStore();
wppconnect.create({ session: 'mySession', tokenStore: myTokenStore });
```

--------------------------------

### sendImageStatus usage examples

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/status-layer.md

JavaScript examples demonstrating how to send an image status with and without a caption. Delegates to WPP.status.sendImageStatus(base64, options). Throws an Error with .code === 'empty_file' if unreadable or .code === 'invalid_image' if the mime is not an image.

```javascript
await client.sendImageStatus('data:image/jpeg;base64,<a long base64 file...>');
await client.sendImageStatus('data:image/jpeg;base64,<a long base64 file...>', {
  caption: 'example test',
});
```

--------------------------------

### Profile management with error handling

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/profile-layer.md

A complete example demonstrating how to set profile status, name, and picture, including error handling for file operations.

```javascript
create({ session: 'profile' }).then(async (client) => {
  await client.setProfileStatus('Available for calls');
  await client.setProfileName('Support Bot');

  try {
    await client.setProfilePic('./avatar.png');
  } catch (error) {
    if (error.code === 'empty_file') {
      console.error('File not found or invalid');
    } else if (error.code === 'invalid_image') {
      console.error('Not an image, allowed formats png, jpeg and webp');
    } else {
      throw error;
    }
  }

  console.log('status:', await client.getProfileStatus());
  console.log('name:', await client.getProfileName());
});
```

--------------------------------

### FileTokenStore with Custom Options and wppconnect.create

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/token-store.md

JavaScript example creating a FileTokenStore instance with commented-out customization options (decodeFunction, encodeFunction, encoding, fileExtension, path) and passing it to wppconnect.create in the 'otherSession' session.

```javascript
const myTokenStore = new wppconnect.tokenStore.FileTokenStore({
  // decodeFunction: JSON.parse,
  // encodeFunction: JSON.stringify,
  // encoding: 'utf8',
  // fileExtension: '.my.ext',
  // path: './a_custom_path',
});
wppconnect.create({ session: 'otherSession', tokenStore: myTokenStore });
```

--------------------------------

### Start Typing

Source: https://github.com/wppconnect-team/wppconnect/blob/master/docs/getting-started/basic-functions.md

Initiates the typing indicator in a chat.

```javascript
await client.startTyping('000000000000@c.us');
```

--------------------------------

### sendImageFromBase64 usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

JavaScript example showing how to send an image from a base64 data URI. Constructs the data URI by concatenating the prefix with the base64 string and calls sendImageFromBase64 with a group chat ID, filename, and caption.

```javascript
const base64picture = '/9j/4AA[...]VZoCn9Lp//Z';
await client.sendImageFromBase64(
  "120[...]381@g.us",
  "data:image/png;base64," + base64picture,
  "picture.png",
  "my caption"
);
```

--------------------------------

### Chat administration usage example: archiveChat, pinChat, clearChat

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/controls-layer.md

JavaScript example showing how to archive a chat, pin it to the top, and clear it while keeping no starred messages. Uses the client instance methods with a contact ID.

```javascript
await client.archiveChat('5531999999999@c.us', true);   // archive
await client.pinChat('5531999999999@c.us', true);        // pin to top
await client.clearChat('5531999999999@c.us', false);     // clear keeping nothing
```

--------------------------------

### Close client with error tolerance

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

Example showing how to close the client with a try/catch to handle potential errors during shutdown.

```javascript
try {
  await client.close();
} catch (e) {
  console.error('Failed to close cleanly', e);
}
```

--------------------------------

### Initialize Client and Listen for Messages

Source: https://github.com/wppconnect-team/wppconnect/blob/master/docs/getting-started/receiving-messages.md

Initializes the WPPConnect client and defines a callback function to handle incoming messages. The start function must be invoked to begin listening for events.

```javascript
// Supports ES6
// import { create, Whatsapp } from '@wppconnect-team/wppconnect';
const wppconnect = require('@wppconnect-team/wppconnect');

wppconnect
  .create()
  .then((client) => client.start())
  .catch((error) => console.log(error));

function start(client) {
  client.onMessage((message) => {
    if (message.body === 'Hello') {
      client
        .sendText(message.from, 'Hello, how I may help you?')
        .then((result) => {
          console.log('Result: ', result); //return success object
        })
        .catch((error) => {
          console.error('Error when sending: ', error); //return error object
        });
    }
  });
  client.start()
}
```

--------------------------------

### Full flow: send a product image

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/business-layer.md

This flow demonstrates retrieving products via getBusinessProfilesProducts and then sending an image with product using sendImageWithProduct. Connect the call to the example chain.

```javascript
create({ session: 'biz' }).then(async (client) => {
  const products = await client.getBusinessProfilesProducts('5521988556558@c.us');
  const first = products[0];

  await client.sendImageWithProduct(
    '5531999999999@c.us',
    'data:image/png;base64,<...>',
    'Check this item',
    '5521988556558@c.us',
    first.id
  );
});
```

--------------------------------

### create(sessionName: string, catchQR?, statusFind?, onLoadingScreen?, catchLinkCode?, options?, browserSessionToken?): Promise<Whatsapp>

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/create.md

Deprecated overload that starts the bot with a session name and optional callbacks and options. It is deprecated in favor of the CreateOptions overload.

```APIDOC
## create(sessionName: string, ...)

### Description
Start the bot. You must pass a string type parameter, this parameter will be the name of the client's session. If not passed, the session name will be "session". Deprecated in favor of create with {session: 'test'}.

### Method
create (deprecated overload)

### Parameters
#### Path Parameters
- none

#### Query Parameters
- none

#### Request Body (arguments)
- **sessionName** (string) - Required - The session name for the bot.
- **catchQR** (CatchQRCallback) - Optional - Callback fired when a new QR code is rendered.
- **statusFind** (StatusFindCallback) - Optional - Callback for lifecycle transitions.
- **onLoadingScreen** (LoadingScreenCallback) - Optional - Callback for loading progress changes.
- **catchLinkCode** (LinkByCodeCallback) - Optional - Callback for link-code emitted.
- **options** (CreateConfig) - Optional - Additional configuration.
- **browserSessionToken** (SessionToken) - Optional - Browser session token.

### Request Example
```typescript
const session = await wppconnect.create('sessionName');
```

### Response
#### Response Example
Returns a Promise<Whatsapp>.
```

--------------------------------

### Subscribe to all contacts

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/listener-layer.md

Example of subscribing to presence updates for all contacts.

```javascript
// subscribe all contacts
const contacts = await client.getAllContacts();
await client.subscribePresence(contacts.map((c) => c.id._serialized));
```

--------------------------------

### listChats usage examples in JavaScript

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/retriever-layer.md

Examples of calling listChats with parameters: limiting to 20 chats, paginating with direction before, and filtering by labels. The withLabels option accepts either label text or id.

```javascript
const chats = await client.listChats({ count: 20 });                 // 20 chats
const older = await client.listChats({ count: 20, direction: 'before', id: '[number]@c.us' });
const labeled = await client.listChats({ withLabels: ['Test'] });    // label text or id
```

--------------------------------

### editProduct usage

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/catalog-layer.md

Example usage of the editProduct method.

```javascript
await client.editProduct('56989897878', {
  name: 'Product name',
  description: 'product description',
  price: 89.9,
  isHidden: true,
  url: 'https://wppconnect.io',
  retailerId: 'AKA001'
});
```

--------------------------------

### Create a group with client.createGroup

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/group-layer.md

Creates a new group with the specified name and contacts. Returns a GroupCreation object; the example logs the group ID (gid) as a Wid object.

```javascript
const group = await client.createGroup('teste vai', ['5521967865110']); // GroupCreation
console.log(group.gid); // Wid
```

--------------------------------

### Catching WPPConnect errors by code

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/errors.md

Example of how to catch and handle specific error codes like 'empty_file' when calling API methods.

```javascript
try {
  await client.sendFile(to, path);
} catch (error) {
  if (error.code === 'empty_file') {
    // file could not be read/downloaded or base64 was invalid
  } else {
    throw error;
  }
}
```

--------------------------------

### waitForQrCodeScan

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/host-layer.md

Polls `needsToScan(page)` every 200 ms until logged, page closed, or throws when the session is not started.

```APIDOC
## waitForQrCodeScan

### Description
Polls `needsToScan(page)` every 200 ms until logged, page closed, or throws when the session is not started.

### Method
waitForQrCodeScan

### Endpoint
HostLayer.waitForQrCodeScan()

### Parameters
None

### Request Example
```typescript
await hostLayer.waitForQrCodeScan();
```

### Response
#### Success Response
- **Promise<void>** - Resolves when the QR code has been scanned and the session is logged in.

#### Response Example
```typescript
await hostLayer.waitForQrCodeScan();
```

### Errors
- Throws `Error('waitForQrCodeScan error: Session not started')` if the session is not started.
```

--------------------------------

### editBusinessProfile Examples

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/business-layer.md

Shows various ways to call client.editBusinessProfile() with options: description, categories, address/email/website (max 2 sites), business hours with specific hours, open_24h, and appointment_only modes. Includes timezone setting. These are separate use cases, not a connected workflow.

```javascript
// Description
await client.editBusinessProfile({ description: 'New description for profile' });

// Categories
await client.editBusinessProfile({
  categories: { id: '133436743388217', localized_display_name: 'Artes e entretenimento', not_a_biz: false },
});

// Address / email / website (max 2 sites)
await client.editBusinessProfile({ address: 'Street 01, New York' });
await client.editBusinessProfile({ email: 'test@test.com.br' });
await client.editBusinessProfile({ website: ['https://www.wppconnect.io', 'https://www.teste2.com.br'] });

// Specific business hours with timezone
await client.editBusinessProfile({
  businessHours: {
    tue: { mode: 'specific_hours', hours: [[540, 1080]] },
    wed: { mode: 'specific_hours', hours: [[540, 1080]] },
    // ... per day
  },
  timezone: 'America/Sao_Paulo',
});

// Always opened
await client.editBusinessProfile({
  businessHours: {
    mon: { mode: 'open_24h' },
    // ... all days
  },
  timezone: 'America/Sao_Paulo',
});

// Appointment only
await client.editBusinessProfile({
  businessHours: {
    mon: { mode: 'appointment_only' },
    // ... all days
  },
  timezone: 'America/Sao_Paulo',
});
```

--------------------------------

### LabelsLayer usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/lists-labels-newsletter.md

Shows how to use LabelsLayer methods: addNewLabel, addOrRemoveLabels, getAllLabels, and getLabelById. addNewLabel accepts an options object with labelColor. addOrRemoveLabels takes an array of label operations with type 'add' or 'remove'. getAllLabels returns an array of Label objects with properties id, name, color, count, hexColor.

```javascript
await client.addNewLabel('Name of label', { labelColor: '#dfaef0' });

await client.addOrRemoveLabels(
  ['[number]@c.us', '[number2]@c.us'],
  [
    { labelId: '76', type: 'add' },
    { labelId: '75', type: 'remove' },
  ]
);

const labels = await client.getAllLabels(); // Label[]: { id, name, color, count, hexColor }
const label = await client.getLabelById('1');
```

--------------------------------

### Get group member IDs with client.getGroupMembersIds

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/group-layer.md

Retrieves the participant IDs of a group. The example maps each member to its _serialized property for display.

```javascript
const members = await client.getGroupMembersIds('120363023902497372@g.us');
console.log(members.map((m) => m._serialized));
```

--------------------------------

### sendPollMessage JavaScript example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Example of sending a poll message to a group.

```javascript
await client.sendPollMessage('[number]@g.us', 'A poll name', ['Option 1', 'Option 2'], {
  selectableCount: 1,
});
```

--------------------------------

### Import and use tokenStore with create

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/token-store.md

Shows how to import the package and pass a custom token store to the create method. The tokenStore option accepts a TokenStore instance or the string 'file'.

```typescript
import * as wppconnect from '@wppconnect-team/wppconnect';

wppconnect.create({
  session: 'mySession',
  tokenStore: myTokenStore, // TokenStore instance or 'file'
});
```

--------------------------------

### editMessage usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/controls-layer.md

Example call to edit a message. The msgId format is 'true_<number>@c.us_messageId'.

```javascript
await client.editMessage('true_<number>@c.us_messageId', 'new text for simple message');
```

--------------------------------

### constructor(public page: Page, session?: string, options?: CreateConfig)

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

Creates a new Whatsapp instance. Normally you don't call this directly; use create() instead. It sets up connection monitoring and page close handling.

```APIDOC
## constructor(public page: Page, session?: string, options?: CreateConfig)

### Description
Creates a new Whatsapp instance. Normally you don't call this directly; use create() instead. It sets up connection monitoring and page close handling.

### Parameters
- **page** (Page) - Required - The browser page running WhatsApp Web
- **session** (string) - Optional - Session name used for tokens/logging
- **options** (CreateConfig) - Optional - Default: `defaultOptions` - See configuration.md

### Behavior
- Registers a `page.on('close')` handler that clears the internal probe timer.
- Starts a 1s `setInterval` polling `WPP.conn.isRegistered()`; whenever the session transitions from registered to unregistered it logs `"Session Unpaired"` and (after 1000 ms) invokes `statusFind('disconnectedMobile', session)` if a `statusFind` callback is configured.
- `afterPageScriptInjected()` (protected override) seeds `this.connected` with the current `WPP.conn.isRegistered()` result after the wapi bundle is injected.
```

--------------------------------

### Build WPPConnect project

Source: https://github.com/wppconnect-team/wppconnect/blob/master/README.md

Build the entire WPPConnect project from the source code.

```bash
> npm run build
```

--------------------------------

### Configure advanced client options

Source: https://github.com/wppconnect-team/wppconnect/blob/master/docs/getting-started/creating-client.md

Pass a configuration object to the create method to customize session behavior, QR handling, and browser settings.

```javascript
wppconnect.create({
    session: 'sessionName', //Pass the name of the client you want to start the bot
    catchQR: (base64Qrimg, asciiQR, attempts, urlCode) => {
      console.log('Number of attempts to read the qrcode: ', attempts);
      console.log('Terminal qrcode: ', asciiQR);
      console.log('base64 image string qrcode: ', base64Qrimg);
      console.log('urlCode (data-ref): ', urlCode);
    },
    statusFind: (statusSession, session) => {
      console.log('Status Session: ', statusSession); //return isLogged || notLogged || browserClose || qrReadSuccess || qrReadFail || autocloseCalled || disconnectedMobile || deleteToken
      //Create session wss return "serverClose" case server for close
      console.log('Session name: ', session);
    },
    onLoadingScreen: (percent, message) => {
      console.log('LOADING_SCREEN', percent, message);
    },
    headless: true, // Headless Chrome
    devtools: false, // Open devtools by default
    useChrome: true, // If false will use Chromium instance
    debug: false, // Opens a debug session
    logQR: true, // Logs QR automatically in terminal
    browserWS: '', // If you want to use browserWSEndpoint
    browserArgs: [''], // Parameters to be added into the Chrome browser instance
    puppeteerOptions: {}, // Will be passed to puppeteer.launch
    disableWelcome: false, // Option to disable the welcoming message which appears in the beginning
    updatesLog: true, // Logs info updates automatically in terminal
    autoClose: 60000, // Automatically closes the wppconnect only when scanning the QR code (default 60 seconds, if you want to turn it off, assign 0 or false)
    tokenStore: 'file', // Define how to work with tokens, which can be a custom interface
    folderNameToken: './tokens', //folder name when saving tokens
    // BrowserSessionToken
    // To receive the client's token use the function await client.getSessionTokenBrowser()
    sessionToken: {
      WABrowserId: '"UnXjH....."',
      WASecretBundle: '{"key":"+i/nRgWJ....","encKey":"kGdMR5t....","macKey":"+i/nRgW...."}',
      WAToken1: '"0i8...."',
      WAToken2: '"1@lPpzwC...."',
    }
  })
  .then((client) => client.start())
  .catch((error) => console.log(error));
```

--------------------------------

### sendReadStatus usage example

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/status-layer.md

JavaScript example that marks a status story as seen using the contact chatId and the status message id.

```javascript
await client.sendReadStatus('[phone_number]@c.us', 'false_status@broadcast_3A169E0FD4BC6E92212F_[]@c.us');
```

--------------------------------

### Basic create() with QR code and message handling

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/create.md

Initializes a WhatsApp bot session with the object form of create(). Sets headless to false, disables auto-close, and logs QR code scan attempts. The client responds to 'ping' messages with 'pong'.

```javascript
const { create } = require('@wppconnect-team/wppconnect');

create({
  session: 'support-bot',
  headless: false,
  autoClose: 0, // disable auto close
  catchQR: (qrBase64, asciiQR, attempt) => {
    console.log(`Scan attempt ${attempt}`);
    console.log(asciiQR);
  },
  statusFind: (status, session) => console.log(status, session),
})
  .then((client) => {
    client.onMessage((message) => {
      if (message.body === 'ping' && !message.fromMe) {
        client.sendText(message.from, 'pong');
      }
    });
  })
  .catch((err) => console.error('create failed', err));
```

--------------------------------

### Initializer callbacks and CreateOptions

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/types.md

Defines callback types for QR code handling, status updates, and stream events, along with the configuration options for creating a session.

```typescript
export type CatchQRCallback = (qrCode: string, asciiQR: string, attempt: number, urlCode?: string) => void;
export type StatusFindCallback = (status: StatusFind | keyof typeof StatusFind, session: string) => void;
export type LoadingScreenCallback = (percent: number, message: string) => void;
export type OnStreamModeCallback = (mode: StreamMode) => void;
export type OnStreamInfoCallback = (info: StreamInfo) => void;
export type LinkByCodeCallback = (code: string) => void;
export interface CreateOptions extends CreateConfig { session?: string; catchQR?: CatchQRCallback; catchLinkCode?: LinkByCodeCallback; statusFind?: StatusFindCallback; onLoadingScreen?: LoadingScreenCallback; onStreamModeChanged?: OnStreamModeCallback; onStreamInfoChanged?: OnStreamInfoCallback; browserSessionToken?: SessionToken; }
```

--------------------------------

### GET /getconnectionstatus

Source: https://github.com/wppconnect-team/wppconnect/blob/master/examples/rest/README.md

Retrieves the current connection status with WhatsApp.

```APIDOC
## GET /getconnectionstatus

### Description
Retrieves the current connection status with WhatsApp.

### Method
GET

### Endpoint
http://127.0.0.1:3000/getconnectionstatus
```

--------------------------------

### Message and ack tracking

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/listener-layer.md

Example of tracking messages and acknowledgements with disposable handles.

```javascript
// Message + ack tracking with disposable handles
create({ session: 'events' }).then((client) => {
  const msgSub = client.onMessage((message) => {
    console.log(message.from, message.body);
  });

  const ackSub = client.onAck((ack) => {
    console.log('ack', ack.id._serialized, ack.ack);
  });

  // stop listening after 5 minutes
  setTimeout(() => { msgSub.dispose(); ackSub.dispose(); }, 5 * 60 * 1000);
});
```

--------------------------------

### Filtered presence and call rejection

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/listener-layer.md

Example of filtering presence changes and rejecting incoming calls.

```javascript
// Filtered presence + incoming call rejection
create({ session: 'events' }).then((client) => {
  client.onPresenceChanged(['5521999999999@c.us'], (event) => {
    console.log(event.id, event.state);
  });

  client.onIncomingCall((call) => {
    console.log('incoming call', call.id, call.isVideo);
    client.rejectCall(call.id).catch(console.error);
  });
});
```

--------------------------------

### getProducts

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/catalog-layer.md

Loads a specified number of products for a given business profile.

```APIDOC
## getProducts

### Description
Loads `qnt` products of business profile `id`.

### Method
getProducts

### Signature
```typescript
public async getProducts(id: string, qnt: number)
```

### Parameters
- **id** (string) - Required - Business profile id (e.g., '00000@c.us')
- **qnt** (number) - Required - Number of products to load

### Request Example
```javascript
const products = await client.getProducts('5521988556558@c.us', 10);
```

### Response
No explicit response documented.
```

--------------------------------

### Get Block List

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/retriever-layer.md

Returns serialized blocked ids: WPP.blocklist.all().map((b) => b.toString()).

```typescript
public async getBlockList()
```

--------------------------------

### sendGif

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/sender-layer.md

Sends a GIF by converting the input to MP4-GIF via ffmpeg and then sending it. Requires ffmpeg to be installed.

```APIDOC
## sendGif

### Description
Sends a GIF by converting the input to MP4-GIF via ffmpeg and then sending it. Requires ffmpeg to be installed.

### Method
async

### Signature
public async sendGif(to: string, filePath: string, filename?: string, caption?: string)

### Parameters
- **to** (string) - Required - The recipient ID.
- **filePath** (string) - Required - Path or URL to the video file.
- **filename** (string) - Optional - The filename to use.
- **caption** (string) - Optional - Caption for the message.

### Notes
Converts to MP4-GIF via ffmpeg (`convertToMP4GIF`) then sends. Throws an error if ffmpeg is not available.
```

--------------------------------

### createProduct

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/catalog-layer.md

Creates a new product in the WhatsApp Business catalog. Requires a business account.

```APIDOC
## createProduct

### Description
Creates a new product in the WhatsApp Business catalog.

### Method
createProduct

### Signature
```typescript
public async createProduct(
  name: string,
  image: string,
  description: string,
  price: number,
  isHidden: boolean,
  url: string,
  retailerId: string,
  currency: string
)
```

### Parameters
- **name** (string) - Required - Product name
- **image** (string) - Required - Image (base64)
- **description** (string) - Required - Product description
- **price** (number) - Required - Product price
- **isHidden** (boolean) - Required - Catalog visibility
- **url** (string) - Required - Product URL
- **retailerId** (string) - Required - Your own product id in your system
- **currency** (string) - Required - e.g. 'BRL'

### Request Example
```javascript
await client.createProduct(
  'Product name',
  'image in base64',
  'product description',
  89.9,
  true,
  'https://wppconnect.io',
  'AKA001'
);
```

### Response
No explicit response documented.
```

--------------------------------

### Get List Mutes

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/retriever-layer.md

Returns mute lists (WAPI.getListMute(type)). The type parameter can be 'all', 'toMute', or 'noMute'.

```typescript
public async getListMutes(type?: string): Promise<object>
```

--------------------------------

### waitForQrCodeScan method signature

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/host-layer.md

Polls needsToScan every 200 ms until logged in, page closed, or throws if session not started.

```typescript
public async waitForQrCodeScan()
```

--------------------------------

### close method signature

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

Closes the page and browser, returning true. Marked @internal, and typically wrapped in try/catch in example.

```typescript
public async close()
```

--------------------------------

### waPage (getter)

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/whatsapp.md

Gets the underlying puppeteer Page instance for advanced operations like waitForSelector, screenshot, or manual evaluate calls.

```APIDOC
## waPage (getter)

### Description
Gets the underlying puppeteer Page instance for advanced operations like waitForSelector, screenshot, or manual evaluate calls.

### Returns
The puppeteer Page instance.
```

--------------------------------

### Catching WhatsApp reported errors

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/errors.md

Example of catching errors from methods like sendText and checking the erro property to handle WhatsApp-reported issues.

```javascript
try {
  await client.sendText(to, 'hello');
} catch (err) {
  if (err && err.erro === true) {
    console.error('WhatsApp reported an error:', err.text);
  }
}
```

--------------------------------

### Phone-number linking with expiry handling

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/api-reference/host-layer.md

This example shows how to link a phone number by providing a phoneNumber and a catchLinkCode callback, and how to refresh the link code after it expires.

```javascript
// Phone-number linking with expiry handling
create({ session: 'host', phoneNumber: '5521987654321', catchLinkCode: (code) =>
  console.log('Link code:', code)
}).then(async (client) => {
  // when "Login by code expired" is logged:
  setTimeout(() => client.refreshLinkCode().then(console.log), 60000);
});
```

--------------------------------

### Use custom winston logger

Source: https://github.com/wppconnect-team/wppconnect/blob/master/_autodocs/configuration.md

Shows how to pass a custom winston logger to the create() function. The logger option accepts any winston Logger; the default is defaultLogger, a console logger with custom npm levels and a [session:type] label prefix.

```javascript
const winston = require('winston');
const { create } = require('@wppconnect-team/wppconnect');

create({
  session: 'log-demo',
  logger: winston.createLogger({
    level: 'info',
    transports: [new winston.transports.File({ filename: 'bot.log' })],
  }),
});
```
Tokens:
Raw