{"id":14986944,"url":"https://github.com/chrishubert/whatsapp-api","last_synced_at":"2025-05-14T14:08:40.095Z","repository":{"id":154143987,"uuid":"626760267","full_name":"chrishubert/whatsapp-api","owner":"chrishubert","description":"This project is a REST API wrapper for the whatsapp-web.js library, providing an easy-to-use interface to interact with the WhatsApp Web platform.","archived":false,"fork":false,"pushed_at":"2025-05-06T06:14:51.000Z","size":1448,"stargazers_count":1198,"open_issues_count":123,"forks_count":492,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-05-06T07:33:38.683Z","etag":null,"topics":["api","api-rest","docker","whatsapp","whatsapp-api","whatsapp-automation","whatsapp-bot","whatsapp-web-api"],"latest_commit_sha":null,"homepage":"https://www.christophehubert.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrishubert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-12T05:33:41.000Z","updated_at":"2025-05-05T19:23:47.000Z","dependencies_parsed_at":"2023-10-04T03:49:18.711Z","dependency_job_id":"15c59df2-a737-4267-b2dc-f26d84f01318","html_url":"https://github.com/chrishubert/whatsapp-api","commit_stats":{"total_commits":125,"total_committers":11,"mean_commits":"11.363636363636363","dds":"0.43999999999999995","last_synced_commit":"e18e8b7b4e1c77918d88b33705456022564db02b"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fwhatsapp-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fwhatsapp-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fwhatsapp-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fwhatsapp-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrishubert","download_url":"https://codeload.github.com/chrishubert/whatsapp-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159931,"owners_count":22024566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","docker","whatsapp","whatsapp-api","whatsapp-automation","whatsapp-bot","whatsapp-web-api"],"created_at":"2024-09-24T14:13:50.763Z","updated_at":"2025-05-14T14:08:40.073Z","avatar_url":"https://github.com/chrishubert.png","language":"JavaScript","funding_links":[],"categories":["Archived"],"sub_categories":["APIs \u0026 Protocols"],"readme":"# WhatsApp REST API\n\nREST API wrapper for the [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js) library, providing an easy-to-use interface to interact with the WhatsApp Web platform. \nIt is designed to be used as a docker container, scalable, secure, and easy to integrate with other non-NodeJs projects.\n\nThis project is a work in progress: star it, create issues, features or pull requests ❣️\n\n**NOTE**: I can't guarantee you will not be blocked by using this method, although it has worked for me. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.\n\n## Table of Contents\n\n[1. Quick Start with Docker](#quick-start-with-docker)\n\n[2. Features](#features)\n\n[3. Run Locally](#run-locally)\n\n[4. Testing](#testing)\n\n[5. Documentation](#documentation)\n\n[6. Deploy to Production](#deploy-to-production)\n\n[7. Contributing](#contributing)\n\n[8. License](#license)\n\n[9. Star History](#star-history)\n\n## Quick Start with Docker\n\n[![dockeri.co](https://dockerico.blankenship.io/image/chrishubert/whatsapp-web-api)](https://hub.docker.com/r/chrishubert/whatsapp-web-api)\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/chrishubert/whatsapp-api.git\ncd whatsapp-api\n```\n\n3. Run the Docker Compose:\n\n```bash\ndocker-compose pull \u0026\u0026 docker-compose up\n```\n4. Visit http://localhost:3000/session/start/ABCD\n\n5. Scan the QR on your console using WhatsApp mobile app -\u003e Linked Device -\u003e Link a Device (it may take time to setup the session)\n\n6. Visit http://localhost:3000/client/getContacts/ABCD\n\n7. EXTRA: Look at all the callbacks data in `./session/message_log.txt`\n\n![Quick Start](./assets/basic_start.gif)\n\n## Features\n\n1. API and Callbacks\n\n| Actions                      | Status | Sessions                                | Status | Callbacks                                      | Status |\n| ----------------------------| ------| ----------------------------------------| ------| ----------------------------------------------| ------|\n| Send Image Message           | ✅     | Initiate session                       | ✅    | Callback QR code                               | ✅     |\n| Send Video Message           | ✅     | Terminate session                      | ✅    | Callback new message                           | ✅     |\n| Send Audio Message           | ✅     | Terminate inactive sessions            | ✅    | Callback status change                         | ✅     |\n| Send Document Message        | ✅     | Terminate all sessions                 | ✅    | Callback message media attachment              | ✅     |\n| Send File URL                | ✅     | Healthcheck                            | ✅    |                                                |        |\n| Send Button Message          | ✅     | Local test callback                    |        |                                                |        |\n| Send Contact Message         | ✅     |                                        |        |                                                |        |\n| Send List Message            | ✅     |                                        |        |                                                |        |\n| Set Status                   | ✅     |                                        |        |                                                |        |\n| Send Button With Media       | ✅     |                                        |        |                                                |        |\n| Is On Whatsapp?              | ✅     |                                        |        |                                                |        |\n| Download Profile Pic         | ✅     |                                        |        |                                                |        |\n| User Status                  | ✅     |                                        |        |                                                |        |\n| Block/Unblock User           | ✅     |                                        |        |                                                |        |\n| Update Profile Picture       | ✅     |                                        |        |                                                |        |\n| Create Group                 | ✅     |                                        |        |                                                |        |\n| Leave Group                  | ✅     |                                        |        |                                                |        |\n| All Groups                   | ✅     |                                        |        |                                                |        |\n| Invite User                  | ✅     |                                        |        |                                                |        |\n| Make Admin                   | ✅     |                                        |        |                                                |        |\n| Demote Admin                 | ✅     |                                        |        |                                                |        |\n| Group Invite Code            | ✅     |                                        |        |                                                |        |\n| Update Group Participants    | ✅     |                                        |        |                                                |        |\n| Update Group Setting         | ✅     |                                        |        |                                                |        |\n| Update Group Subject         | ✅     |                                        |        |                                                |        |\n| Update Group Description     | ✅     |                                        |        |                                                |        |\n\n3. Handle multiple client sessions (session data saved locally), identified by unique id\n\n4. All endpoints may be secured by a global API key\n\n5. On server start, all existing sessions are restored\n\n6. Set messages automatically as read\n\n7. Disable any of the callbacks\n\n## Run Locally\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/chrishubert/whatsapp-api.git\ncd whatsapp-api\n```\n\n2. Install the dependencies:\n\n```bash\nnpm install\n```\n\n3. Copy the `.env.example` file to `.env` and update the required environment variables:\n\n```bash\ncp .env.example .env\n```\n\n4. Run the application:\n\n```bash\nnpm run start\n```\n\n5. Access the API at `http://localhost:3000`\n\n## Testing\n\nRun the test suite with the following command:\n\n```bash\nnpm run test\n```\n\n## Documentation\n\nAPI documentation can be found in the [`swagger.json`](https://raw.githubusercontent.com/chrishubert/whatsapp-api/master/swagger.json) file. See this file directly into [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/chrishubert/whatsapp-api/master/swagger.json) or any other OpenAPI-compatible tool to view and interact with the API documentation.\n\nThis documentation is straightforward if you are familiar with whatsapp-web.js library (https://docs.wwebjs.dev/)\nIf you are still confused - open an issue and I'll improve it.\n\nAlso, there is an option to run the documentation endpoint locally by setting the `ENABLE_SWAGGER_ENDPOINT` environment variable. Restart the service and go to `/api-docs` endpoint to see it.\n\nBy default, all callback events are delivered to the webhook defined with the `BASE_WEBHOOK_URL` environment variable.\nThis can be overridden by setting the `*_WEBHOOK_URL` environment variable, where `*` is your sessionId.\nFor example, if you have the sessionId defined as `DEMO`, the environment variable must be `DEMO_WEBHOOK_URL`.\n\nBy setting the `DISABLED_CALLBACKS` environment variable you can specify what events you are **not** willing to receive on your webhook.\n\n### Scanning QR code\n\nIn order to validate a new WhatsApp Web instance you need to scan the QR code using your mobile phone. Official documentation can be found at (https://faq.whatsapp.com/1079327266110265/?cms_platform=android) page. The service itself delivers the QR code content as a webhook event or you can use the REST endpoints (`/session/qr/:sessionId` or `/session/qr/:sessionId/image` to get the QR code as a png image). \n\n## Deploy to Production\n\n- Load the docker image in docker-compose, or your Kubernetes environment\n- Disable the `ENABLE_LOCAL_CALLBACK_EXAMPLE` environment variable\n- Set the `API_KEY` environment variable to protect the REST endpoints\n- Run periodically the `/api/terminateInactiveSessions` endpoint to prevent useless sessions to take up space and resources(only in case you are not in control of the sessions)\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## Disclaimer\n\nThis 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 https://whatsapp.com. \"WhatsApp\" as well as related names, marks, emblems and images are registered trademarks of their respective owners.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](./LICENSE.md) file for details.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=chrishubert/whatsapp-api\u0026type=Date)](https://star-history.com/#chrishubert/whatsapp-api\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrishubert%2Fwhatsapp-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrishubert%2Fwhatsapp-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrishubert%2Fwhatsapp-api/lists"}