WhatsApp HappyBDay

Monitor WhatsApp groups to dynamically detect people who should be congratulated. It identifies keywords (e.g., "birthday", "congratulations") and the person's name using a score-based system, then automatically sends a random customizable congratulatory message.

zero-astro@zero-astro

Install

openclaw skills install @zero-astro/whatsapp-happybday

WhatsApp HappyBDay Skill

A skill to automatically detect when someone is being congratulated in WhatsApp groups and send them a random, customizable congratulatory message.

It dynamically checks recent messages across all active groups, uses a score-based NLP approach to prevent false positives, and supports any language via customizable dictionaries.

Features

Dynamic Group Monitoring: Automatically fetches active groups and recent messages via wacli. No need to hardcode group names.
Score-Based Keyword Detection: Uses a weighted scoring system (e.g., "birthday" = +40 pts, "family" = -50 pts) to accurately detect congratulatory intent.
Name Identification: Extracts the name of the person being congratulated from the messages using Regex and dictionary filtering.
Enhanced Skip List: Supports both permanent skips (e.g., your own name) AND date-based skips (skip only on specific birthdays). Format: "Name|MM-DD,OtherName" where names with |MM-DD are skipped ONLY on that date, and names without the pipe are permanently skipped.
Fully Customizable: Uses external JSON files (messages.json and scoring_words.json) so you can adapt it to any language or vibe.
Simulation Mode: Test the logic safely without actually sending messages.

Dependencies

Python 3: Ensure Python 3 is installed on your system.
Python Packages: The script requires the python-dotenv package to read environment variables from .env. You can install it using the provided requirements.txt:
bash
```
pip install -r ~/.openclaw/skills/whatsapp-happybday/requirements.txt
```
wacli: OpenClaw already provides a wacli skill out of the box. Just ensure that the wacli skill is activated, available to the agent, and properly configured (i.e., you have completed the authentication process by following its own instructions).

Setup & Configuration

To make the skill work, you need to configure a few environment variables and (optionally) customize the dictionaries.

1. Environment Variables (`.env`)

Create a .env file in the skill's root directory (~/.openclaw/skills/whatsapp-happybday/.env) or export these variables in your environment:

bash

# Skip list with enhanced format:
# - "Name|MM-DD" = skip this person ONLY on their birthday (date-based)
# - "Name" (no pipe) = permanently skip this name (e.g., your own name)
# Examples: "John|01-15,Jane,Alice|12-25"
export BIRTHDAY_SKIP_LIST="Urtzi|03-16,Iraide,Xune,Eñaut|08-25"

# Minimum messages mentioning the name before triggering (default: 3)
export BIRTHDAY_MIN_MESSAGES="3"

# Minimum score threshold to trigger the congratulation (default: 120)
export BIRTHDAY_CONFIDENCE_THRESHOLD="120"

# Simulation mode (true = dry-run/logging only, false = actually send messages) (default: true)
export BIRTHDAY_SIMULATE="true"

2. Dictionaries

The skill uses two JSON files. If they don't exist, it uses English defaults.

scoring_words.json: Defines the words and their point values.

json

{
  "birthday": {"words": ["birthday", "years", "candle", "cake"], "points": 40},
  "general": {"words": ["congratulations", "congrats", "celebrate", "day", "happy", "party"], "points": 15},
  "negative": {"words": ["family", "son", "daughter", "child", "kid", "work", "job"], "points": -50}
}

messages.json: Templates for the automated responses.

json

{
  "greetings": [
    "Happy birthday, {name}!", 
    "Congrats {name}!!"
  ],
  "wishes": [
    "Have a great day!", 
    "Wishing you the best!"
  ],
  "emojis": ["🎉", "🎂", "🥳"]
}

Note: The script combines one greeting, one wish, and 1-4 random emojis.

Agent Integration

For the system to work autonomously, your OpenClaw agent needs to continuously sync WhatsApp messages and run the detection script.

1. Syncing Messages (`HEARTBEAT.md`)

The Python script reads from the local wacli database, so it must be kept up to date. Add the following to your workspace's HEARTBEAT.md:

markdown

## WhatsApp Synchronization and Birthday/Congrats Monitoring

- **Action:** Run `wacli sync --once`. Afterward, check if there are any new congratulatory/birthday messages in the configured WhatsApp groups.
- **Silence Rule (CRITICAL):** If there are no errors AND no new congratulatory messages or new people detected to congratulate, **DO NOT SEND ANY MESSAGE**. Respond ONLY with the exact string `HEARTBEAT_OK`. The user does not want to receive empty notifications or status updates between 08:00 and 20:00. Only report positive findings or critical system errors.

2. Automated Execution (Cron Job)

Create a cron job to run the monitor script periodically (e.g., every hour between 8 AM and 8 PM). Run this in your terminal: