Show HN: Simple WhatsApp API (Open Source)

A multi-session, easy-to-deploy API that allows you to send text messages and attachments from multiple WhatsApp accounts with minimal setup.

• Multi-Session Support: Connect and manage multiple WhatsApp accounts simultaneously. Each session is tied to its own unique API key.
• Easy Login: Scan a QR code just once per session to connect your WhatsApp account.
• Persistent Sessions: Sessions are saved locally, so the server can be restarted without needing to log in again.
• Send Text Messages: A simple endpoint to send plain text messages from a specific session.
• Send Attachments: Send images, videos, or documents directly via file upload, URL, or a Base64 encoded string.
• File Uploads: A dedicated endpoint to upload files and receive a temporary URL, perfect for sending as attachments later.
• Secure:
  • Protect your entire server with a global Master API Key.
  • Manage individual WhatsApp sessions with a per-session API Key.
• Dynamic QR Codes: Fetch the login QR code for any session as a string or a PNG image via API endpoints.

• Node.js (v16 or higher recommended)
• One or more WhatsApp accounts

Create a .env file in the root of the project and add your Master API Key. You can invent any secret strings for the keys.

You can also run this application using Docker and Docker Compose for a more isolated and reproducible setup.

This is the easiest way to get started.

1. Create an Environment File: Create a .env file in the root of the project. This file will be used by Docker Compose to set the environment variables inside the container.

   # .env # The master key to protect the server MASTER_API_KEY=yoursecretkey # The port to run the server on (optional, defaults to 3000) PORT=3000

2. Build and Run the Container: Run the following command to build the Docker image and start the container in the background:

   docker compose up --build -d

   The server will now be running on the port you specified (or the default, 3000).

3. To Stop the Server:

If you don't want to build the image from the source, you can use the pre-built image from Docker Hub.

1. Pull the Image:

   docker pull codegres/simple-whatsapp-api:latest

2. Run the Image: You still need to provide the environment variables and mount the volumes.

   docker run -d \ -p 3000:3000 \ -e MASTER_API_KEY="yoursecretkey" \ -e PORT="3000" \ --name whatsapp-api-container \ -v whatsapp_sessions:/usr/src/app/sessions \ -v whatsapp_uploads:/usr/src/app/uploads \ codegres/simple-whatsapp-api:latest

If you prefer not to use Docker Compose, you can build and run the container manually.

1. Build the Docker Image:

   docker build -t whatsapp-api .

2. Run the Docker Container: You must pass the MASTER_API_KEY and map the port. You also need to create and mount volumes to persist the sessions and uploads data.

   docker run -d \ -p 3000:3000 \ -e MASTER_API_KEY="yoursecretkey" \ -e PORT="3000" \ --name whatsapp-api-container \ -v whatsapp_sessions:/usr/src/app/sessions \ -v whatsapp_uploads:/usr/src/app/uploads \ whatsapp-api
   • -d: Run in detached mode.
   • -p: Map port 3000 on your host to port 3000 in the container.
   • -e: Set environment variables.
   • --name: Assign a name to the container.
   • -v: Mount named volumes to persist data.

All endpoints are prefixed with /api.

This API uses a two-key system for security and session management:

1. Master Key (X-MASTER-KEY):

   • This is a global key that grants access to the API server.
   • It must be included in the header of every single request.
   • This is the key you set in your .env file.

2. Session Key (X-API-KEY):

   • This key identifies a specific WhatsApp session (i.e., a specific phone number).
   • You can invent any unique string for each session (e.g., user1_phone, work_account, a random hash, etc.).
   • The first time a new X-API-KEY is used with the /connect endpoint, a new session will be created for it.

To use a WhatsApp account, you must first connect it to a session key.

1. Choose a unique X-API-KEY for the account you want to connect (e.g., my-personal-whatsapp).

2. Make a request to one of the connection endpoints with both the master key and your chosen session key. The server will generate a QR code for that specific session.

   • GET /api/connect: Returns the QR code as a string.
   • GET /api/connect/image: Returns the QR code as a PNG image.

3. Open WhatsApp on your phone, go to Settings > Linked Devices, and scan the QR code.

