User Guide
API
WhatsApp Automation API is built using PHP and it uses a simple bridge to send messages to Python program.
It supports a single end point for sending messages, details are given below:
https://<your-domain.com>/admin/SendSMSAPI.php
Parameters
| Parameter name (GET or POST method) | Description |
| SMS | The mobile number to send the message to should contain country code and any trailing zeros but other formats are supported too. |
| mobileNo | The mobile number to send the message to should contain the country code and any trailing zeros but other formats are supported too. |
| accountId | The account id of customer, |
| accountPassword | The password of user. (TO BE DECRYPTED) |
Other parameters are present too but are not needed to invoke the API.
Test API
You can invoke WhatsApp Automation API to test if the API is running. The same URL can be used to test the API with different parameters.
crm.cartzlink.com.local/admin/sendSMSApi.php?test_invoke=true&test_num=9203162353525 (Use your own number).
The following parameters are supported for test API.
| Parameter name (GET or POST method) | Description |
| SMS | The text for SMS may contain icons and new lines (\n) |
| test_invoke | Required to invoke test API, can be set to any value. (OPTIONAL) |
| test_num | The number to send the test message to includes country code and leading zero. (OPTIONAL) |
A message should be received by test_num with the text “Test triggered on h:m:s” within a maximum of 3 minutes. It can be used to determine if the API is up and working.
Return Value
Currently, the server returns values in string format, however, it will soon be replaced by a JSON response. The server may return one of the following values:
TIMEOUT: The server received no response from Python in the specified time.
Message sent successfully: The server received the answer and sent the message.
FAILED: The server received an error response from Python.
Developer Guide
WhatsApp automation is used to send messages using WhatsApp Web.
Technologies
It uses Python along with selenium and chromium driver. Python and pip are required for installation. Detailed documentation along with source code can be found in D:\ITL\ITL_PRG\whatem.
Current Chrome Driver Version: 108
How to Run
You can run the application using the main Python file in D:\ITL\ITL_PRG\whatem\src\main.py. The following command can be used to run the Python file. (Make sure you are in D:\ITL\ITL_PRG\whatem\src
.venv/Scripts/python.exe ./main.pyA command prompt window will be launched, and after some time, it will tell you to log in using <phone number> (If you are not testing multiple phones, you may use any phone). An image will be launched afterward, containing the QR code. Scan the code and once logged in, close the image.
Folder Structure
- .venv
- tests
- vendor
- vendor_production
- config.py
- main.py
- setup.py
- whatem
- commands
- beowser_config.py
Here is a brief introduction to folder structure:
tests: Automated tests using unit test
vendor: Any third-party libraries or applications are placed here
vendor_production: If this folder exists, use this while deploying.
config.py: Contains the configuration scripts for program
main.py: Enter the point of program
setup.py: Responsible for building the program into a .exe file.
whatem: Contains the actual code for controlling the browser.
whatem/browser_config.py: Creates and configures the browser.
How to use
To send a message using WhatsApp automation, you must create a file in the specified directory. The files should be placed in the C:\anisiis\test.cartzlink.com\httpdocs\whatsapp-messages directory. Before making the actual file, you must create a .lock file, i.e., a file with the same name but suffixed by a .lock extension. After you have finished writing the file, delete the .lock file to send the message. Your file is automatically deleted afterward.
File Formats
The file must follow a pattern of mobile number to message without any formatting, suffixed by the extension. For example, to send a text message to +92 0123-4567890, you will name your file 9201234567890.txt
The file may also contain an underscore followed by anything. This is used to create queued messages. For example, to send three text messages to +92 0123-4567890 at the same time, you will create 9201234567890.txt, 9201234567890_2.txt and 9201234567890_3.txt
.
Supported Formats
The following file formats are supported:
| Extension | Action |
| txt | The text of the file is sent in the message |
| The file is sent as a document | |
| png, jpg | The image is sent as a document |
Checking Message Result
After placing the file, you can check the result of the message by waiting for the result file. The resulting file will be created in </path/to/current-messages-directory>/result folder. It will follow a format <number-entered>.log. It may contain one of the following messages.
SUCCESS: The message has been sent successfully.
FAILED: An error occurred while sending the message.
INVALID_NUMBER: The number was blacklisted due to too many failed attempts.
If no file is created within 6-7 seconds, then it means that either the service is down or busy sending other messages.
Sending using Specific Number
If you have configured two or more numbers, you can send a number specifically from a number by creating a file in that number’s directory.
Example of Sending Message
Let’s say you want to send a text message to +92 0123 4567890 by using the phone number +92 0098 7654321, you will follow the following steps to send the message.
- Create a file 9201234567890.txt.lock in <current-messages-directory>/9200987654321 (mentioned above)
- Create a file 9201234567890.txt and write the message in it.
- Delete the lock file, i.e., 9201234567890.txt.lock.
- Look in the </path/to/current-messages-directory>/9200987654321/result> for a file named 9201234567890.log
Mobile Number Used
The mobile numbers can be configured using config.py, however, the actual mobile number used to send the message will be the one you use to scan the QR code.
Debugging
- Look at the file whatsapp_automation.log in the root directory to find errors.
- Run the tests to detect any failing component
Steps for installing / Deployment
Installation
For installation the first time, follow the following steps
- Download the latest version from this URL: https://crm.cartzlink.com/applications/whatem/whatem.zip
- Unzip the
whatem.zipto the installation directory. - Disable auto update of Chrome (7 Ways to Disable Automatic Chrome Update – WebNots).
- Download the latest Chrome driver and place it in
vendor/chrome_win32directory. - Run the main.exe.
- Authenticate the WhatsApp.
Deployment
Follow the steps for deploying the new version to production
- Make sure you are in the src directory.
- Run all tests, you may use GUI from Visual Studio Code or use the following command
- .venv/Scripts/python.exe -m unittest discover -s tests -p test_*.py
- Set the build type: Go to
build/config/config.pyand set the build_type variable to one of the following:- build: While you are testing.
- patch: When you are deploying a small bug fix.
- minor: When you are deploying a new feature.
- major: Deploying big changes which could break the code.
- Deploy the new version, run the following command
- .venv/Scripts/python.exe ./deploy.py
- Ask your senior to deploy the following folder:
C:\anisiis\test.cartzlink.com\httpdocs\applications\whatem. - The application will be deployed automatically.
