🔔 Webchat Audio Notifications

---

name: webchat-audio-notifications

description: Add browser audio notifications to Moltbot/Clawdbot webchat with 5 intensity levels - from whisper to impossible-to-miss (only when tab is backgrounded).

version: 1.1.0

author: brokemac79

repository: https://github.com/brokemac79/webchat-audio-notifications

homepage: https://github.com/brokemac79/webchat-audio-notifications

tags:

- webchat

- notifications

- audio

- ux

- browser

- howler

metadata:

clawdbot:

emoji: 🔔

compatibility:

minVersion: "2026.1.0"

browsers:

- Chrome 92+

- Firefox 90+

- Safari 15+

- Edge 92+

dependencies:

- howler.js (included)

files:

- client/howler.min.js

- client/notification.js

- client/sounds/notification.mp3

- client/sounds/alert.mp3

install:

- kind: manual

label: Install webchat audio notifications

instructions: |

1. Copy files to your webchat directory:

- client/howler.min.js → /webchat/js/

- client/notification.js → /webchat/js/

- client/sounds/ → /webchat/sounds/

2. Add to your webchat HTML before closing </body>:

```html

<script src="/js/howler.min.js"></script>

<script src="/js/notification.js"></script>

<script>

const notifier = new WebchatNotifications({

soundPath: '/sounds/notification'

});

notifier.init();

</script>

```

3. Hook into message events:

```javascript

socket.on('message', () => {

if (notifier) notifier.notify();

});

```

4. Test by switching tabs and triggering a message

See docs/integration.md for full guide.

---

# 🔔 Webchat Audio Notifications

Browser audio notifications for Moltbot/Clawdbot webchat. Plays a notification sound when new messages arrive - but only when the tab is in the background.

Features

Quick Start

Test the POC

cd examples
python3 -m http.server 8080
# Open http://localhost:8080/test.html

**Test steps:**

1. Switch to another tab

2. Click "Trigger Notification"

3. Hear the sound! 🔊

Basic Integration

// Initialize
const notifier = new WebchatNotifications({
  soundPath: './sounds',
  soundName: 'level3',  // Medium intensity (default)
  defaultVolume: 0.7
});

await notifier.init();

// Trigger on new message
socket.on('message', () => notifier.notify());

// Use different levels for different events
socket.on('mention', () => {
  notifier.setSound('level5');  // Loudest for mentions
  notifier.notify();
});

API

Constructor Options

new WebchatNotifications({
  soundPath: './sounds',               // Path to sounds directory
  soundName: 'level3',                 // level1 (whisper) to level5 (very loud)
  defaultVolume: 0.7,                  // 0.0 to 1.0
  cooldownMs: 3000,                    // Min time between alerts
  enableButton: true,                  // Show enable prompt
  debug: false                         // Console logging
});

**Intensity Levels:**

Methods

Browser Compatibility

| Browser | Version | Support |

|---------|---------|---------|

| Chrome | 92+ | ✅ Full |

| Firefox | 90+ | ✅ Full |

| Safari | 15+ | ✅ Full |

| Mobile | Latest | ⚠️ Limited |

**Overall:** 92% of users (Web Audio API support)

File Structure

webchat-audio-notifications/
├── client/
│   ├── notification.js       # Main class (10KB)
│   ├── howler.min.js         # Audio library (36KB)
│   └── sounds/
│       ├── level1.mp3        # Whisper (9.5KB)
│       ├── level2.mp3        # Soft (12KB)
│       ├── level3.mp3        # Medium (13KB, default)
│       ├── level4.mp3        # Loud (43KB)
│       └── level5.mp3        # Very Loud (63KB)
├── examples/
│   └── test.html            # Standalone test with all levels
├── docs/
│   └── integration.md       # Integration guide
└── README.md                # Full documentation

Integration Guide

See `docs/integration.md` for:

Configuration Examples

Simple

const notifier = new WebchatNotifications();
await notifier.init();
notifier.notify();

Advanced

const notifier = new WebchatNotifications({
  soundPath: '/assets/sounds',
  soundName: 'level2',  // Start with soft
  defaultVolume: 0.8,
  cooldownMs: 5000,
  debug: true
});

await notifier.init();

// Regular messages = soft
socket.on('message', () => {
  notifier.setSound('level2');
  notifier.notify();
});

// Mentions = very loud
socket.on('mention', () => {
  notifier.setSound('level5');
  notifier.notify();
});

// DMs = loud
socket.on('dm', () => {
  notifier.setSound('level4');
  notifier.notify();
});

With UI Controls

<input type="range" min="0" max="100" 
       onchange="notifier.setVolume(this.value / 100)">
<button onclick="notifier.test()">Test 🔊</button>

Troubleshooting

**No sound?**

**Sound plays when tab active?**

**Mobile not working?**

Performance

Security

License

MIT License

Credits

Contributing

1. Test with `examples/test.html`

2. Enable debug mode

3. Report issues with browser + console output

Roadmap

---

**Status:** ✅ v1.1.0 Complete - 5 Intensity Levels

**Tested:** Chrome, Firefox, Safari

**Ready for:** Production use & ClawdHub publishing

Links