Catching messages on Gmail from clients always has me running late, and checking it over and over can be a real drag. That's why I created `whatsapp ping`! It lets me ping myself on WhatsApp using a webhook.
https://github.com/user-attachments/assets/f46a909d-a0c8-4cd1-9fcb-56dce1e3d40b
### Use Cases
few use cases of this project generated by gpt.
- 🔔 Instant Notifications: Get WhatsApp alerts for important client emails.
- 📬 Stay Connected: Easily send quick messages to your team or clients.
- 📅 Task Reminders: Schedule pings to remind yourself of upcoming tasks.
- 🎉 Timely Notification: Wish your friend a happy birthday right on time.
- 👨💻 Programmatic Use: Thanks to webhooks, integrate notifications into any app or service.
### Usage
clone or fork the repo and install all dependencies using your favorite package manager. In my case, i'm using `pnpm`.
```bash
pnpm i
```
**Prepare environment variables:**
you need two env variables to make this work
```env
API_KEY=YOUR_API_KEY
MONGO_URL=your_url
# optional
SELF_HOSTED=boolean -> set to true if running in self-hosted environment
LOCAL=boolean -> for development purposes
NEXT_MSG_DELAY=number > delays between next message
```
We use `api-key` for authentication you can use any key you like to use but we recommend using strong key that is not vulnerable to `brute-force` attack.
```bash
openssl rand -base64 256
```
To run this bot in a serverless environment, we use MongoDB to manage the authentication state.
You can Get the MongoDB URL for free from their [website](https://www.mongodb.com/).
```js
mongodb+srv://:@cluster0.usggwa4.mongodb.net/?retryWrites=true&w=majority
```
**start the server using the following command:**
```bash
pnpm dev # start development server
OR
pnpm start # start server in production
```
After starting the server, it will print QR code in the terminal scan it using your phone to connect whatsapp.
### ⚓ Web Hook Usage
Next use web hook as following to send a message,
```c
curl -X POST localhost:8080/ping \
-H "Authorization: Bearer $YOUR_API_KEY"
-d '{
"message": "hello world",
"numbers": ["123456789012"]
}'
```
using js,
```js
fetch("http://localhost:8080/ping", {
headers: {
Authorization: "Bearer YOUR_KEY",
"Content-Type": "application/json"
},
method: "POST",
body: JSON.stringify({
message: "hey",
image: "optional BASE64 image",
numbers: ["<...number>"]
})
})
.then((res) => res.text())
.then((res) => console.log(res));
```
### Caveats
```diff
- If you plan to deploy this project, it currently works only on VPS and not in a serverless environment. This means you will not be able to deploy it to the Vercel or other serverless providers.
+ We just added support for serverless deployment https://github.com/Zain-ul-din/whatsapp-ping/issues/2
```
## 😻 Sponsors
A big thank you to these people for supporting this project.
