sulla

Sulla

Sulla is a javascript library which provides a high-level API control to Whatsapp so it can be configured to automatize responses or any data that goes through Whatsapp effortlessly.

It is built using puppeteer

Sulla state

As of version 2.3.5 it seems that sulla has reached a very rich and stable functionality and architecture. As much as I would love to, I cannot dedicate a lot of time to this project so please consider checking out forked versions of sulla where other developers can dedicate more time and support to it.

Recommended actively supported sulla-based projects:

venom

wppconnect

open-wa/wa-automate

Installation

> npm i sulla --save

Getting started

// Supports ES6
// import { create, Whatsapp } from 'sulla';
const sulla = require('sulla');

sulla.create().then((client) => start(client));

function start(client) {
  client.onMessage((message) => {
    if (message.body === 'Hi') {
      client.sendText(message.from, ' Hello from sulla!');
    }
  });
}

After executing create() function, sulla will create an instance of whatsapp web. If you are not logged in, it will print a QR code in the terminal. Scan it with your phone and you are ready to go!

Sulla will remember the session so there is no need to authenticate everytime.

Multiples sessions can be created at the same time by pasing a session name to create() function:

// Init sales whatsapp bot
sulla.create('sales').then((salesClient) => {...});

// Init support whatsapp bot
sulla.create('support').then((supportClient) => {...});

Optional create parameters

Sulla create() method third parameter can have the following optional parameters:

create('sessionName', qrCallback, {
  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
  browserArgs: [''] // Parameters to be added into the chrome browser instance
  refreshQR: 15000, // Will refresh QR every 15 seconds, 0 will load QR once. Default is 30 seconds
});

The type definition con be found in here: CreateConfig.ts

Exporting QR code

By default QR code will appear on the terminal. If you need to pass the QR somewhere else heres how:

const fs = require('fs');

// Second create() parameter is the QR callback
sulla.create('session-marketing', (base64Qr, asciiQR) => {
  // To log the QR in the terminal
  console.log(asciiQR);

  // To write it somewhere else in a file
  exportQR(base64Qr, 'marketing-qr.png');
});

// Writes QR in specified path
function exportQR(qrCode, path) {
  qrCode = qrCode.replace('data:image/png;base64,', '');
  const imageBuffer = Buffer.from(qrCode, 'base64');

  // Creates 'marketing-qr.png' file
  fs.writeFileSync(path, imageBuffer);
}

Downloading files

Puppeteer takes care of the file downloading. The decryption is being done as fast as possible (outruns native methods). Supports big files!

import fs = require('fs');
import mime = require('mime-types');

client.onMessage(async (message) => {
  if (message.isMedia) {
    const buffer = await client.downloadFile(message);
    // At this point you can do whatever you want with the buffer
    // Most likely you want to write it into a file
    const fileName = `some-file-name.${mime.extension(message.mimetype)}`;
    fs.writeFile(fileName, buffer, function (err) {
      ...
    });
  }
});

Basic functions (usage)

Not every available function is listed, for further look, every function available can be found in here and here

Chatting

Here, chatId could be @c.us or [email protected]

…

Retrieving data

…

Group functions

…

Profile functions

// Set client status
await client.setProfileStatus('On vacations! ✈️');

// Set client profile name
await client.setProfileName('Sulla bot');

Device functions

// Get device info
await client.getHostDevice();

// Get connection state
await client.getConnectionState();

// Get battery level
await client.getBatteryLevel();

// Is connected
await client.isConnected();

// Get whatsapp web version
await client.getWAVersion();

Events

…

Other

// Delete chat
await client.deleteChat(chatId);

// Clear chat messages
await client.clearChat(chatId);

// Delete message (last parameter: delete only locally)
await client.deleteMessage(chatId, message.id.toString(), false);

// Retrieve a number profile / check if contact is a valid whatsapp number
const profile = await client.getNumberProfile('[email protected]');

Misc

There are some tricks for a better usage of sulla.

Keep session alive:

// In case of being logged out of whatsapp web
// Force it to keep the current session
// State change
client.onStateChange((state) => {
  console.log(state);
  const conflits = [
    sulla.SocketState.CONFLICT,
    sulla.SocketState.UNPAIRED,
    sulla.SocketState.UNLAUNCHED,
  ];
  if (conflits.includes(state)) {
    client.useHere();
  }
});

Send message to new contacts (non-added)

Also see Whatsapp links Be careful since this can pretty much could cause a ban from Whatsapp, always keep your contacts updated!

await client.sendMessageToId('[email protected]', 'Hello from sulla! ');

Multiple sessions

If you need to run multiple sessions at once just pass a session name to create() method.

async () => {
  const marketingClient = await sulla.create('marketing');
  const salesClient = await sulla.create('sales');
  const supportClient = await sulla.create('support');
};

Closing (saving) sessions

Close the session properly to ensure the session is saved for the next time you log in (So it wont ask for QR scan again). So instead of CTRL+C,

// Catch ctrl+C
process.on('SIGINT', function() {
  client.close();
});

// Try-catch close
try {
   ...
} catch (error) {
   client.close();
}

Debugging

Development

Building sulla is really simple altough it contians 3 main projects inside

1. Wapi project

> npm run build:wapi

1. Middleeware

> npm run build:build:middleware
> npm run build:jsQR

1. Sulla

> npm run build:sulla

To build the entire project just run

> npm run build

Maintainers

Maintainers are needed, I cannot keep with all the updates by myself. If you are interested please open a Pull Request.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.