blakegt/whatsapp-web-api-rest repository overview

⁠📱 WhatsApp API REST

whatsapp-web-api-rest is an easy-to-use Docker REST API wrapper for Baileys - Lightweight full-featured TypeScript/JavaScript WhatsApp Web API⁠ built with NestJS⁠. It allows you to interact with WhatsApp using endpoints to enable message sending, simulate actions, fetch contacts, and more.

⁠✨ Features

• 🚀 Send WhatsApp messages via API
• 🤖 Simulate user actions (e.g. composing, recording audio)
• 📲 Fetch chats, contacts, labels, and WhatsApp states
• 🔔 Manage webhooks for real-time updates
• 🔄 Server-Sent Events (SSE) for live message updates
• ⚡️ RESTful design based on NestJS

⁠🐳 Docker

docker run --restart unless-stopped -dp 8085:8085 --name whatsapp-web-api-rest blakegt/whatsapp-web-api-rest:latest

⁠👨🏻‍💻 Dev mode

Clone the repository:

git clone https://github.com/your-username/whatsapp-web-api-rest.git

Install dependencies:

cd whatsapp-web-api-rest
npm install or pnpm i

Start the server:

npm run dev or pnpm dev

⁠🛠️ API Endpoints

• GET /

  Start whatsApp session

  Returns an HTML page displaying QR code for authentication curl -i http://localhost:8085 or open in your browser http://localhost:8085⁠

• POST /message

  Send message text, media, location, poll, contact

  Request Body: application/json

  curl -X POST http://localhost:8085/message \ -H "Content-Type: application/json" -d {...body}

  Body examples:

  • Text:

    {
      "chatId": "[email protected]",
      "text": "Hello!",
    }
    

    Copy

  • Media (document):

    {
      "chatId": "[email protected]",
      "media": {
          "type": "document",
          "filename": "My name of the file",
          "caption": "Hey! This is a pdf doc",
          "mimetype": "application/pdf",
          "data": "JVBERi0xLjMKJbrfrO..." // base64
      }
    }
    

    Copy

  • Media (video):

    {
      "chatId": "[email protected]",
      "media": {
          "type": "video",
          "caption": "Hey! This is a video",
          "data": "JVBERi0xLjMKJbrfrO..." // base64
      }
    }
    

    Copy

  • Media (audio):

    {
      "chatId": "[email protected]",
      "media": {
          "type": "audio",
          "caption": "Hey! This is an audio",
          "ptt": false, // Set to true if you want it to appear as a voice note
          "data": "JVBERi0xLjMKJbrfrO..." // base64
      }
    }
    

    Copy

  • Media (sticker):

    {
      "chatId": "[email protected]",
      "media": {
          "type": "sticker",
          "mimetype": "image/webp",
          "data": "JVBERi0xLjMKJbrfrO..." // base64
      }
    }
    

    Copy

  • Location:

    {
        "chatId": "[email protected]",
        "location": {
          "name": "Googleplex",
          "address": "1600 Amphitheatre Pkwy",
          "url": "https: //google.com",
          "latitude": 37.422,
          "longitude": -122.084
        }
    }
    

    Copy

  • Contact:

    {
        "chatId": "[email protected]",
        "contact": {
            "firstname": "Blake",
            "lastname": "Pro",
            "email": "[email protected]",
            "phone": "5215512345678"
        }
    }
    

    Copy

  • Poll:

    {
        "chatId": "[email protected]",
        "poll": {
            "name": "Do you like Apple?",
            "options": [
                "Yes",
                "No",
                "Maybe"
            ],
            "allowMultipleAnswers": false
        }
    }
    

    Copy

• POST /simulate

  Simulate an action (presence)

  • chatId: The chat number ID
  • action: The action to simulate: unavailable | available | composing | recording | paused

    {
        "chatId": "[email protected]",
        "action": "composing",
    }
    

    Copy
    curl http://localhost:8085/simulate

• GET /profile/status/:chatId

  Get the status of a person/group

  • chatId: The chat number ID

  curl http://localhost:8085/profile/status/:chatId

• GET /profile/picture/:chatId

  Get profile url picture of a person/group

  • chatId: The chat number ID

  curl http://localhost:8085/picture/status/:chatId

• GET /chats

  Fetches all available chats

  curl http://localhost:8085/chats

• GET /contacts

  Fetches all available contacts

  curl http://localhost:8085/contacts

• GET /number/:numberId

  Check if a given ID is on WhatsApp

  • number: The phone number

  curl http://localhost:8085/number/:number

• GET /logout

  Logs out from the current WhatsApp session

  curl http://localhost:8085/logout

⁠🛠️ Manage webhooks

• GET /webhooks

  Fetches the list of registered webhook URLs

  curl http://localhost:8085/webhooks

• POST /webhooks

  Create a new webhook URL Request Body: application/json

  curl -X POST http://localhost:8085/webhooks \
  -H "Content-Type: application/json" \
  -d { "url": "https://your-webhook-url.com" }
  

  Copy

• DELETE /webhooks/:indexId

  Remove the webhook by the index in the list

  curl -X DELETE http://localhost:8085/webhooks/:indexId

⁠🌐 Example of a webhook in an Express.js (Node.js) application

1. Create a folder in your computer and enter

2. Init the project npm init or pnpm i

3. Install express.js npm i express.js or pnpm i express.js

4. Create a file index.js

5. Copy and paste in index.js and run in terminal node index.js

   const express = require('express');
   
   const app = express();
   const port = 3005;
   const limit = '50mb';
   
   // Use express.json() middleware to parse JSON bodies
   app.use(express.json({ limit }));
   app.use(express.urlencoded({ extended: true, limit }));
   
   // Define a POST endpoint
   app.post('/', async (req, res) => {
     const url = `${req.protocol}://${req.get('host')}${req.url}`;
     const bodyPayload = req.body;
   
     const message = bodyPayload?.message;
     const media = bodyPayload?.media;
     const from = message?.from;
     console.log(from)
   
     // Body payload data 
     const payload = {
       chatId: from,
       text: 'Response from webhook'
     }
   
     // Send message to endpoint
     await fetch(`${url}/message`,
       {
         method: 'POST',
         body: JSON.stringify(payload),
         headers: {
           "Content-Type": "application/json",
         },
       })
   
     res.send({});
   });
   
   // Start the server
   app.listen(port, () => {
     console.log(`Server running at http://localhost:${port}`);
   });
   

   Copy

⁠🤝 Contributing

Feel free to contribute by creating issues or submitting pull requests. All contributions are welcome!

⁠🤝 Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners. Also it is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

⁠📜 License

This project is licensed under the MIT License.

⁠👨🏻‍💻 Author

Cristian Yosafat Hernández Ruiz - BlakePro⁠