Once connected, the server will save the session data in the ./sessions folder. You won't need to scan the code again for this session unless you log out. Repeat this process for each WhatsApp account you want to use, assigning a different X-API-KEY to each.

• Endpoint: GET /connect
• Description: Get the current connection status for a session. If a QR code is available, it will be returned as a string. If not, the session status is returned.
• Headers:
  • X-MASTER-KEY: your_global_master_key_here
  • X-API-KEY: your_unique_session_key
• Response (When QR is ready): 200 OK with the QR string in the body.
• Response (When connected): 200 OK
  { "sessionId": "your_unique_session_key", "status": "Connected" }

• Endpoint: GET /connect/image
• Description: Get the session's QR code as a PNG image.
• Headers:
  • X-MASTER-KEY: your_global_master_key_here
  • X-API-KEY: your_unique_session_key
• Response: 200 OK with Content-Type: image/png.

• Endpoint: POST /upload
• Description: Upload a file to get a temporary URL. The URL is valid for 5 minutes and can be used in the /send or /send-attachment (URL method) endpoints.
• Headers: X-MASTER-KEY: your_global_master_key_here
• Body: multipart/form-data with a single field named file.
• Response:
  { "message": "File uploaded successfully.", "url": "http://localhost:3000/uploads/1678886400000-123456789.jpg" }
• Example curl Request:
  curl -X POST http://localhost:3000/api/upload \ -H "X-MASTER-KEY: your_global_master_key_here" \ -F "file=@/path/to/your/image.jpg"

• Endpoint: GET /send
• Description: A simple GET request to send a text message or an attachment via URL.
• Headers:
  • X-MASTER-KEY: your_global_master_key_here
  • X-API-KEY: your_unique_session_key
• Query Parameters:
  • number: The recipient's phone number (e.g., +1234567890).
  • message: The text message to send.
  • attachmentUrl (optional): A URL to a file to send as an attachment. The message will be used as the caption.
• Example curl Request:
  curl "http://localhost:3000/api/send?number=+1234567890&message=Hello&attachmentUrl=http://localhost:3000/uploads/file.jpg" \ -H "X-MASTER-KEY: your_global_master_key_here" \ -H "X-API-KEY: your_unique_session_key"

• Endpoint: POST /send-message
• Headers:
  • X-MASTER-KEY: your_global_master_key_here
  • X-API-KEY: your_unique_session_key
• Payload: application/json
  { "to": "+1234567890", "message": "Hello from the API!" }

• Endpoint: POST /send-attachment
• Description: Sends an attachment to a specified number. This endpoint supports three methods: direct file upload, from a URL, or from a Base64 string.
• Headers:
  • X-MASTER-KEY: your_global_master_key_here
  • X-API-KEY: your_unique_session_key

• Content-Type: multipart/form-data
• Body Fields:
  • to: The recipient's phone number.
  • file: The file to be sent.
  • caption (optional): A caption for the file.
• Example curl Request:
  curl -X POST http://localhost:3000/api/send-attachment \ -H "X-MASTER-KEY: your_global_master_key_here" \ -H "X-API-KEY: your_unique_session_key" \ -F "to=+1234567890" \ -F "file=@/path/to/your/document.pdf" \ -F "caption=Here is the document you requested."

• Content-Type: application/json
• Payload:
  { "to": "+1234567890", "file": "url_or_base64_string", "type": "image/png", // Required only for Base64 "caption": "Optional caption" }
• Notes:
  • If file is a URL, the server will download it.
  • If file is a Base64 string, you must provide the correct type (MIME type).
• Example curl Request (URL):
  curl -X POST http://localhost:3000/api/send-attachment \ -H "Content-Type: application/json" \ -H "X-MASTER-KEY: your_global_master_key_here" \ -H "X-API-KEY: your_unique_session_key" \ -d '{"to": "+1234567890", "file": "https://i.imgur.com/some-image.jpeg", "caption": "From a URL"}'

• You must keep your phone connected to the internet for the API to work.
• This API uses an unofficial library (whatsapp-web.js), which may have a risk of your number being banned by WhatsApp if used for spamming. Use responsibly.
• This API only supports sending messages and does not handle incoming messages or webhooks.