This package has been deprecated

Author message:

WARNING: This project has been renamed to @open-wa/wa-automate. Install using @open-wa/wa-automate instead.

sulla-hotfix

Sulla-hotfix is the most advanced NodeJS library which provides a high-level API control to Whatsapp.

It is built using puppeteer, based on this python wrapper and is an extension of the work done in this base project

Installation

> npm i --save sulla-hotfix

Usage

// import { create, Whatsapp } from 'sulla-hotfix';
const sulla = require('sulla-hotfix');
 
sulla.create().then(client => start(client));
 
function start(client) {
  client.onMessage(message => {
    if (message.body === 'Hi') {
      client.sendText(message.from, '👋 Hello!');
    }
  });
}

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-hotfix will remember the session so there is no need to authenticate everytime.

Functions list

Function	Description	Implemented
Receive message		✅
Automatic QR Refresh		✅
Send text		✅
Get contacts		✅
Get chats		✅
Get groups		✅
Get group members		✅
Send contact		✅
Get contact detail		✅
Send Images (image)		✅
Send media (audio, doc)		✅
Send media (video)		✅
Send stickers		✅
Decrypt media (image, audio, doc)		✅
Capturing QR Code		✅
Multiple Sessions		✅
[Last seen & isOnline (beta)]		✅
📍 SEND LOCATION!! (beta)		✅
Simulated '...typing'		✅
Send GIFs!		✅
Forward Messages		✅
Listen to Read Receipts		✅
Listen to Live Locations		✅
Group participant changes		✅
Create Groups		✅
add, remove, promote, demote participants		✅

Checkout all the available functions here.

Starting a conversation

There are 3 ways to start a chat with a new number:

1. WhatsApp Links

   You can send a special link to the person you want to start a chat with. This will open a conversation with your number on their phone. This way you can insure that they have explicitly started a conversation with you.

2. WhatsApp Buttons

   You can add this button to your website which, when clicked, will open a chat with you in the same way as above.

3. With a License Key

   In order to unlock the functionality to send texts to unknown numbers through sulla-hotfix itself, you will need an License key.

   One License Key is valid for one number. Each License Key is £5 per month or £50 per year.

   For now the process happens through Buy Me A Coffee (BMAC)

   How to get an License key:

   1. Go to BMAC.

   2. Click on 'Membership'.

   3. Select your payment preference (monthly/annually).

   4. Add the phone number you want to assign to the License Key in the notes, along with the use case for this functionality

   5. Select "Make this message private."

      

   6. Complete the process for membership.

   7. You will receive your License key via email.

   8. Add licenseKey to your config:

   ...
   create({
     licenseKey: "..."
   })
   ...

   Notes:

   • You can change the number assigned to a specific License Key at any time.
   • In order to cancel your License Key, simply stop your membership.
   • Apart from adding your licenseKey to your config, you will need to change nothing else in your code.
   • An added benefit for members is priority on issues.

Running the demo

You can clone this repo and run the demo, but you will need to use typescript/ts-node:

> git clone https://github.com/smashah/sulla.git
> cd sulla
> npm i
> npm i -g ts-node typescript
> cd demo
> ts-node index.ts

Capturing QR Code

An event is emitted every time the QR code is received by the system. You can grab hold of this event emitter by importing ev

import { ev } from 'sulla-hotfix';
const fs = require('fs');
 
ev.on('qr.**', async qrcode => {
  //qrcode is base64 encoded qr code image
  //now you can do whatever you want with it
  const imageBuffer = Buffer.from(
    qrcode.replace('data:image/png;base64,', ''),
    'base64'
  );
  fs.writeFileSync('qr_code.png', imageBuffer);
});

You can see a live implementation of this on demo/index.ts. Give it a spin! :D

Refreshing QRCode

In version v1.6.13^, sulla can refresh the QR code every 10 seconds (you can change the interval).

create('session',{
    autoRefresh:false, //default to true
    qrRefreshS:30 //please note that if this is too long then your qr code scan may end up being invalid. Generally qr codes expire every 15 seconds.
}).then(async client => await start(client));

Kill the session

As of v1.6.6^ you can now kill the session when required. Best practice is to manage trycatch-es yourself and kill the client on catch.

