WhatsAppNotifier

whatsapp_notifier is production-ready WhatsApp messaging for Rails. Set it up in minutes with one install generator and one service command.

No official WhatsApp API setup, app review, or Meta webhook configuration is required.

What You Get

• Bun-powered lightweight WhatsApp Web service (embedded in the gem)
• QR scanning and connection status APIs
• Single message and bulk message delivery APIs
• Mailer-like notification classes with deliver_now / deliver_later
• Multi-user session support via metadata[:user_id]

Quick Start (60 seconds)

bundle add whatsapp_notifier
bin/rails g whatsapp_notifier:install
bin/dev

Then:

• open /dashboard/whatsapp/qr
• scan QR
• send a test message

If setup fails, run:

bundle exec whatsapp_notifier doctor

Installation

gem "whatsapp_notifier"

bundle install
bin/rails g whatsapp_notifier:install

Scan QR and check status

# Use current_user.id for multi-user apps; omit metadata for a default shared session.
qr_data_url = WhatsAppNotifier.scan_qr(metadata: { user_id: current_user.id })

status = WhatsAppNotifier.connection_status(metadata: { user_id: current_user.id })
# => { state: "...", authenticated: true/false, has_qr: true/false }

Log out (disconnect + clear session)

Explicitly disconnects the user and wipes their saved WhatsApp session from the service, so the next connect starts fresh with a new QR. Call this from a user-initiated "Log out WhatsApp" action — NOT from your app's sign-out, which should leave the WhatsApp session intact for the next login.

WhatsAppNotifier.logout(metadata: { user_id: current_user.id })
# => { success: true }

The mounted engine also exposes DELETE /whatsapp/logout for the same effect.

Send a message

result = WhatsAppNotifier.deliver(
  to: "+919999999999",
  body: "Booking confirmed",
  metadata: { user_id: current_user.id }
)

result.success?

Notifications API

class LeadWhatsappNotification < WhatsAppNotifier::Notification
  def to
    params[:lead].phone_number
  end

  def message
    "Hi #{params[:lead].name}, we are working on your itinerary."
  end

  def metadata
    { user_id: params[:user].id }
  end
end

LeadWhatsappNotification.with(lead: @lead, user: current_user).deliver_later

Bulk Messaging

messages = [
  { to: "+919999999991", body: "Hello A", metadata: { user_id: current_user.id } },
  { to: "+919999999992", body: "Hello B", metadata: { user_id: current_user.id } }
]

summary = WhatsAppNotifier.deliver_bulk(messages)
summary[:success]

Generators

Install everything with one command:

rails generate whatsapp_notifier:install

If you want to eject Bun service files into your app:

rails generate whatsapp_notifier:install_service

This copies the service to whatsapp_service/ and updates .gitignore.

Notes

• This gem uses WhatsApp Web automation. Use responsibly and follow WhatsApp policies.
• Keep Chromium available in your runtime (or set PUPPETEER_EXECUTABLE_PATH).
• Session profiles persist under WHATSAPP_SESSION_DIR (default /whatsapp_data). Mount it on durable storage so logins survive restarts; the service clears stale Chromium SingletonLock files on each launch so an unclean exit can't wedge it.
• Resilience knobs: WHATSAPP_INIT_TIMEOUT_MS (default 90000) recycles a client that never reaches QR/READY; set WWEBJS_WEB_VERSION (e.g. 2.3000.1023204887, optionally WWEBJS_WEB_VERSION_CACHE_URL) to pin the WhatsApp Web build so a live web.whatsapp.com change can't silently break the client.

License

MIT. See LICENSE.txt.