roleewasap

roleewasap

Warning This project can stop working without notice since a core dependency has been removed from GitHub and NPM.

Send WhatsApp messages from the command-line, see also this Medium post.

This project is based on Baileys, a full-featured WhatsApp Web+Multi-Device API library (in case you're wondering about the name, a roleewasap is a Baileys cocktail).

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

Installation

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

npx roleewasap@latest -V

this should display the version number of the latest release.

Using npm roleewasap can be installed globally as follows:

npm install -g roleewasap

Platform binaries

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

Docker

roleewasap can also run inside a Docker container, you can build the Docker image using the supplied Dockerfile:

docker build -t roleewasap .

Test if the build was successful:

docker run -it roleewasap

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

docker run -v /home/<USERNAME>/.local/share/roleewasap:/usr/src/app/cache login

Usage

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

npx roleewasap@latest --help

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

Running behind a proxy server

When the global option --proxy is used, roleewasap 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 roleewasap@latest --proxy login

Login

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

npx roleewasap@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 roleewasap.

Logout

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

npx roleewasap@latest logout

Different types of recipients

roleewasap 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 roleewasap@latest send me 'hello world'

To send a message to a phone number:

npx roleewasap@latest send 3161234567890 'hello world'

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

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

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

npx roleewasap@latest send me 'hello\nworld'

Footer text

Use the --footer option to include a footer text with your message:

npx roleewasap@latest send me 'hello\nworld' --footer 'Bye!'

Buttons

Use the -b/button option to include a button with your message. This option can be used multiple times:

npx roleewasap@latest send [e-mail] 'Everyone ready?' -b 'yes' -b 'no'

Sending an image file

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

npx roleewasap@latest send-image me image.png

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

Image captions

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

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

Sending other files

Single files can be sent to individuals or groups:

npx roleewasap@latest send-file me test.json

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

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 roleewasap@latest send-location me 48.858222 2.2945

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

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

List your groups

To list all the groups you are participating in:

npx roleewasap@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 roleewasap@latest add-to-group [e-mail] 3161234567890

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

Show current user details

To get the WhatsApp ID of the logged in user:

npx roleewasap@latest me

Configuration

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

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

Troubleshooting

In case roleewasap 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 roleewasap can be incrased with the global option -v. Use -vvv for the greatest level of detail:

npx roleewasap@latest -vvv me

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/roleewasap/issues

Contributing

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