askrella/whatsapp-chatgpt: a self-hosted WhatsApp bot on whatsapp-web.js

What askrella/whatsapp-chatgpt actually is

The repository describes itself as a WhatsApp bot that uses OpenAI's GPT and DALL-E 2 to respond to user inputs, and it accepts voice messages that it transcribes before answering. It is TypeScript, MIT-licensed according to the README badge and the package.json license field, and it is meant to be run by you on your own machine or server rather than offered as a hosted product. There is no hosted number to message. People searching for a whatsapp chatgpt link or a whatsapp chatgpt number are looking for something this project does not provide: it gives you code that logs into an account you already own.

The intended user is a developer or technically comfortable operator who wants an assistant reachable from WhatsApp, and who is willing to run Node.js, keep an OpenAI key funded, and scan a QR code from a terminal. The README states plainly that operations are not free and that OpenAI charges for each request. It also states that the bot uses Puppeteer to run a real instance of WhatsApp Web and that WhatsApp does not allow bots or unofficial clients, so using it carries a risk of the account being blocked.

How the WhatsApp Web session and the OpenAI calls fit together

The mechanism is a browser automation session, not an official API. The dependency list includes whatsapp-web.js, which drives WhatsApp Web, and Puppeteer underneath it. The Dockerfile installs chromium plus a long list of shared libraries described as components for whatsapp-web.js on systems without a GUI. When the process starts, whatsapp-web.js produces a QR code that you scan with the WhatsApp app on a phone; the resulting session is stored on disk, which is why the compose file mounts a named volume at /app/session.

Message handling runs through src/index.ts, which package.json names as the entry point and which the start script executes with vite-node. Incoming text goes to OpenAI through the chatgpt and openai packages, and image requests go to DALL-E. Voice messages are handled with ffmpeg, which the Dockerfile installs, and the README lists a separate speech-rest-api project among the libraries used, so transcription is not purely local by default. The Dockerfile comments note that installing OpenAI Whisper locally would pull roughly 6 to 7 GB of model data, and that command is commented out. The README also mentions a PREFIX_ENABLED environment variable and a SERPAPI_API_KEY in the compose file, which suggests an optional command prefix and an optional search integration, though the README itself does not explain either setting.

Installing askrella/whatsapp-chatgpt and sending a first message

The README lists the requirements as Node.js 18 or newer, a recent npm, an OpenAI API key, and a WhatsApp account. It points to a documentation site at askrella.github.io/whatsapp-chatgpt for install, configuration and usage details, so the repository README is a summary rather than the full manual. The repository also ships an installer.sh script and a docs directory at the top level.

For a container run, the compose file names the image and the environment variables. Fill in your own key before starting:

version: "3"
services:
    whatsapp-chatgpt:
        container_name: whatsapp-chatgpt
        read_only: true
        image: ghcr.io/askrella/whatsapp-chatgpt:master
        environment:
            OPENAI_API_KEY: ""
            OPENAI_GPT_MODEL: ""
            PREFIX_ENABLED: ""
            SERPAPI_API_KEY: ""
        restart: unless-stopped
        volumes:
            - session-data:/app/session
volumes:
    session-data:

After starting the container, watch its logs. The documentation states that a QR code is printed for pairing; scan it from WhatsApp on your phone under linked devices. The session persists in the session-data volume, so a restart should not require a new scan as long as that volume is intact.

For a local run without Docker, the requirements are Node.js 18 or newer and npm. The repository provides an .env-example file at the top level, and the process reads configuration from .env through the dotenv dependency. The package.json scripts define the two commands the project exposes:

npm install
npm run start

The start script is npx vite-node src/index.ts. Once the bot is paired, send it a direct message from another WhatsApp account and it should reply through GPT. Send a voice note and it should transcribe and answer, provided the transcription path is reachable.

The blocking risk and the maintenance reality

The README is unusually direct about the central weakness. It states that WhatsApp does not allow bots or unofficial clients on its platform, that the Puppeteer approach avoids getting blocked but cannot guarantee it, and that the method should not be considered completely safe. That is a real operational risk, not a formality: the account you pair is the account that can be restricted, and the bot operates as that account rather than as a separate business identity.

The second constraint is maintenance. The README opens by saying the project is unmaintained and looking for maintainers. The last push to the default branch was on 2026-07-12. There are no releases retrieved for the repository, so there is no tagged version to pin against and the compose file references the master image tag, which moves. If you depend on this bot in a production workflow, you are depending on a codebase whose own front page asks for someone to take it over. That does not make the code unusable, but it changes what you should expect when WhatsApp Web changes its internals and whatsapp-web.js needs to catch up.

The third constraint is cost. Every reply is a billed OpenAI request, and the README says so explicitly. A bot in a busy group chat is a metered expense with no built-in budget cap described in the README.

When a hosted assistant or the official WhatsApp Business API is the better fit

The real alternative depends on what you actually want. If you want a number you can message without running anything, you want a hosted assistant, not this repository; this project has no hosted endpoint, and the searches for a free whatsapp chatgpt number do not map to anything it ships. If you want a bot that businesses can message at scale with platform sanction, the official WhatsApp Business API is the sanctioned route, and it comes with onboarding, a business identity, and pricing that the platform controls. The difference in approach is fundamental: this project impersonates a normal WhatsApp Web session through Chromium, while the Business API is a supported integration surface that WhatsApp expects you to use.

If you want a local assistant without WhatsApp in the loop, this project is the wrong layer entirely. Its value is the WhatsApp transport, not the model access; the chatgpt and openai packages it depends on are usable directly from a script. And if you want a maintained WhatsApp automation library, whatsapp-web.js itself is the dependency that does the hard part here, so building against it directly removes the unmaintained middle layer.

Licence, upgrades and what keeping it running costs

The README badge and package.json both state MIT. In practice that means you can modify and redistribute the code, but it says nothing about the OpenAI terms you accept by using an API key, or about WhatsApp's terms, which the README warns you are already outside of. This is not legal advice; if you plan to run this for other people, read both sets of terms yourself.

Upgrade cost is asymmetric. Because there are no releases, you either track the master image tag or build from the Dockerfile yourself. The Dockerfile pins its base to node:bullseye-slim and installs chromium and ffmpeg from the distribution, so a rebuild can pull newer browser and codec packages than the ones the code was written against. The dependency set is broad for a bot of this size: aws-sdk, langchain, chatgpt, openai, whatsapp-web.js, qrcode and picocolors all sit in the same package.json. Each of those is a surface that can drift. The README also notes that the local Whisper transcription option is commented out in the Dockerfile and would add roughly 6 to 7 GB, which is the trade-off between a heavier image and a dependency on an external transcription service.

Editorial conclusion

Adopt askrella/whatsapp-chatgpt if you want a personal or small-group assistant on a number you control and you accept that WhatsApp does not permit unofficial clients. Do not adopt it if you need a guaranteed uptime bot, a public number strangers can message, or a component someone else is actively fixing; the README says the project is unmaintained and looking for maintainers. Verify first that Node.js is 18 or newer, that your OpenAI key has billing enabled, that the session volume survives container restarts, and that your own number is not the one you are willing to lose.

Frequently asked questions

Official sources

1. askrella/whatsapp-chatgpt on GitHub
2. Issues
3. README