WhatsApp Automation in Python with Neonize
Over 2 billion people use WhatsApp every month. If you work in software development, marketing, or customer support, there is a good chance you have been asked to automate at least part of that channel. The problem: most WhatsApp automation tools are either expensive SaaS platforms with usage limits or low-level libraries that require wrestling with protocol details. Neonize changes that equation. It wraps the Go-based Whatsmeow library into a clean Python API, giving you access to WhatsApp Web's full protocol without leaving the language you already know.
In this article, you will learn what Neonize is, how to install it, and how to build a working WhatsApp bot in under 30 lines of code. You will also see how to handle media, manage groups, and run bots asynchronously for production workloads.
What Is Neonize?
Neonize is an open-source Python library maintained by krypton-byte on GitHub. It acts as a Python binding for Whatsmeow, a mature Go library that implements the WhatsApp Web multi-device protocol. The Go backend handles the heavy lifting: encryption, connection management, and binary protocol encoding. Python handles the logic you write.
This architecture gives you two things at once. First, you get the speed and reliability of a compiled Go binary managing your WebSocket connections and cryptographic handshakes. Second, you get Python's readability and massive third-party library ecosystem for everything else your bot needs to do: database queries, API calls, natural language processing, or scheduling.
Neonize follows an event-driven design. You register callback functions for specific events (a new message arrives, the bot connects, a user starts typing), and the library calls those functions when the events occur. This model works well for chatbots because messages arrive unpredictably, and you need to react to each one independently.
Key Features at a Glance
Core Messaging
- Send and receive plain text messages
- Handle media files: images, videos, documents, and audio
- Manage groups: create, add or remove participants, change settings
- Track message delivery receipts and read status
- Reply to specific messages in a conversation thread
Advanced Capabilities
- End-to-end encryption support through the Whatsmeow protocol
- Presence and typing indicators so your bot can show "typing..." status
- Polls and interactive message support
- Call event handling (incoming, outgoing, missed)
- Contact and user information retrieval
- Blocklist management
Developer Experience
- Both synchronous and asynchronous APIs
- SQLite and PostgreSQL database backends for session persistence
- Built-in logging and debugging utilities
- Simple decorator-based event registration
Prerequisites and Installation
Before you start, make sure you have the following:
- Python 3.8 or higher installed on your system
- Go 1.19 or higher only if you plan to build Neonize from source (the pip package includes prebuilt binaries for most platforms)
Install Neonize with pip:
pip install neonizeAfter installation, verify it works by importing the library in a Python shell:
from neonize.client import NewClientIf that line runs without errors, you are ready to build your first bot.
Building Your First WhatsApp Bot
The quickest way to understand Neonize is to build a simple echo bot. It connects to WhatsApp, listens for incoming messages, and replies with a greeting when someone sends "hi".
Step 1: Import the required classes.
Neonize exposes three primary imports for the synchronous API: NewClient for creating a bot instance, and the event types MessageEv and ConnectedEv for handling messages and connection events.
Step 2: Initialize the client.
The NewClient constructor takes a session name string. This name determines where Neonize stores your WhatsApp session data (SQLite by default). If you run multiple bots on the same machine, give each one a unique name.
Step 3: Register event handlers with decorators.
Use @client.event(EventType) to register a function that fires whenever that event occurs. The ConnectedEv event triggers once when the bot successfully authenticates. The MessageEv event triggers every time a message arrives.
Here is the complete working example:
from neonize.client import NewClient from neonize.events import MessageEv, ConnectedEv, event client = NewClient("my_first_bot") @client.event(ConnectedEv) def on_connected(client, event): print("Bot connected to WhatsApp!") @client.event(MessageEv) def on_message(client, event): if event.message.conversation == "hi": client.reply_message("Hello! How can I help you?", event.message) client.connect() event.wait()
When you run this script, Neonize will display a QR code in your terminal. Scan it with WhatsApp on your phone (linked devices, then link a device). After authentication, the bot connects and starts listening. Send "hi" from any chat, and the bot replies.
Understanding the Event Flow
The connection sequence works like this:
client.connect()opens a WebSocket connection to WhatsApp servers.- WhatsApp sends a QR code challenge. Neonize renders it in the terminal.
- You scan the QR code with your phone. WhatsApp verifies the pairing.
- The
ConnectedEvhandler fires. Your bot is now online. - Every incoming message triggers the
MessageEvhandler. event.wait()keeps the Python process alive so the bot continues running.
The session persists across restarts. After the first successful scan, Neonize stores the session tokens in a local database. You will not need to scan the QR code again unless you explicitly log out or the session expires.
Handling Media and Advanced Events
Real bots do more than echo text. You need to send images, react to typing indicators, and manage groups. Neonize supports all of this through the same event-driven pattern.
Sending and Receiving Media
To send an image, you pass the image bytes and a caption to the appropriate send method. When you receive a media message, Neonize decodes the attachment and makes the binary data available through the event object. You can save it to disk, forward it to another chat, or process it with an image recognition library.
Presence and Typing Indicators
You can make your bot appear to type before sending a reply. This small detail makes automated responses feel more natural to users. Neonize lets you send a "composing" presence update, wait a realistic delay, and then send the actual message. You can also listen for when other users start or stop typing.
Group Management
Neonize exposes group operations: create new groups, add or remove participants, update the group subject or description, and retrieve the participant list. You can build moderation bots that automatically remove users who violate rules, or announcement bots that broadcast messages to multiple groups on a schedule.
Async Bots for Production Workloads
The synchronous API works fine for simple bots and prototyping. But if your bot handles hundreds of conversations at once, blocking calls will create bottlenecks. Neonize provides an async API for exactly this scenario.
Import from neonize.aioze instead of neonize.client:
import asyncio from neonize.aioze.client import NewAClient from neonize.aioze.events import MessageEv, ConnectedEv client = NewAClient("async_bot") @client.event(ConnectedEv) async def on_connected(client, event): print("Async bot connected!") @client.event(MessageEv) async def on_message(client, event): if event.message.conversation == "ping": await client.reply_message("pong", event.message) asyncio.run(client.connect())
The async version uses asyncio under the hood. Each message handler runs as a coroutine, so your bot can process multiple messages concurrently without blocking. This is the approach you should use for any bot that will run in production or handle more than a trickle of traffic.
For a real-world look at running a WhatsApp bot continuously, this video walks through the full deployment process:
Best Practices for Running Neonize in Production
Building the bot is the easy part. Keeping it running reliably requires attention to a few details.
Choose the right database backend. Neonize supports both SQLite and PostgreSQL for session storage. SQLite works well for single-instance bots. If you run multiple bot instances or need high availability, PostgreSQL is the better choice because it handles concurrent access without file-locking issues.
Add error handling around your event callbacks. If an unhandled exception crashes inside an event handler, it can silently break your bot. Wrap your logic in try/except blocks, log the error, and let the bot continue processing the next message.
Use structured logging. Python's built-in logging module works well here. Log every incoming message ID, every reply you send, and every error you catch. When something goes wrong at 2 AM, you will want those records.
Respect WhatsApp's terms of service. Automated messaging on WhatsApp exists in a gray area. Keep your message volume reasonable, do not spam users who have not opted in, and do not scrape contact lists. Accounts that trigger spam detection get banned, and there is no reliable appeal process.
Handle disconnections gracefully. Network interruptions happen. Neonize will attempt to reconnect automatically, but your bot should not assume it is always online. If a message send fails, queue it for retry rather than crashing.
Recommended Courses
Keep learning with these free courses:
What to Build Next
You now have a working foundation. The real question is what you build on top of it. Here are a few concrete project ideas that go beyond a hello-world bot:
- Customer support triage bot: Receives incoming messages, classifies them by topic using a simple keyword matcher or a language model, and routes them to the correct support queue.
- Appointment reminder service: Connects to a calendar API, reads upcoming appointments, and sends WhatsApp reminders 24 hours and 1 hour before each one.
- Group moderation bot: Monitors a WhatsApp group for messages that match a blocklist of banned words or links, and automatically deletes offending messages or warns the sender.
- Order notification system: Integrates with an e-commerce backend (Shopify, WooCommerce) to send shipping updates and delivery confirmations to customers via WhatsApp.
Each of these projects will teach you something different about Neonize: media handling, group operations, scheduled tasks, or external API integration. Start with whichever one solves a problem you actually have.
The full source code, documentation, and issue tracker live at the Neonize GitHub repository. If the library saves you time on a project, consider sponsoring the maintainer. Open-source projects like this survive on community support, and a few dollars a month goes further than you might expect.
If you are new to Python and want to get comfortable with the language before diving into libraries like Neonize, our Python vs JavaScript comparison can help you decide where to focus. And for writing cleaner bot code, check out our guide on Python clean code practices.
