Class: Livechat::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/livechat/configuration.rb

Overview

Host-tunable settings. Everything has a safe default, so a fresh install works with zero configuration; the hooks below let an app decide who can chat, who answers, and how everyone is named.

Constant Summary collapse

DEFAULT_AGENT_LAYOUT =

The gem's own agent layout. Compared against, so DashboardController can tell "the host left this alone" from "the host chose this".

'livechat/application'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/livechat/configuration.rb', line 127

def initialize
  @app_name = nil
  @enabled = ->(_request) { true }
  @authorize_agent = ->(_request) { Rails.env.development? }
  @agent_layout = DEFAULT_AGENT_LAYOUT
  @base_controller_class = 'ActionController::Base'
  @current_user = ->(_request) {}
  @visitor_label = ->(user) { user.try(:name).presence || user.try(:email).presence || user.to_s }
  @agent_label = ->(user) { user.try(:name).presence || user.try(:email).presence || user.to_s }
  @agent_display_name = ->(label) { label }
  @greeting = nil
  @reply_time_text = nil
  @launcher_label = nil
  @avatar_url = nil
  @accent_color = nil
  @show_launcher = true
  @agent_emails = nil
  @mailer_from = nil
  @on_visitor_message = ->(_message) {}
  @on_agent_message = ->(_message) {}
  @rate_limit = { to: 30, within: 60 }
  @mount_path = '/livechat'
  @attach_files = true
  @storage_service = nil
  @max_attachments = 5
  @max_attachment_size = 10 * 1024 * 1024
  @allowed_attachment_types = nil
  @action_cable = false
  @action_cable_url = '/cable'
end

Instance Attribute Details

#accent_color ⇒ Object

Brand color for the widget (launcher, header, visitor bubbles, send button) as a hex value, e.g. "#7c3aed". The widget picks black or white text automatically for contrast. nil keeps the built-in blue.



74
75
76
 
# File 'lib/livechat/configuration.rb', line 74

def accent_color
  @accent_color
end

#action_cable ⇒ Object

Push new messages over Action Cable instead of waiting for the next poll. Opt-in and off by default: polling stays the transport, so a host that never mounts a cable keeps working; when on (and Action Cable is present) a new message nudges the widget and the inbox to refresh at once. Requires /cable mounted in the host's routes.



117
118
119
 
# File 'lib/livechat/configuration.rb', line 117

def action_cable
  @action_cable
end

#action_cable_url ⇒ Object

Where the host mounts Action Cable. Only consulted when action_cable is on. Keep in sync with the mount ActionCable... => "/cable" in routes.



121
122
123
 
# File 'lib/livechat/configuration.rb', line 121

def action_cable_url
  @action_cable_url
end

#agent_display_name ⇒ Object

What visitors see as the sender of an agent message. Receives the stored agent_label; return it unchanged (default), a first name, or a constant like "Support team" to keep agents anonymous.



60
61
62
 
# File 'lib/livechat/configuration.rb', line 60

def agent_display_name
  @agent_display_name
end

#agent_emails ⇒ Object

Email addresses to notify when a visitor writes and nobody has read it — an array, or a callable returning one. nil disables the built-in email.



82
83
84
 
# File 'lib/livechat/configuration.rb', line 82

def agent_emails
  @agent_emails
end

#agent_label ⇒ Object

Turn a resolved user into the attribution stored on an agent's message. Every reply carries this, so a thread with several teammates stays legible.



55
56
57
 
# File 'lib/livechat/configuration.rb', line 55

def agent_label
  @agent_label
end

#agent_layout ⇒ Object

Layout used by the built-in inbox. Override this to render Livechat inside your app's admin shell, e.g. "admin/application".



27
28
29
 
# File 'lib/livechat/configuration.rb', line 27

def agent_layout
  @agent_layout
end

#allowed_attachment_types ⇒ Object

Cap on attachments per message, on the size of each file (bytes), and an optional content-type allowlist (nil accepts any type). Enforced on the server; a rejected upload comes back as a validation error.



110
111
112
 
# File 'lib/livechat/configuration.rb', line 110

def allowed_attachment_types
  @allowed_attachment_types
end

#app_name ⇒ Object

Shown in the widget header and in notification emails. nil resolves to the Rails application name.



14
15
16
 
# File 'lib/livechat/configuration.rb', line 14

def app_name
  @app_name
end

#attach_files ⇒ Object

Let visitors and agents attach files to messages. Requires Active Storage in the host app (rails active_storage:install); silently ignored when it isn't present, so the widget keeps working. Set false to turn attachments off even where Active Storage exists.



100
101
102
 
# File 'lib/livechat/configuration.rb', line 100

def attach_files
  @attach_files
end

#authorize_agent ⇒ Object

Per-request gate for the inbox. Defaults to development only — override it before deploying, e.g. with an admin check. Independent of enabled, so your team can answer from production even where the widget is off.



23
24
25
 
# File 'lib/livechat/configuration.rb', line 23

def authorize_agent
  @authorize_agent
end

#avatar_url ⇒ Object

Optional customer-facing avatar shown in the widget header. Use a URL string, or a callable receiving the request for tenant-specific branding. nil keeps the text-only header.



69
70
71
 
# File 'lib/livechat/configuration.rb', line 69

def avatar_url
  @avatar_url
end

