Rolee_WhatsApp

[!WARNING] DO NOT USE THIS TOOL FOR IMPORTANT THINGS. This tool can stop working without notice since it depends on libraries that could be removed any time from GitHub/NPM.

Keep in mind that the working of Rolee_WhatsApp depends on the Baileys library and since that is not an official supported library by WhatsApp it could stop working without notice.

• Installation
• Usage
• Configuration
• Troubleshooting
• FAQ
• Development
• Feedback, suggestions and bug reports
• Contributing
• License

Installation

Using npx, installation is not necessary. You can run Rolee_WhatsApp on a system with NodeJS 16 or higher from the command-line as follows:

npx rolee_whatsapp@latest -V

this should display the version number of the latest release.

Using npm rolee_whatsapp can be installed globally as follows:

npm install -g rolee_whatsapp

Platform binaries

Binaries for different platforms (Linux, Windows) are available on the latest release page.

Docker

Rolee_WhatsApp can also run inside a Docker container:

docker run roleesoft/rolee_whatsapp

Since Rolee_WhatsApp keeps authentication state on disk you need to mount a state directory outside the container, for example:

docker run -v $HOME/.local/share/rolee_whatsapp:/usr/src/app/cache -it roleesoft/rolee_whatsapp login

or:

docker run -v $HOME/.local/share/rolee_whatsapp:/usr/src/app/cache roleesoft/rolee_whatsapp me

Build image

You can build the Docker image using the supplied Dockerfile:

docker build -t rolee_whatsapp .

Test if the build was successful:

docker run -it rolee_whatsapp

Docker Compose

If you chose to use docker-compose instead of docker you can build the Docker image using the supplied assets/docker-compose.yml file (which in turn depends on the supplied Dockerfile):

cd assets/
docker-compose build

Test if the build was successful:

docker-compose run rolee_whatsapp

Since Rolee_WhatsApp keeps authentication state on disk you need to mount a state directory outside the container, for example in ~/.local/share/rolee_whatsapp:

See respective lines in docker-compose.yml

    volumes:
        - ~/.local/share/rolee_whatsapp:/usr/src/app/cache

Usage

Available commands and options can be listed with --help flag:

npx rolee_whatsapp@latest --help

for most command it's necessary that you've authorized Rolee_WhatsApp to interact with the WhatsApp API on your behalf. This can be done by logging in as described below.

Login

To login you need to authorize Rolee_WhatsApp from another device that has WhatsApp installed and scan the QR code printed in the terminal:

npx rolee_whatsapp@latest login
█▀▀▀▀▀█ ▀▀   ▀  █ █▀▀▀▀▀█
█ ███ █ █▄ █▀▀▀▀  █ ███ █
█ ▀▀▀ █ ▀█▀▀▄▀█▀▀ █ ▀▀▀ █
▀▀▀▀▀▀▀ ▀▄▀▄▀▄█▄▀ ▀▀▀▀▀▀▀
▀███▄ ▀▄▀▄   ▀▀ █▀ ▄▀▀▀▄▀
█▄▄▄▄ ▀ ▄  ▄▄▄█▄ ▄█▀ ▄▄
▀▄ ▄▀ ▀ ▄█▄█ ▄ ▄ ██▄█ ▀▀█
▄▀▄██▀▀██▄▀ █▄▀▄▄█▀▄█ ▀▀▄
    ▀▀▀ ███▀▄▄  █▀▀▀█▀█▀█
█▀▀▀▀▀█   ▀▀█  ▄█ ▀ █ ▀██
█ ███ █ ▄▄█▀██▄▄▀██▀██▄▄▄
█ ▀▀▀ █ █▀▀▀▀▀ ▀▀█▀ █ █▀
▀▀▀▀▀▀▀ ▀▀▀ ▀ ▀  ▀ ▀▀▀▀▀▀

In the WhatsApp mobile app go to "Settings > Connected Devices > Connect Device" and scan the QR code. Wait until the status is "active", then you can exit Rolee_WhatsApp.

Logout

Logging out removes credentials from your local environment but will not disconnect Rolee_WhatsApp from your WhatsApp account, you can disconnect Rolee_WhatsApp using the WhatsApp app.

npx rolee_whatsapp@latest logout

Different types of recipients

Muslide supports three types of recipients for sending messages/images/files/etc.:

1. An international phone number (e.g.: 3161234567890)
2. The authenticated user: me
3. A so-called WhatsApp ID, for example a group ID: [e-mail]

Sending a message to yourself or a phone number

