This binding provides access to the WhatsApp messaging service. Initially it will provide full support of text messages. Media files (image / video / audio) will be likely supported, but need more work.

The actual technical interface to WhatsApp is provided by the yowsup project. This is a pearl-based implementation using an inoffcial WhatsApp API. Be ware that this can be shutdown by WhatsApp at any time. The project includes yowsup-cli, which will be started and controlled by the binding. It's imprtant to carefully read the installation notes and make sure that yowsup-cli is running before installing the binding. Otherwise you could expect unpredictable results.

The binding uses the AragurDEV yowsup fork (see below).

Currently the installation is intended for macOS, for Linux some dependencies must be added (install xxx) and Windows is not yet tested.

You need a mobile number, which is not yet registered with WhatsApp, e.g. a prepaid SIM. This is only required once, the SIM is not relevant anymore, but shouldn't be used in a smartphone with WhatsApp at any time.

If you use the yowsup-cli command for registration of a new number, you run the risk of being black-listed by WhatsApp after sending your first message.

To avoid this,

• insert a new SIM
  
• install WhatsApp on the mobile device
  
• Start conversations with several numbers in your address book
  
• do some ping pong with different contacts for 24h-48h
  
• deinstall Whatsapp (you still need the SIM for the registration SMS)
  
• register with yowsup and the registration SMS (see above)
  