#base_controller_class ⇒ Object

The controller the INBOX inherits from, as a String so it resolves lazily rather than at config time. Default: a plain 'ActionController::Base', where authorize_agent is the only gate.

Name the controller your own admin already inherits from and the inbox adopts that whole stack — layout, helpers, authentication, and any request context your before_actions set up. agent_layout covers only the layout, which leaves a host layout calling its own helpers to raise NameError under the engine's isolated namespace.

Only the inbox uses it. The widget's endpoints stay on the engine's own public controller, so an admin base controller here can never demand a staff session from a visitor starting a chat.



42
43
44
 
# File 'lib/livechat/configuration.rb', line 42

def base_controller_class
  @base_controller_class
end

#current_user ⇒ Object

Resolve the current user (optional). Return an object responding to #id, or nil. Receives the request. Signed-in users keep one conversation across devices; guests are tracked with a cookie.



47
48
49
 
# File 'lib/livechat/configuration.rb', line 47

def current_user
  @current_user
end

#enabled ⇒ Object

Per-request gate for the widget and its endpoints. Return false to hide the widget and reject writes for this request.



18
19
20
 
# File 'lib/livechat/configuration.rb', line 18

def enabled
  @enabled
end

#greeting ⇒ Object

Widget copy. nil uses the localized defaults. reply_time_text is the honest line under the greeting — "We usually reply within a few hours."



64
65
66
 
# File 'lib/livechat/configuration.rb', line 64

def greeting
  @greeting
end

#launcher_label ⇒ Object

Widget copy. nil uses the localized defaults. reply_time_text is the honest line under the greeting — "We usually reply within a few hours."



64
65
66
 
# File 'lib/livechat/configuration.rb', line 64

def launcher_label
  @launcher_label
end

#mailer_from ⇒ Object

From-address for the built-in notification emails. Required for any email to be sent.



86
87
88
 
# File 'lib/livechat/configuration.rb', line 86

def mailer_from
  @mailer_from
end

#max_attachment_size ⇒ Object

Cap on attachments per message, on the size of each file (bytes), and an optional content-type allowlist (nil accepts any type). Enforced on the server; a rejected upload comes back as a validation error.



110
111
112
 
# File 'lib/livechat/configuration.rb', line 110

def max_attachment_size
  @max_attachment_size
end

#max_attachments ⇒ Object

Cap on attachments per message, on the size of each file (bytes), and an optional content-type allowlist (nil accepts any type). Enforced on the server; a rejected upload comes back as a validation error.



110
111
112
 
# File 'lib/livechat/configuration.rb', line 110

def max_attachments
  @max_attachments
end

#mount_path ⇒ Object

Where the engine is mounted. The widget calls paths under it, so keep this in sync with the mount line in your routes.



125
126
127
 
# File 'lib/livechat/configuration.rb', line 125

def mount_path
  @mount_path
end

#on_agent_message ⇒ Object

Called with each saved Livechat::Message — wire up Slack, Noticed, push… Runs inline after save; keep it fast or hand off to a job.



90
91
92
 
# File 'lib/livechat/configuration.rb', line 90

def on_agent_message
  @on_agent_message
end

#on_visitor_message ⇒ Object

Called with each saved Livechat::Message — wire up Slack, Noticed, push… Runs inline after save; keep it fast or hand off to a job.



90
91
92
 
# File 'lib/livechat/configuration.rb', line 90

def on_visitor_message
  @on_visitor_message
end

#rate_limit ⇒ Object

Per-IP throttle for the public endpoints, as keyword arguments for Rails' rate limiter (Rails 7.2+; ignored on 7.1). nil disables it.



94
95
96
 
# File 'lib/livechat/configuration.rb', line 94

def rate_limit
  @rate_limit
end

#reply_time_text ⇒ Object

Widget copy. nil uses the localized defaults. reply_time_text is the honest line under the greeting — "We usually reply within a few hours."



64
65
66
 
# File 'lib/livechat/configuration.rb', line 64

def reply_time_text
  @reply_time_text
end

#show_launcher ⇒ Object

The floating launcher bubble. Set false to open the widget only from your own elements carrying data-livechat-open.



78
79
80
 
# File 'lib/livechat/configuration.rb', line 78

def show_launcher
  @show_launcher
end

#storage_service ⇒ Object

Named Active Storage service for chat attachments. nil uses the host app's default service; set this to route files to a dedicated bucket, folder, or provider-specific service entry.



105
106
107
 
# File 'lib/livechat/configuration.rb', line 105

def storage_service
  @storage_service
end

#visitor_label ⇒ Object

Turn a resolved user into the visitor name shown in the inbox.



50
51
52
 
# File 'lib/livechat/configuration.rb', line 50

def visitor_label
  @visitor_label
end

Instance Method Details

#agent_email_list ⇒ Object 



160
161
162
163
164
 
# File 'lib/livechat/configuration.rb', line 160

def agent_email_list
  list = agent_emails
  list = list.call if list.respond_to?(:call)
  Array(list).compact_blank
end

#emails_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


166
 
# File 'lib/livechat/configuration.rb', line 166

def emails_enabled? = mailer_from.present?

#widget_endpoint ⇒ Object 



158
 
# File 'lib/livechat/configuration.rb', line 158

def widget_endpoint = "#{mount_path.chomp('/')}/widget"