A Slack bot that celebrates birthdays with AI-generated personalized messages and images.

• AI Messages: Personalized birthday wishes using OpenAI GPT-4.1
• AI Images: Face-accurate images using Slack profile photos (GPT-Image-1.5)
• 9 Personalities: Ludo the Mystic Dog, Captain BirthdayBeard, TechBot 3000, and more
• Multi-Timezone: Celebrates at 9 AM in each user's timezone
• Special Days: 75+ UN/WHO/UNESCO observances with AI-generated content
• Smart Consolidation: Single message for multiple same-day birthdays
• Slash Commands: /birthday and /special-day with modal forms
• App Home: Dashboard with birthday status and upcoming birthdays
• Block Kit UI: Professional Slack message layouts

1. Go to api.slack.com/apps → Create New App
2. Enable Socket Mode with connections:write scope
3. Add Bot Events: app_mention, member_joined_channel, message.channels, message.im, app_home_opened
4. Add Bot Scopes: chat:write, chat:write.public, users:read, users.profile:read, files:write, channels:read, im:write, im:read, emoji:read, commands
5. Add Slash Commands: /birthday, /special-day
6. Enable Interactivity & Shortcuts (for modal forms)
7. Enable App Home → Home Tab
8. Install to workspace

pip install -r requirements.txt
cp .env.example .env

Required in .env:

SLACK_BOT_TOKEN="xoxb-..."
SLACK_APP_TOKEN="xapp-..."
BIRTHDAY_CHANNEL_ID="C..."
OPENAI_API_KEY="sk-..."

python app.py

OPENAI_MODEL="gpt-4.1"              # AI model (default: gpt-4.1)
AI_IMAGE_GENERATION_ENABLED="true"  # Enable AI images
EXTERNAL_BACKUP_ENABLED="true"      # Backup to admin DMs

• Timezone-aware (default): Celebrates at 9 AM per user's timezone
• Simple mode: Single daily check at 10 AM server time

Toggle with admin timezone enable/disable.

brightdaybot/
├── app.py                  # Entry point
├── config.py               # Configuration
├── personality_config.py   # Personality definitions
├── handlers/               # Command & event handlers
│   ├── slash_commands.py   # /birthday, /special-day
│   ├── modal_handlers.py   # Birthday form modal
│   ├── app_home.py         # App Home dashboard
│   └── event_handler.py    # DM & channel events
├── services/               # Business logic
│   ├── birthday.py         # Celebrations
│   ├── celebration.py      # Pipeline & validation
│   └── scheduler.py        # Background tasks
├── utils/                  # Utilities
│   ├── message_generator.py
│   ├── image_generator.py
│   └── block_builder.py
└── data/
    ├── storage/            # Birthday data, configs
    ├── logs/               # 9 component logs
    ├── backups/            # Auto backups
    └── cache/              # Images, profiles

# systemd service
sudo nano /etc/systemd/system/brightdaybot.service

[Unit]
Description=BrightDayBot
After=network-online.target

[Service]
Type=simple
ExecStart=/path/to/venv/bin/python /path/to/app.py
WorkingDirectory=/path/to/brightdaybot
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now brightdaybot

1. Health check: admin status in Slack
2. Logs: Check data/logs/ (ai.log, birthday.log, etc.)
3. Common issues:
   • Missing API keys → Check .env
   • Image failures → Verify OpenAI key has image access
   • Timezone issues → User must set timezone in Slack profile

See LICENSE.