try{
...
await client.sendMessage(...
...
} catch(error){
client.kill();
//maybe restart the session then
}

Force Refocus and reacting to state

When a user starts using whatsapp web in a different browser, sulla-hotfix will be left on a screen prompting you to click 'Use here'. As of v1.6.6^ you can now force the client to press 'Use here' everytime the state has changed to 'CONFLICT'. onStateChanged results in 'UNPAIRED', 'CONNECTED' or 'CONFLICT';

client.onStateChanged(state=>{
    console.log('statechanged', state)
    if(state==="CONFLICT") client.forceRefocus();
  });
 

Decrypting Media

Here is a sample of how to decrypt media. This has been tested on images, videos, documents, audio and voice notes.

import { create, Whatsapp, decryptMedia } from 'sulla-hotfix';
const mime = require('mime-types');
const fs = require('fs');
 
function start(client: Whatsapp) {
  client.onMessage(async message => {
    if (message.mimetype) {
      const filename = `${message.t}.${mime.extension(message.mimetype)}`;
      const mediaData = await decryptMedia(message);
      const imageBase64 = `data:${message.mimetype};base64,${mediaData.toString(
        'base64'
      )}`;
      await client.sendImage(
        message.from,
        imageBase64,
        filename,
        `You just sent me this ${message.type}`
      );
      fs.writeFile(filename, mediaData, function(err) {
        if (err) {
          return console.log(err);
        }
        console.log('The file was saved!');
      });
    }
  });
}
 
create().then(client => start(client));

It is always preferable to keep projects smaller than needed so you can now use a lightweight library called wa-decrypt for projects that do not need all of sulla-hotfix.

You can install that using:

> npm i --save wa-decrypt

and import it like so:

import { decryptMedia } from 'wa-decrypt';

Learn more about wa-decrypt here

Issues with decyption

If you are having issues with decryption it may be due to the user agent being used by the decrypt method. You can remedy this by passing a custom user agent as a second parameter to the decrypt method. Now there is a convenience method on the WhatsApp class to allow you to easily get a compatible user agent shown below. This feature is available in v.1.5.8 and above.

...
      const generatedUa = await client.getGeneratedUserAgent(); //you can optionally pass your custom user agent in here also getGeneratedUserAgent('...');
      const mediaData = await decryptMedia(message,generatedUa);
...

Sending Media/Files

Here is a sample of how to send media. This has been tested on images, videos, documents, audio and voice notes.

Interestingly sendImage has always worked for sending any type of file.

An example of sending a is shown in the Decrypting Media secion above also.

import { create, Whatsapp} from 'sulla-hotfix';
 
function start(client: Whatsapp) {
await client.sendFile('[e-mail]',[BASE64 FILE DATA],'some file.pdf', `Hello this is the caption`);
}
 
create().then(client => start(client));

Please note sometimes short(<4s) voice notes sometimes do not decrypt properly and result in empty audio files.

Sending Video

If you intend to use video via sulla-hotfix, you need to use a chrome instance with puppeteer instead of the default chromium instance. This is becase chromium does not have any relevant video codecs needed for new whatsapp web video sending features.

You will need to make sure that you have a valid chrome instance on your machine then use the following to tell puppeteer where it can find your chrome isntance. The below demo is an example for mac & windows. For linux based hosts, you can find the chrome path with whereis google-chrome, it should be something like /usr/bin/google-chrome

 
create('session',{
  // For Mac:
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  // For Windows:
  // executablePath: 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
}).then(client => start(client));
 

Sending Gifs

Extending the functionality of sending videos, version 1.4.2 brings with it the ability to send GIFs!!!! This was super annoying to figure out, as I was sent on a wild goose chase but it turned out that the answer was just 2 simple lines.

There are two ways to send GIFs - by Video or by giphy link.

1. Sending Video as a GIF.

WhatsApp doesn't actually support the .gif format - probably due to how inefficient it is as a filetype - they instead convert GIFs to video then process them.

In order to send gifs you need to do the same (convert the gif to an mp4 file) then use the following method:

 
import { create, Whatsapp} from 'sulla-hotfix';
 
function start(client: Whatsapp) {
await client.sendVideoAsGif('[e-mail]',[BASE64 Video FILE DATA],'some file.mp4', `Hello this is the caption`);
}
 
///IMPORTANT! Please make sure to point to your chrome installation and make sure your host has ffmpeg support
create('session',{
  // For Mac:
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  // For Windows:
  // executablePath: 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
}).then(client => start(client));
 

1. Sending a Giphy Media Link

This is a convenience method to make it easier to send gifs from the website GIPHY. You need to make sure you use a giphy media link as shown below.

 
import { create, Whatsapp} from 'sulla-hotfix';
 
function start(client: Whatsapp) {
await client.sendGiphy('[e-mail]','https://media.giphy.com/media/oYtVHSxngR3lC/giphy.gif', `Hello this is the caption`);
}
 
create('session',{
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
}).then(client => start(client));
 

Sending Location

As of version 1.3.0 you can now send location!! You can't even do this in normal whatsapp web interface.

You need to pass the following params:

• chat id: [e-mail]
• latitude: '51.5074'
• longitude: '0.1278'
• location text: 'LONDON!'

Here's how you do it:

await client.sendLocation('[e-mail]', '51.5074', '0.1278',  'LONDON!')

Simulate typing

As of version 1.3.1 you can now simulate '...typing'

You need to pass the following params:

• chat id: [e-mail]
• on: true or false

Note: You need to manually turn this off!!!

//start '...typing'
await client.simulateTyping('[e-mail]',true)
//wait 3 seconds
 
//stop '...typing'
await client.simulateTyping('[e-mail]',false)

Load profile pics from server

Generally, after the 20th chat in your whatsapp, getChat methods do not retreive the chat picture. You need to get these from the WhatsApp servers. This is how you do it in v1.6.6^:

client.getProfilePicFromServer('[e-mail]')

Forward Messages

As of version 1.5.1 you can now forward messages. This has been tested on most types of messages.

You need to pass the following params:

• chat to forward messages to : [e-mail]
• messages: a single or array of message ids or message objects
• skipMyMessages: true or false, if true it will filter out messages sent by you from the list of messages, default false.

Note: You need to manually turn this off!!!

//forward messages
await client.forwardMessages('[e-mail]',[...],true)
 
//forward single message by id
await client.forwardMessages('[e-mail],"...",true)

Reply to messages

As of version 1.6.17, you can now reply to specific messages.

...
/**
   * @param to string chatid
   * @param content string reply text
   * @param quotedMsg string | Message the msg object or id to reply to.
   */
 
      await client.reply('[e-mail]','This is the reply',message);
...

Create group

As of v1.7.2 you can now create a new group. The first parameter is the group name, the second parameter is the contact ids to add as participants

...
  client.createGroup('Cool new group','[e-mail]') //you can also send an array of ids.
...

Group participants [beta]

As of v1.7.0 you can now add, remove, promote & demote participants for groups. The first parameter is the chat id for the group. The second parameter is the number to which you are conducting the action.

...
  client.addParticipant('[e-mail]','[e-mail]')
  client.removeParticipant('[e-mail]','[e-mail]')
  client.promoteParticipant('[e-mail]','[e-mail]')
  client.demoteParticipant('[e-mail]','[e-mail]')
...

Group participant changes

As of version 1.5.6 you can now listen in on changes to group participants. You can react to when participants are added and removed.

client.onParticipantsChanged("[e-mail]", (participantChangedEvent:any) => console.log("participant changed for group", participantChangedEvent));
 
//participantChangedEvent returns
{
  by: '[e-mail]', //who performed the action
  action: 'remove',
  who: [ '[e-mail]' ] //all the numbers the action effects.
}

This solution can result in some false positives and misfires however a lot of effort has been made to mitigate this to a reasonable level. Best practice is to maintian a seperate registry of participants and go from that.

Listen to Live Locations

As of version 1.7.21 you can now listen to live locations from a specific chat. You can see the liveLocation callback object here

 
client.onLiveLocation('[e-mail]', (liveLocation) => {
  console.log('Someone moved',liveLocation)
})
 

Listen to Read Receipts

As of version 1.5.3 you can now listen in on the read state (or technically acknowledgement state) of the messages. As of writing the limitation is presumed to be on sent messages.

The callback you set returns the whole raw message object.

Here's how you do it.

client.onAck((msg:any) => console.log(msg.id.toString(),msg.body,msg.ack))

ack represents the acknoledgement state, of which there are 3.

1 => Message Sent (1 tick)
 
2 => Message Received by Recipient (2 ticks)
 
3 => Message Read Receipt Confirmed (2 blue ticks)

Note: You won't get 3 if the recipient has read receipts off.

Timing out an unpaired session

If you want to kill the process after a certain amount of seconds due to an unscanned code, you can now set the killTimer parameter in the configuration object.

create('session',
{
  killTimer: 30 //kills the session if the QR code is not scanned within 30 seconds.
})
.then(client => start(client));

Managing multiple sessions at once

With v1.2.4, you can now run multiple sessions of sulla-hotfix in the same 'app'. This allows you to do interesting things for example:

1. Design and run automated tests for you WA bot.
2. Connect two or more whatsapp numbers to a single (or multiple) message handler(s)
3. Use one client to make sure another one is alive by pinging it.

Please see demo/index.ts for a working example

NOTE: DO NOT CREATE TWO SESSIONS WITH THE SAME SESSIONID. DO NOT ALLOW SPACES AS SESSION ID.

import { create, Whatsapp} from 'sulla-hotfix';
 
function start(client: Whatsapp) {
  ...
}
 
create().then(client => start(client));
 
create('another_session').then(client => start(client));

You can then capture the QR Code for each session using the following event listener code:

//events are fired with the ev namespace then the session Id. e.g "qr.another_session"
//You can however use the wildcard operator with the new event listener and capture the session Id as a parameter instead.
ev.on('qr.**', async (qrcode,sessionId) => {
  console.log("TCL: qrcode,sessioId", qrcode,sessionId)
  //base64 encoded qr code image
  const imageBuffer = Buffer.from(qrcode.replace('data:image/png;base64,',''), 'base64');
  fs.writeFileSync(`qr_code${sessionId?'_'+sessionId:''}.png`, imageBuffer);
});

Manage page errors

Since this project is built upon puppeteer, you can access the Puppeteer Page instance by referencing client.page, and then therefore you can listen to any errors on the page like so:

client.page.on('error', _=>{
...
}

Custom Set Up

With v.1.2.6 you can now forward custom arguments through the library to puppeteer. This includes any overrides to the pupeteer config and a custom useragent.

Note: If you want to change the user agent but leave the puppeteer config the same then just pass {} to the pupeteer config. Also if you don't want to use a custom session then just use 'session' for the first argument.

As with session name segment, these are all optional parameters.

Why should you use a custom user agent?

Users of these whatsapp injection libraries should use different user agents (preferably copy the one you have one your own pc) because then it makes it harder for whatsapp to break the mecahnism to restart sessions for this library.

Setting up your client in headless:false mode ensures you can easily visually debug any issues.

Example:

import { create, Whatsapp} from 'sulla-hotfix';
 
function start(client: Whatsapp) {
  ...
}
 
create().then(client => start(client));
 
//1st argument is the session name
//2nd argument is the puppeteer config override
//3rd argument is the user agent override
 
create('session',
{
  headless: false
},
'some custom user agent')
.then(client => start(client));

Best Practice

Since this is not an officially sanctioned solution it is tempermental to say the least. Here are some best practices:

1. Keep the session alive
2. Offload most work off of your sulla-hotfix setup (i.e forward all events to a pubsub or something)
3. Keep the phone nearby just in case you need to reauthenticate
4. Use a chrome instance instead of the default chromium instance
5. Use headless: false for easy & quick visual debugging
6. Implement the unread messages functionality on creation of a session so you don't miss any messages upon any downtime.
7. Implement a promise-queue
8. Use a unique and valid custom user-agent
9. await all sulla-hotfix methods just in case
10. Do not run your sulla-hotfix instance on a Windows machine.
11. Always kill the session safely upon error or SIGINT.

import { create, Whatsapp} from 'sulla-hotfix';
const { default: PQueue } = require("p-queue");
 
const queue = new PQueue({
  concurrency: 4,
  autoStart:false
   });
 
const proc = async message => {
  //do something with the message here
    console.log(message)
    return true;
}
 
const processMessage = message => queue.add(proc(message));
 
async function start(client: Whatsapp) {
  const unreadMessages = await client.getAllUnreadMessages();
  unreadMessages.forEach(processMessage)
  ...
  await client.onMessage(processMessage);
  queue.start();
}
 
create().then(client => start(client));
 
//1st argument is the session name
//2nd argument is the puppeteer config override
//3rd argument is the user agent override
 
create('session',
{
  // For Mac:
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  // For Windows:
  // executablePath: 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
  headless: false,
  autoRefresh:true
},
'some custom user agent')
.then(client => start(client));

Contributing

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

License

Hippocratic + Do Not Harm Version 1.0

Legal

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by WhatsApp or any of its affiliates or subsidiaries. This is an independent and unofficial software. Use at your own risk.

Cryptography Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.