Giter Club home page Giter Club logo

sulla's Introduction

Sulla logo

Sulla

npm version npm type definitions GitHub last commit GitHub license

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

It is built using puppeteer and based on this python wrapper

By deafult sulla will try to use Google Chrome driver if installed, if not, it will use integrated Chromium instance

Installation

> npm i sulla

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((salesBot) => {...});

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

Basic functions (usage)

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

Chatting

// Send basic text
await client.sendText(chatId, '๐Ÿ‘‹ Hello from sulla!');

// Send image
await client.sendImage(chatId, 'path/to/img.jpg', 'something.jpg', 'Caption text');

// Send @tagged message
await client.sendMentioned(chatId, 'Hello @5218113130740 and @5218243160777!', ['5218113130740', '5218243160777']);

// Reply to a message
await client.reply(chatId, 'This is a reply!', message.id.toString());

// Send file (sulla will take care of mime types, just need the path)
await client.sendFile(chatId, 'path/to/file.pdf', 'cv.pdf', 'Curriculum');

// Send gif
await client.sendVideoAsGif(chatId, 'path/to/video.mp4', 'video.gif', 'Gif image file');

// Send contact
// contactId: [email protected]
await client.sendContact(chatId, contactId);

// Forwards messages
await client.forwardMessages(chatId, [message.id.toString()], true);

// Send sticker
await client.sendImageAsSticker(chatId, 'path/to/image.jpg');

// Send location
await client.sendLocation(chatId, 25.6801987, -100.4060626, 'Some address, Washington DC', 'Subtitle');

// Send seen โœ”๏ธโœ”๏ธ
await client.sendSeen(chatId);

// Start typing...
await client.startTyping(chatId);

// Stop typing
await client.stopTyping(chatId);

// Set chat state (0: Typing, 1: Recording, 2: Paused)
await client.setChatState(chatId, 0 | 1 | 2)

Group functions

// groupId or chatId: leaveGroup [email protected]

// Leave group
await client.leaveGroup(groupId);

// Get group members
await client.getGroupMembers(groupId);

// Get group members ids
await client.getGroupMembersIds(groupId);

// Generate group invite url link
await client.getGroupInviteLink(groupId);

// Create group (title, participants to add)
await client.createGroup('Group name', ['[email protected]', '[email protected]']);

// Remove participant
await client.removeParticipant(groupId, '[email protected]');

// Add participant
await client.addParticipant(groupId, '[email protected]');

// Promote participant (Give admin privileges)
await client.promoteParticipant(groupId, '[email protected]');

// Demote particiapnt (Revoke admin privileges)
await client.demoteParticipant(groupId, '[email protected]');

// Get group admins
await client.getGroupAdmins(groupId);

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

// Listen to messages
client.onMessage(message => {
  ...
})

// Listen to state changes
client.onStateChange(state => {
  ...
});

// Listen to ack's
client.onAck(ack => {
  ...
});

// Listen to live location
// chatId: '[email protected]'
client.onLiveLocation(chatId, (liveLocation) => {
  ...
});

// Listen to group participant changes
client.onParticipantsChanged(chatId, (participantChange) => {
  ...
});

// Listen when client has been added to a group
client.onAddedToGroup(chatEvent => {
  ...
});

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)

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
client.onStateChange((state) => {
  if (state === 'UNLAUNCHED') {
    client.useHere();
  }
});

Send message to new contacts (non-added)

Also see Whatsapp links

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();
}

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.

License

MIT

sulla's People

Contributors

danielcardeenas avatar greenkeeper[bot] avatar dependabot-preview[bot] avatar zagbutnozig avatar dependabot[bot] avatar

Watchers

James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.