Whatsapp Agent

🚀 WhatsApp Agent

A proxy program that interacts with WhatsApp through the WhatsApp MCP server. It can perform various operations on behalf of the user.

✨ Features

This agent connects to the WhatsApp MCP server, which offers the following tools:

• search_contacts: Search for contacts by name or phone number.
• list_messages: Retrieve messages with optional filters and context.
• list_chats: List available chats and their metadata.
• get_chat: Get information about a specific chat.
• get_direct_chat_by_contact: Find a direct chat with a specific contact.
• get_contact_chats: List all chats involving a specific contact.
• get_last_interaction: Get the latest message with a certain contact.
• get_message_context: Retrieve context information for a specific message.
• send_message: Send a WhatsApp message to a specified phone number or group JID.
• send_file: Send a file (image, video, raw audio, document) to a specified recipient.
• send_audio_message: Send an audio file as a WhatsApp voice message (requires the file to be in .opus format or ffmpeg to be installed).
• download_media: Download media from a WhatsApp message and get the local file path.

🚀 Quick Start

Prerequisites

• Python 3.10+
• WhatsApp MCP server
• OpenAI API key (or a compatible service like DeepSeek)
• uv

⚠️ Important Note

To set up the WhatsApp MCP server, follow the instructions in the README.

📦 Installation

Follow these steps to set up the project on your local machine:

1. Clone the repository

   git clone https://github.com/aasherkamal216/whatsapp_agent.git
   cd whatsapp_agent
   

2. Create and activate a virtual environment

   uv venv
   # On macOS/Linux
   source .venv/bin/activate
   # On Windows
   .venv\Scripts\activate
   

3. Install dependencies

   uv sync
   

4. Set up environment variables Copy the example environment file and update the credentials:

   cp .env.example .env
   

   Add your environment variables to the .env file.

💻 Usage Examples

Run the Chainlit application:

uv run chainlit run chainlit_app.py -w

The application will run at http://localhost:8000.

Example Questions

Here are some example questions you can ask the WhatsApp agent:

• Show my recent chat history.
• Send a message to John Doe: "Meeting at 5 PM."
• List all of John's messages from the past week.
• Download the last photo sent in the "SF News" group.
• Search for a contact named Alex.
• Get the latest interaction information with +1234567890.