Using the recipient me you can send yourself a test message:

npx rolee_whatsapp@latest send me 'hello world'

To send a message to a phone number:

npx rolee_whatsapp@latest send 3161234567890 'hello world'

To send a message to a group you are particpating in you need the group ID (see the rolee_whatsapp groups command). Send a message to a group as follows:

npx rolee_whatsapp@latest send [e-mail] 'hello world'

Use \n to send a message with a newline, for example:

npx rolee_whatsapp@latest send me 'hello\nworld'

Sending an image file

Image files (PNG, JPG, GIF) can be sent to individuals or groups:

npx rolee_whatsapp@latest send-image me image.png

npx rolee_whatsapp@latest send-image [e-mail] image.jpg

Note In case there is a space in the path or the file name, enclose the entire path and file name in quotes (")

Image captions

Use the --caption option to add a caption to the image:

npx rolee_whatsapp@latest send-image --caption 'Your text here' me image.png

Sending other files

Single files can be sent to individuals or groups:

npx rolee_whatsapp@latest send-file me test.json

npx rolee_whatsapp@latest send-file [e-mail] document.pdf

Note In case there is a space in the path or the file name, enclose the entire path and file name in quotes (")

File types

By default, files will be sent as "documents" and show as a download link in the chat. The --type option can be used for audio and video files that show as a playable message in the chat:

npx rolee_whatsapp@latest send-file --type audio [e-mail] music.mp3

Sending a location

Geographic locations can be sent to individuals or groups using latitude and longitude coordinates. For example, to position yourself at the Eiffel Tower:

npx rolee_whatsapp@latest send-location me 48.858222 2.2945

Or to send your location at the Sydney Opera House to a group:

npx rolee_whatsapp@latest send-location [e-mail] -33.857058 151.214897

Sending a poll

Polls can be sent to individuals or groups, and allow participants to select 1 or more items.

For example, to send a poll for the summer holiday destination, allowing participants to select 2 items, use:

npx rolee_whatsapp@latest send-poll [e-mail] 'Summer holiday destination' --item 'France' --item 'Spain' --item 'Italy' --item 'Switzerland' --selectable 2

Or to send a quick poll to check who's going training on Friday:

npx rolee_whatsapp@latest send-poll [e-mail] 'Training on Friday' --item 'Yeeeess!' --item 'Nope' --item 'Maybe...'

List your groups

To list all the groups you are participating in:

npx rolee_whatsapp@latest groups

this will show a list of group IDs and subjects.

Add/remove group participants

Participants can be added/removed from existing groups as follows:

npx rolee_whatsapp@latest add-to-group [e-mail] 3161234567890

npx rolee_whatsapp@latest remove-from-group [e-mail] 3161234567890

Show current user details

To get the WhatsApp ID of the logged in user:

npx rolee_whatsapp@latest me

Configuration

By default WhatsApp credentials are cached in a folder located in the user's home directory. This folder is .local/share/rolee_whatsapp' on Linux & macOS and AppData\Local\rolee_whatsapp\Data on Windows.

A different location for the cache folder can be configured via the environment variable ROLEE_WHATSAPP_CACHE_FOLDER or the -c/--cache options.

Running behind a proxy server

When the global option --proxy is used, Rolee_WhatsApp will use the environment variables HTTP_PROXY and HTTPS_PROXY to proxy all requests. For example:

export HTTP_PROXY=http://USER:[e-mail]:80
export HTTPS_PROXY=http://USER:[e-mail]:80
npx rolee_whatsapp@latest --proxy login

Troubleshooting

In case Rolee_WhatsApp does not give any output or does not behave as expected, try removing the local cache folder (see Configuration section), then disconnect the client using your mobile WhatsApp app, and login again.

To see what goes on in more detail, the verbosity of Rolee_WhatsApp can be incrased with the global option -v. Use -vvv for the greatest level of detail:

npx rolee_whatsapp@latest -vvv me

FAQ

How can I read messages?

Rolee_WhatsApp is for sending messages only. If you want to read messages (e.g. when building a chat bot), have a look at the Baileys library.

Development

Running unit-tests

To run the unit-tests run this command:

yarn test

Feedback, suggestions and bug reports

Please create an issue here: https://github.com/roleesoft/rolee_whatsapp/issues

If you like this software, please star ⭐ it.

Contributing

If you have suggestions for how Rolee_WhatsApp could be improved, or want to report a bug, open an issue! All and any contributions are appreciated.

License

ISC © 2022 [e-mail]