{"id":14987006,"url":"https://github.com/kalebu/alright","last_synced_at":"2025-05-16T08:06:47.599Z","repository":{"id":37003321,"uuid":"378700960","full_name":"Kalebu/alright","owner":"Kalebu","description":"Python wrapper for WhatsApp web-based on selenium ","archived":false,"fork":false,"pushed_at":"2024-08-02T16:55:48.000Z","size":524,"stargazers_count":393,"open_issues_count":51,"forks_count":114,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-16T08:06:40.430Z","etag":null,"topics":["python-whatsapp","pywhatsapp","whatsapp-api","whatsapp-bulk-sender","whatsapp-business-api","whatsapp-web"],"latest_commit_sha":null,"homepage":"https://www.youtube.com/watch?v=yitQTt-NukM","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kalebu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"kalebujordan"}},"created_at":"2021-06-20T17:16:31.000Z","updated_at":"2025-04-16T16:18:33.000Z","dependencies_parsed_at":"2023-02-19T04:30:59.371Z","dependency_job_id":"8f08a0ff-b13b-4f9b-9a8d-b95d43228c53","html_url":"https://github.com/Kalebu/alright","commit_stats":{"total_commits":118,"total_committers":22,"mean_commits":5.363636363636363,"dds":0.5508474576271186,"last_synced_commit":"b7a1d257fa8c830ed4d026c67196537b6f57451b"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kalebu%2Falright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kalebu%2Falright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kalebu%2Falright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kalebu%2Falright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kalebu","download_url":"https://codeload.github.com/Kalebu/alright/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493385,"owners_count":22080127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python-whatsapp","pywhatsapp","whatsapp-api","whatsapp-bulk-sender","whatsapp-business-api","whatsapp-web"],"created_at":"2024-09-24T14:13:56.613Z","updated_at":"2025-05-16T08:06:42.589Z","avatar_url":"https://github.com/Kalebu.png","language":"Python","readme":"# [alright](#)\n\n\u003csamp\u003e\n\nPython wrapper for WhatsApp web made with selenium inspired by [PyWhatsApp](https://github.com/shauryauppal/PyWhatsapp)\n\n[![Downloads](https://pepy.tech/badge/alright)](https://pepy.tech/project/alright)\n[![Downloads](https://pepy.tech/badge/alright/month)](https://pepy.tech/project/alright)\n[![Downloads](https://pepy.tech/badge/alright/week)](https://pepy.tech/project/alright)\n\n[![Youtube demo](https://img.youtube.com/vi/yitQTt-NukM/0.jpg)](https://www.youtube.com/watch?v=yitQTt-NukM)\n\n## Why alright ?\n\nI was looking for a way to control and automate WhatsApp web with Python, I came across some very nice libaries and wrapper implementations including;\n\n- [pywhatkit](https://pypi.org/project/pywhatkit/)\n- [pywhatsapp](https://github.com/tax/pywhatsapp)\n- [PyWhatsapp](https://github.com/shauryauppal/PyWhatsapp)\n- [WebWhatsapp-Wrapper](https://github.com/mukulhase/WebWhatsapp-Wrapper)\n- and many others\n\nSo I tried [**pywhatkit**](https://pypi.org/project/pywhatkit/), a really cool one well crafted to be used by others but its implementations require you to open a new browser tab and scan QR code everytime you send a message no matter if its to the same person, which was deal breaker for using it.\n\nThen I tried [**pywhatsapp**](https://github.com/tax/pywhatsapp) which is based on [yowsup](https://github.com/tgalal/yowsup) and thus requiring you to do some registration with yowsup before using it of which after bit of googling I got scared of having my number blocked, so I went for the next option\n\nI then went for [**WebWhatsapp-Wrapper**](https://github.com/mukulhase/WebWhatsapp-Wrapper), it has some good documentation and recent commits so I had hopes that it would work. But unfortunately it didn't for me, and after having a couple of errors I abandoned it to look for the next alternative.\n\nWhich is [**PyWhatsapp**](https://github.com/shauryauppal/PyWhatsapp) by [shauryauppal](https://github.com/shauryauppal/). This was more of CLI tool than a wrapper which suprisingly worked well and it's approach allows you to dynamically send whatsapp message to unsaved contacts without rescanning QR-code everytime.\n\nSo what I did is more of a refactoring of the implementation of that tool to be more of wrapper to easily allow people to run different scripts on top of it instead of just using it as a tool. I then thought of sharing the codebase to people who might have struggled to do this as I did.\n\n## Getting started\n\nYou need to do a little bit of work to get [**alright**](https://github.com/Kalebu/alright) running, but don't worry I got you, everything will work well if you just carefully follow through the documentation.\n\n### Installation\n\nWe need to have alright installed on our machine to start using it which can either be done directly from **GitHub** or using **pip**.\n\n#### Installing directly\n\nYou first need to clone or download the repo to your local directory and then move into the project directory as shown in the example and then run the command below;\n\n```bash\ngit clone https://github.com/Kalebu/alright\ncd alright\nalright \u003e python setup.py install \n....\n```\n\n#### Installing from pip\n\n```bash\npip install alright --upgrade\n```\n\n### Setting up Selenium\n\nUnderneath alright is **Selenium** which is what does all the automation work by directly controlling the browser, so you need to have a selenium driver on your machine for **alright** to work. But luckily alright uses [webdriver-manager](https://pypi.org/project/webdriver-manager/), which does this automatically. You just need to install a browser. By default alright uses [Google Chrome](https://www.google.com/chrome/).\n\n## What you can do with alright?\n\n- [Send Messages](#sending-messages)\n- [Send Messages1](#sending-messages1)\n- [Send Images](#sending-images)\n- [Send Videos](#sending-videos)\n- [Send Documents](#sending-documents)\n- [Get first chat](#get-first-chat)\n- [Search chat by name](#search-chat-by-name)\n- [logout](#logout)\n\n*When you're running your program made with **alright**, you can only have one controlled browser window at a time. Running a new window while another window is live will raise an error. So make sure to close the controlled window before running another one*\n\n### Unsaved contact vs saved contacts\n\nAlright allows you to send the messages and media to both saved and unsaved contacts as explained earlier. But there is a tiny distinction on how you do that, you will observe this clearly as you use the package.\n\nThe first step before sending anything to the user is first to locate the user and then you can start sending the information, thats where the main difference lies between saved and unsaved contacts.\n\n#### Saved contacts\n\nTo saved contact use method *find_by_username()* to locate a saved user. You can also use the same method to locate WhatsApp groups. The parameter can either be;\n\n- saved username\n- mobile number\n- group name\n\nHere an Example on how to do that\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.find_by_username('saved-name or number or group')\n```\n\n#### Unsaved contacts\n\nIn sending message to unsaved whatsapp contacts use *find_user()* method to locate the user and the parameter can only be users number with country code with (+) omitted as shown below;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.find_user('255-74848xxxx')\n```\n\nNow Let's dive in on how we can get started on sending messages and medias\n\n### Sending Messages\n\n\u003eUse this if you don't have WhatsApp desktop installed\n\nTo send a message with alright, you first need to target a specific user by using *find_user()* method (include the **country code** in your number without the '+' symbol) and then after that you can start sending messages to the target user using *send_message()* method as shown in the example below;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.find_user('2557xxxxxz')\n\u003e\u003e\u003e messages = ['Morning my love', 'I wish you a good night!']\n\u003e\u003e\u003e for message in messages:  \n        messenger.send_message(message)    \n```\n\n### Send Direct Message [NEW]\n\n\u003e Recommended\n\nThis is newly added method that makes it a bit simpler to send a direct message without having to do the **find_user** or **find_by_username**, It works well even if you have or not have WhatsApp installed on your machine. It assumes the number is a saved contact by default.\n\n```python\n\u003e\u003e\u003e messenger.send_direct_message(mobile, message, saved=True)\n```\n\nIt does receive the following parameters;\n\n1. **mobile[str]** - The mobile number of the user you want to send the message to\n2. **message[str]** - The message you want to send\n3. **saved[bool]** - If you want to send to a saved contact or not, default is True\n\nHere is an example on how to use it;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e \u003e\u003e\u003e messenger.send_direct_message('25573652xxx', 'Hello')\n2022-08-14 17:27:57,264 - root -- [INFO] \u003e\u003e Message sent successfuly to \n2022-08-14 17:27:57,264 - root -- [INFO] \u003e\u003e send_message() finished running!\n\u003e\u003e\u003e messenger.send_direct_message('25573652xxx', 'Who is This ?', False)\n2022-08-14 17:28:30,953 - root -- [INFO] \u003e\u003e Message sent successfuly to 255736524388\n2022-08-14 17:28:30,953 - root -- [INFO] \u003e\u003e send_message() finished running!\n```\n\n### Sending Messages1\n\nThis Send Message does NOT find the user first like in the above Send Message, AND it does work even if you have the Desktop WhatsApp app installed.\nInclude the **country code** in your number withour '+' symbol as shown in the example below;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messages = ['Morning my love', 'I wish you a good night!']\n\u003e\u003e\u003e mobNum = 27792346512\n\u003e\u003e\u003e for message in messages:  \n        messenger.send_message1(mobNum, msg)\n```\n\n#### Multiple numbers\n\nHere how to send a message to multiple users, Let's say we want to wish merry-x mass to all our contacts, our code is going to look like this;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e numbers = ['2557xxxxxx', '2557xxxxxx', '....']\n\u003e\u003e\u003e for number in numbers:\n        messenger.find_user(number)\n        messenger.send_message(\"I wish you a Merry X-mass and Happy new year \")\n```\n\n*You have to include the **country code** in your number for this library to work but don't include the (+) symbol*\n\n\n\u003e If you're sending media either picture, file, or video each of them have an optional parameter called \u003cmessage\u003e which is usually the caption to accompany the media. \n\n### Sending Images\n\nSending Images is nothing new, its just the fact you have to include a path to your image and the message to accompany the image instead of just the raw string characters and also you have use *send_picture()*, Here an example;\n\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.find_user('mobile')\n\u003e\u003e\u003e messenger.send_picture('path-to-image-without-caption')\n\u003e\u003e\u003e messenger.send_picture('path-to-image',\"Text to accompany image\")\n```\n\n### Sending Videos\n\nSimilarly, to send videos just use the *send_video()*  method;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.find_user('mobile')\n\u003e\u003e\u003e messenger.send_video('path-to-video')\n```\n\n\u003e\n\n### Sending Documents\n\nTo send documents such as docx, pdf, audio etc, you can use the *send_file()* method to do that;\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.find_user('mobile')\n\u003e\u003e\u003e messenger.send_file('path-to-file')\n```\n\n### Check if a chat has unread messages or not\n\nThis method checks if a chat, which name is passed as a *query* parameter, has got unread messages or not.\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.check_if_given_chat_has_unread_messages(query=\"Chat 123\")\n```\n        \n### Get first chat\n\nThis method fetches the first chat in the list on the left of the web app - since they are not ordered in an expected way, a fair workaround is applied. One can also ignore (or not ignore) pinned chats (placed at the top of the list) by passing the parameter *ignore_pinned* to do that - default value is `ignore_pinned=True`.\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.get_first_chat()\n```\n\n### Search chat by name\n\nThis method searches the opened chats by a partial name provided as a `query` parameter, returning the first match. Case sensitivity is treated and does not impact the search.\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.search_chat_by_name(query=\"Friend\")\n```\n        \n### Get last message received in a given chat\n\nThis method searches for the last message received in a given chat, received as a `query` parameter, returning the sender, text and time. Groups, numbers and contacts cases are treated, as well as possible non-received messages, video/images/stickers and others.\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.get_last_message_received(query=\"Friend\")\n```\n        \n### Retrieve all chat names with unread messages\n\nThis method searches for all chats with unread messages, possibly receiving parameters to `limit` the search to a `top` number of chats or not, returning a list of chat names.\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.fetch_all_unread_chats(limit=True, top=30)\n```\n\n#### DISCLAIMER: Apparently, `fetch_all_unread_chats` functionallity works on most updated browser versions (for example, `Chrome Version 102.0.5005.115 (Official Build) (x86_64)`). If it fails with you, please consider updating your browser while we work on an alternatives for non-updated broswers.\n        \n### logout from whatsapp\n\nYou can sign out of an account that is currently saved\n\n```python\n\u003e\u003e\u003e from alright import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp()\n\u003e\u003e\u003e messenger.logout()\n```\n\nWell! thats all for now from the package, to request new feature make an issue.\n\n## Contributions\n\n**alright** is an open-source package under **MIT** license, so contributions are warmly welcome whether that be a code , docs or typo just fork it.\n\nWhen contributing to code please make an issue for that before making your changes so that we can have a discussion before implementation.\n\n## Issues\n\nIf you're facing any issue or difficulty with the usage of the package just raise one so that we can fix it as soon as possible.\n\n**Please, be as much comprehensive as possible!** Use as many screenshots and detailed description sets as possible; this will save us some time that we'd dedicate on asking you for \"a more detailed descriptiton\", and it'll make your request be solved faster.\n\n## Give it a star\n\nWas this useful to you ? Then give it a star so that more people can manke use of this.\n\n## Credits\n\nAll the credits to:\n\n- [kalebu](https://github.com/kalebu)\n- [Eurico Nicacio](https://github.com/euriconicacio)\n- [Victor Daniel](https://github.com/vadolasi)\n- [Cornelius Mostert](https://github.com/theCJMan)\n- [shauryauppal](https://github.com/shauryauppal/)\n- and all the contributors\n\n\u003c/samp\u003e\n","funding_links":["https://patreon.com/kalebujordan"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkalebu%2Falright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkalebu%2Falright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkalebu%2Falright/lists"}