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.
Send WhatsApp messages from the command-line π―
For an introduction please read 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 Mudslide is a Baileys cocktail).
Keep in mind that the working of Mudslide 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
Using npx
, installation is not necessary. You can run Mudslide on a system
with NodeJS 16 or higher from the command-line as follows:
npx mudslide@latest -V
this should display the version number of the latest release.
Using npm
Mudslide can be installed globally as follows:
npm install -g mudslide
Binaries for different platforms (Linux, Windows) are available on the latest release page.
Mudslide can also run inside a Docker container:
docker run robvanderleek/mudslide
Since Mudslide keeps authentication state on disk you need to mount a state directory outside the container, for example:
docker run -v $HOME/.local/share/mudslide:/usr/src/app/cache -it robvanderleek/mudslide login
or:
docker run -v $HOME/.local/share/mudslide:/usr/src/app/cache robvanderleek/mudslide me
You can build the Docker image using the supplied Dockerfile
:
docker build -t mudslide .
Test if the build was successful:
docker run -it mudslide
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 mudslide
Since Mudslide keeps authentication state on disk you need to mount a state
directory outside the container, for example in ~/.local/share/mudslide
:
See respective lines in docker-compose.yml
volumes:
- ~/.local/share/mudslide:/usr/src/app/cache
Available commands and options can be listed with --help
flag:
npx mudslide@latest --help
for most command it's necessary that you've authorized Mudslide to interact with the WhatsApp API on your behalf. This can be done by logging in as described below.
To login you need to authorize Mudslide from another device that has WhatsApp installed and scan the QR code printed in the terminal:
npx mudslide@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 Mudslide.
Logging out removes credentials from your local environment but will not disconnect Mudslide from your WhatsApp account, you can disconnect Mudslide using the WhatsApp app.
npx mudslide@latest logout
Muslide supports three types of recipients for sending messages/images/files/etc.:
- An international phone number (e.g.:
3161234567890
) - The authenticated user:
me
- A so-called WhatsApp ID, for example a group ID:
123456789-987654321@g.us
Using the recipient me
you can send yourself a test message:
npx mudslide@latest send me 'hello world'
To send a message to a phone number:
npx mudslide@latest send 3161234567890 'hello world'
To send a message to a group you are particpating in you need the group ID (see
the mudslide groups
command). Send a message to a group as follows:
npx mudslide@latest send 123456789-987654321@g.us 'hello world'
Use \n
to send a message with a newline, for example:
npx mudslide@latest send me 'hello\nworld'
Image files (PNG, JPG, GIF) can be sent to individuals or groups:
npx mudslide@latest send-image me image.png
npx mudslide@latest send-image 123456789-987654321@g.us 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 (")
Use the --caption
option to add a caption to the image:
npx mudslide@latest send-image --caption 'Your text here' me image.png
Single files can be sent to individuals or groups:
npx mudslide@latest send-file me test.json
npx mudslide@latest send-file 123456789-987654321@g.us 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 (")
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 mudslide@latest send-file --type audio 123456789-987654321@g.us music.mp3
Geographic locations can be sent to individuals or groups using latitude and longitude coordinates. For example, to position yourself at the Eiffel Tower:
npx mudslide@latest send-location me 48.858222 2.2945
Or to send your location at the Sydney Opera House to a group:
npx mudslide@latest send-location 123456789-987654321@g.us -33.857058 151.214897
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 mudslide@latest send-poll 123456789-987654321@g.us '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 mudslide@latest send-poll 123456789-987654321@g.us 'Training on Friday' --item 'Yeeeess!' --item 'Nope' --item 'Maybe...'
To list all the groups you are participating in:
npx mudslide@latest groups
this will show a list of group IDs and subjects.
Participants can be added/removed from existing groups as follows:
npx mudslide@latest add-to-group 123456789-987654321@g.us 3161234567890
npx mudslide@latest remove-from-group 123456789-987654321@g.us 3161234567890
Group participants can be listed as follows:
npx mudslide@latest list-group 123456789-987654321@g.us
To get the WhatsApp ID of the logged in user:
npx mudslide@latest me
By default WhatsApp credentials are cached in a folder located in the user's
home directory. This folder is .local/share/mudslide'
on Linux & macOS and
AppData\Local\mudslide\Data
on Windows.
A different location for the cache folder can be configured via the environment
variable MUDSLIDE_CACHE_FOLDER
or the -c
/--cache
options.
When the global option --proxy
is used, Mudslide will use the environment variables HTTP_PROXY
and HTTPS_PROXY
to
proxy all requests. For example:
export HTTP_PROXY=http://USER:PASS@proxy.server.com:80
export HTTPS_PROXY=http://USER:PASS@proxy.server.com:80
npx mudslide@latest --proxy login
In case Mudslide 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 Mudslide can be incrased
with the global option -v
. Use -vvv
for the greatest level of detail:
npx mudslide@latest -vvv me
Mudslide 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.
To run the unit-tests run this command:
yarn test
Please create an issue here: https://github.com/robvanderleek/mudslide/issues
If you like this software, please star β it.
If you have suggestions for how Mudslide could be improved, or want to report a bug, open an issue! All and any contributions are appreciated.
ISC Β© 2022 Rob van der Leek robvanderleek@gmail.com (https://twitter.com/robvanderleek)