Supbot2

v0.2.3 (12th Oct 2020)

Unoffical WhatsApp Automation Library for Python

Overview

Supbot2 is an unofficial WhatsApp automation library written in Python which can be used to create bots. Supbot2 uses Appium to automate WhatsApp application to read the GUI and call respective events, and perform various actions on the GUI.

Supbot API (1.0) was extremely tedious to setup and even more difficult to use. Not only that it required to have a phone and Supbot server connected to the Internet, which made it very unstable and unreliable. Supbot2 tries to fix these issues.

Easy to Use

Supbot is exeremly easy and intuitive to use library. It's API is made of just two types of services: Action and Events, which are basically simple function calls.

Aims for Stability

Supbot aims for developers to just concentrate on building the business logic, and not to worry about how the library works. We want the API work flawlessly.

Installation

You can either watch the installation guide, or follow the steps below

Requirements

  • Android phone/emulator
  • A phone number to setup WhatsApp
  • PC

Configuring Whatsapp

  • Install Whatsapp on your phone/AVD
  • Set it up with your phone number
  • IMPORTANT: Turn off notification from android settings
  • IMPORTANT: Create an empty group with !temp name and pin it to the top (You can do this by adding 1 contact to the group then kicking them out)
  • IMPORTANT: Change keyboard to Appium Keyboard (if its not available run supbot once, required for using mentions)

Creating Environment

You will need to setup Appium and Whatsapp before you start with Supbot

  • Download and install JDK, Android Studio, and NPM
  • Create JAVA_HOME environment variable by default it is C:\PROGRA~1\Java\jdk1.8.0_162 in windows (don't forget to change the jdk version depending on what version you have installed)
  • Create ANDROID_HOME environment variable by default it is %USERPROFILE%\AppData\Local\Android\Sdkin windows
  • Install Appium using npm install -g appium@1.15.1
  • Connect your phone via usb, and start debugging -OR- Create and run android emulator using AVD manager

Installing Supbot

You will need Python >=3.7 in order to install supbot. Supbot is developed using Python 3.7.4, so its recomended to use that, so that you don't encouter unexpected issues.

Install the supbot package using

pip install supbot

You can test supbot by running supbot in terminal / powershell, and use the given commands to run some test functions

Note: Please DON'T INTERACT WITH WHATSPAPP after the bot starts, this WILL DE-SYSC THE UI causing bot the restart the whatsapp or even resulting bot to crash, if the UI de-syncs even when you haven't touch whatsapp, please report the issue along with an exact steps to reproduce on github issues

Getting Started

Following code resends the message received from a contact (in just 5 LOC!).
Visit Overview to understand the code.

from supbot import Supbot


def repeat_message(contact_name, message):
    supbot.send_message(contact_name, message)


with Supbot(message_received=repeat_message) as supbot:
    supbot.wait_for_finish()

Roadmap

Check out the Trello board, to see what I'm working on and whats next.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

If you have any problems or you want to contact me for feature ideas or want to collaborate in development you can contact me on DefineX Community discord server.