Noticed

Noticed supports two top-level types of delivery methods:

1. Individual Deliveries: Each recipient receives their own unique notification. This is used when different recipients need different information related to the same event (e.g., a buyer receiving contract details while a salesperson receives commission details).
2. Bulk Deliveries: A single notification is sent to all recipients. This is typically used for pushing updates to external platforms where users are managed (e.g., Slack or Discord) to notify a group of people with the same content.

Supported Individual Delivery Methods

• ActionCable
• Action Push Native
• Apple Push Notification Service
• Email
• Firebase Cloud Messaging (iOS, Android, and web clients)
• Microsoft Teams
• Slack
• Twilio Messaging (SMS, Whatsapp)
• Vonage SMS
• Test

Supported Bulk Delivery Methods

• Bluesky
• Discord
• Slack
• Webhook

Use the deliver_by :email block to configure how notifications are sent via email. You must specify the mailer and the method to be called on that mailer. You can also provide custom params, positional args, or keyword kwargs via lambdas.

By default, config.enqueue is false because Noticed already handles deliveries in separate jobs. Set config.enqueue = true only if you explicitly want to use deliver_later to queue the email via ActiveJob.

deliver_by :email do |config|
  config.mailer = "UserMailer"
  config.method = :invoice_paid
  config.params = ->{ params }
  config.args = ->{ [1, 2, 3] }
  config.kwargs = ->{ {body: "Hey there", subject: "Thanks for joining"} }

  # Enqueues a separate job for sending the email using deliver_later.
  # config.enqueue = false
end

Use the deliver_by :twilio_messaging block to send SMS or WhatsApp messages via Twilio. You can customize the JSON payload, provide credentials, and specify the API URL.

By default, the payload uses params[:message] for the body, credentials from Rails.application.credentials.twilio, and the Twilio Messages API URL.

deliver_by :twilio_messaging do |config|
  config.json = -> {
    {
       From: "+1234567890",
       To: recipient.phone_number,
       ContentSid: "value", # Template SID
       ContentVariables: {1: recipient.first_name}
    }
  }
end

The :test delivery method allows you to save deliveries in memory instead of sending them via a real transport (like email or SMS). This is useful for testing notification logic in your test suite.

To use it, add deliver_by :test to your notifier class. You can then inspect all deliveries sent during the session using Noticed::DeliveryMethods::Test.delivered.

class CommentNotification
  deliver_by :test
end

# To inspect delivered notifications:
Noticed::DeliveryMethods::Test.delivered #=> []

You can deliver notifications to the browser in real-time using the :action_cable delivery method. This allows you to broadcast notification data directly to an ActionCable channel.

Configure the delivery method within your notification class using the deliver_by block.

deliver_by :action_cable do |config|
  config.channel = "Noticed::NotificationChannel"
  config.stream = ->{ recipient }
  config.message = ->{ params.merge( user_id: recipient.id) }
end

You can implement a pattern where a notification is sent via a real-time service first, and then sent via email if the user hasn't read it after a certain period. This is achieved by combining multiple deliver_by calls with the wait and if/unless options.

Note: You must manually call the #mark_as_read method on the notification in your application logic for the unless condition to work.

class NewCommentNotifier < Noticed::Event
  deliver_by :action_cable
  deliver_by :email do |config|
    config.mailer = "CommentMailer"
    config.wait = 15.minutes
    config.unless = -> { read? }
  end
end

You can implement custom error handling for Twilio delivery failures using the error_handler option. The handler receives a twilio_error_response object. You can parse the response body to inspect Twilio error codes (e.g., 21211 for an invalid 'To' number) and decide how to react.

deliver_by :twilio_messaging do |config|
  config.error_handler = lambda do |twilio_error_response|
    error_hash = JSON.parse(twilio_error_response.body)
    case error_hash["code"]
    when 21211
      # The 'To' number is not a valid phone number.
      # Write your error handling code
    else
      raise "Unhandled Twilio error: #{error_hash}"
    end
  end
end

You can use the :bluesky bulk delivery method to create posts on Bluesky from your notifications. Within the bulk_deliver_by :bluesky block, you must provide an identifier (your username), a password, and a json lambda that returns the post payload.

The json payload should include:

• text: The content of the post.
• createdAt: The timestamp of the post in ISO8601 format.

class CommentNotification
  bulk_deliver_by :bluesky do |config|
    config.identifier = "username"
    config.password = "password"
    config.json = -> {
      {
        text: "Hello world!",
        createdAt: Time.current.iso8601
        # ...
      }
    }
  end
end