Whatsapp Web

🚀 WhatsApp Web Project Documentation

WhatsApp Web is a web client based on WhatsApp, enabling users to access WhatsApp features via web browsers. This project offers a rich set of APIs and protocol implementations, facilitating developers to integrate and extend functionalities.

🚀 Quick Start

WhatsApp Web is a web - based client for the popular messaging service. It provides developers with a set of APIs and protocol implementations to integrate and extend its functionality.

✨ Features

• Comprehensive API: Offers a wide range of APIs for seamless integration.
• Flexible Architecture: Allows for various deployment options to suit different scenarios.
• Well - structured Project: With clear project structure and development guidelines.
• Robust Testing: Utilizes Jest for unit testing and provides multiple testing modes.
• Code Quality Management: Employs ESLint and Prettier for code quality control.

🔧 Technical Details

Architecture

Core Components

1. WhatsApp Client: Interacts with the WhatsApp Web browser application.
2. Core Business Logic: Handles core functions such as message sending/receiving and contact management.
3. WhatsApp API Client: Provides access to the WhatsApp API server.
4. REST API Routes: Implements HTTP interfaces for external system calls.
5. MCP Protocol Implementation: Supports the Model Context Protocol.

Deployment Options

1. WhatsApp API Server: An independently running REST API service.
2. MCP Server (Stand - alone): A direct MCP implementation connected to WhatsApp Web.
3. MCP Server (API Client): Connects via the API server.

This architectural design allows for flexible deployment, supporting the following scenarios:

• Running the API server and MCP server on different machines.
• Using the MCP server as a client for an existing API server.
• Running all components on a single machine.

Development

Project Structure

src/
├── whatsapp-client.ts     # WhatsApp Web client implementation
├── whatsapp-service.ts    # Core business logic implementation
├── whatsapp-api-client.ts # Client access to the WhatsApp API server
├── api.ts                 # REST API route implementation
├── mcp-server.ts          # MCP protocol implementation
└── main.ts                # Application entry point

Build

npm run build

Test

The project uses Jest for unit testing. Run tests:

# Run all tests
npm test

# Run tests in watch mode (during development)
npm run test:watch

# Generate test coverage report
npm run test:coverage

Code Standards

The project uses ESLint and Prettier for code quality management:

# Perform code inspection
npm run lint

# Automatically fix code issues
npm run lint:fix

# Format code
npm run format

# Validate code (inspection + testing)
npm run validate

💻 Usage Examples

Basic Usage

To build the project:

npm run build

Advanced Usage

To run tests in watch mode during development:

npm run test:watch

📚 Documentation

Troubleshooting

Claude Desktop Integration Issues

• Since Claude opens multiple processes, wweb - mcp cannot run in the command - line independent mode. To address this limitation, we split the application into API and MCP modes to support seamless integration with Claude.

Planned Features

• Create webhooks to receive messages and other WhatsApp events.
• Support sending media files (images, audio, documents).
• Implement group chat management features.
• Provide contact management (add/remove contacts).
• Implement message templates for common scenarios.
• Enhance error handling and recovery mechanisms.

Contribution Guidelines

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push to the branch.
5. Create a pull request.

Please ensure your PR:

• Has clear code and is properly tested.
• Follows code standards and naming conventions.
• Provides detailed commit messages and descriptions.

Dependencies

The project depends on the following libraries:

Logging System

Levels

• debug: Debug information
• info: General information
• warn: Warning information
• error: Error information
• fatal: Critical error

Configuration

const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console({ colorize: true })
  ]
});

Security Considerations

1. Do not expose debug endpoints in the production environment.
2. Configure appropriate authentication mechanisms to protect API interfaces.
3. Regularly update dependencies to fix security vulnerabilities.
4. Use HTTPS to provide API services.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for detailed information.