• remove SIM from phone (don't use it in parallel to yowsup, e.g. in different phone)
  
• use different phone to send 2 messages to this number from 2 different contacts
  
• start sending messages with yousup - you should them incoming messages on the console
  
• do some ping pong with 2 contacts, e.g. using the yowsup echo client (see below)
  

Important Note:
Be aware not to fix the same phone number (MSISDN) on multiple servers. You need one number per server to avoid those issues!
This could also happen when you start more than once instance on the same system (I suppose that caused the problem on my dev system)

Do not run yowsup in parrallel to the binding!

Preperation on Linux
sudo apt-get update sudo apt-get install libncurses5-dev

Preperation on Mac (needs [Homwbrew](https://www.howtogeek.com/211541/homebrew-for-os-x-easily-installs-desktop-apps-and-terminal-utilities/))
brew install wget --with-libressl
brew install ncurses
brew install freetype imagemagick exiftool ffmpeg pkg-config
brew install libmagic
cd /usr/local/lib/
ln -s ../Cellar/libmagic/5.35/lib/libmagic.dylib libmagic.dylib

Install Python modules:
pip3 install --upgrade pip
pip3 install argparse
pip3 install python-dateutil
pip3 install --upgrade readline
pip3 install protobuf
pip3 install preview-generator
pip3 install xvfbwrapper
pip3 install urllib3
pip3 install idna
pip3 install chardet
pip3 install certifi
pip3 install cryptographypip3 install pycrypto
pip3 install python-axolotl-curve25519
pip3 install --upgrade pillow

Download https://files.pythonhosted.org/packages/ce/17/9eeb6bc3a7cc1dc8ba7db35a2038c61bef49336ec21057258801e9aef2a5/preview_generator-0.9.tar.gz
unzip preview_generator-0.9.tar.gz
phyton3 ./setup.py install

go to the directory where you want to download and build yowsup

clone the repository:
git clone https://github.com/AragurDEV/yowsup.git

don't run setup.py yet!

You need to update the WhatsApp version and a key, otherwise you get error "old_version"!

You find suitable settings under https://coderus.openrepos.net/whitesoft/whatsapp_scratch
{"a": "HVpGIJI3MRi3wZmsvjJDqw==", "b": "PdA2DJyKoUrwLw1Bg6EIhzh502dF9noR9uFCllGk", "c":"1478194306452L", "d":"2.18.355", "e":"2.16.12", "f":"2.11.634", "g":"PdA2DJyKoUrwLw1Bg6EIhzh502dF9noR9uFCllGk", "h":"1478194472015L", "i":"PdA2DJyKoUrwLw1Bg6EIhzh502dF9noR9uFCllGk", "j":"1478194472015L"}

Use parameter a and d and update the file yowsup/env/env_android.py
nano yowsup/env/env_android.py
and change the lines
_MD5_CLASSES = "<hash>"
_VERSION = "<version>"

for example:
_MD5_CLASSES = "HVpGIJI3MRi3wZmsvjJDqw=="
_VERSION = "2.18.355"

Now build and install yowsup_ Linux:
python ./setup.py install

MacOS:
python2 ./setup.py install

You need to lookup Mobile Country Code (MCC), the Mobile Network Code (MNC) and the normal Country Code (CC) you want to use:
Open https://en.wikipedia.org/wiki/Mobile_country_code and look for MCC and MNC. Those identify the mobile network you are using, e.g. MCC=262 for Germany and MNC=1 for Telekom, MNC=2 for VodafoneDE etc.

Run the WhatsApp registration:
yowsup-cli registration -d -E android -m <MCC> -n <MNC> -p <phone number> -C <country code> -r sms

Example: Germany (MCC=262, Country Code=49) and T-Mobile (MNC=1), phone number 491711234567
yowsup-cli registration -d -E android -m 262 -n 1 -p 491711234567 -C 49 -r sms

Make sure to prefix your phone number also with the country code, in this case 49xxxx. Do not include the 0 for the phone number, e.g. 01711234567 becomes 491711234567.
As a result you receive a SMS on your mobile phone. You need the 6 digit registration code in format XXX-XXX sent by WhatsApp. SMS text will be something like:
Your WhatsApp code: XXX-XXX
...

Registration will be completed with the following command:
yowsup-cli registration -d -E android -p <CC><phone number without 0> -C <CC> -R <Registration Code>

for example: yowsup-cli registration -d -E android -p 491711234567 -C 49 -R 123-456

Now you should receive a result like this one:
status: ok
kind: free
pw: <password>
price: $0.99
price_expiration: 1543012826
currency: USD
cost: 0.99
expiration: 4444444444.0
login: <phone number>

Generate some keys with the following command:
yowsup-cli demos -l "491711234567:XXXXXX0uB6IMp9spB9FqedKFak=" -y

This opens the yowsup command line interface.

Do a Quick Login by entering "/L<return>"

This should result in a response like:
INFO:yowsup.layers.axolotl.layer_control:Axolotl layer is generating keys
Auth: Logged in!
general: Disconnected: Requested

Finally you are able to send messages.

yowsup-cli demos -l "<originating number>:<password from previous step>" -s <destination number> "<message>"

example:
yowsup-cli demos -l "491711234567: XXXXXX0uB6IMp9spB9FqedKFak =" -s 491727654321 "Welcome to openHAB"

You should receive the message in WhatsApp on the target phone

You could also try the echo client:
yowsup-cli demos -l "49170XXXXXXX:XXXXXXXXLQkjHw2/faNBL0XXXX=" -e

Send some messages to yowsup and get the echo.

Please describe the different supported things / devices within this section. Which different types are supported, which models were tested etc.? Note that it is planned to generate some part of this based on the XML files within ESH-INF/thing of your binding.

There is no auto-discovery for WhatsApp things.

A WhatsApp thing could be added using PaperUI. Change to Configuration->Things and click on '+'.

Select the WhatsApp binding and continue, then the WhatsApp Hub and continue.

Enter the originating number of the SIM card, which was registered. Do not enter the leading '0' and use international format:
e.g. 01711234567 is a number in Germany, then replace the loading '0' with '49' = 491711234567

The API password is the one you generated during yowsup installation.

If you used the default installation you should find yowsup-cli under /usr/local/bin

Here you should provide information about available channel types, what their meaning is and how they can be used.

Note that it is planned to generate some part of this based on the XML files within ESH-INF/thing of your binding.

Provide a full usage example based on textual configuration files (*.things, *.items, *.sitemap).

WhatsApp requires the number in international format. The binding normalizes the given number to allow different formats. You need to set the default country code in the binding config if you want to use 0xxx (being transformed to CCxxxx). examples: +491711234567 -> 491711234567 00491711234567 -> 491711234567 01711234567 -> 491711234567

Send a message: You need to create an item, which is linked to the "Text Messages->Outbound message" channel.
Use sendCommand(Item, Message) from an openHAB rule and use the following notation: : Inbound messages are posted to the "Text Messages->Inbound message" channel in the same format.

The binding uses a JSON format to send/receive non-text media messages, e.g.
{ "type" : "image", "number" : "491711234567", "path" : "/home/markus7017/Downloads/image.png", "caption" : "Hello from openHAB" }
sends an image. Please make sure to incude the fully qualified path.

If you get a message “WARNING:yowsup.layers.axolotl.layer_receive:InvalidMessage or InvalidKeyIdException for xxxxxxxxxx, going to send a retry also described here: tgalal/yowsup#2403

From Solution tgalal/yowsup#2525:

There is a little annoying solution, that i am using since 2 month and it always works.
login with the yowsup cli (... -y)
/L
/disconnect

repeat step 2 and 3 repeatedly until it resolves. it will auto generate the key.
maybe you have to try 50 to 100 times to solve it keep patience , it will work.
Try deleting the .yowsup folder, and then try again.
What helped me was just sending messages in both directions, also using the echo client (-e).

---

If you get a message “ModuleNotFoundError: No module named ‘Crypto’:” then run the following:
pip3 uninstall crypto
pip3 uninstall pycrypto
pip3 install pycrypto

---

If you get an error that MagicWand is not found: I seems that MagicWand doesn't support imagemagick 7 yet as mentioned in other answers.
There's a new brew formula for Imagemagick 6 which can be used to install the older version in the meanwhile:

brew install imagemagick@6

Create a symlink to this newly installed dylib file as mentioned in other answer to get things working.
ln -s /usr/local/Cellar/imagemagick@6/<your specific 6 version>/lib/libMagickWand-6.Q16.dylib /usr/local/lib/libMagickWand.dylib

e.g.: ln -s /usr/local/Cellar/imagemagick@6/6.9.10-14/lib/libMagickWand-6.Q16.dylib /usr/local/lib/libMagickWand.dylib

--

If you see the error “ERROR:yowsup.layers.protocol_media.mediauploader:Error occured at transfer object of type ‘int’ has no len()” run
pip3 uninstall pyOpenSSL

see danielcardeenas/whatsapp-framework#133