Restructure omni services and add Chatwoot research snapshot

research/chatwoot/app/builders/account_builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class AccountBuilder
+  include CustomExceptions::Account
+  pattr_initialize [:account_name, :email!, :confirmed, :user, :user_full_name, :user_password, :super_admin, :locale]
+
+  def perform
+    if @user.nil?
+      validate_email
+      validate_user
+    end
+    ActiveRecord::Base.transaction do
+      @account = create_account
+      @user = create_and_link_user
+    end
+    [@user, @account]
+  rescue StandardError => e
+    Rails.logger.debug e.inspect
+    raise e
+  end
+
+  private
+
+  def user_full_name
+    # the empty string ensures that not-null constraint is not violated
+    @user_full_name || ''
+  end
+
+  def account_name
+    # the empty string ensures that not-null constraint is not violated
+    @account_name || ''
+  end
+
+  def validate_email
+    Account::SignUpEmailValidationService.new(@email).perform
+  end
+
+  def validate_user
+    if User.exists?(email: @email)
+      raise UserExists.new(email: @email)
+    else
+      true
+    end
+  end
+
+  def create_account
+    @account = Account.create!(name: account_name, locale: I18n.locale)
+    Current.account = @account
+  end
+
+  def create_and_link_user
+    if @user.present? || create_user
+      link_user_to_account(@user, @account)
+      @user
+    else
+      raise UserErrors.new(errors: @user.errors)
+    end
+  end
+
+  def link_user_to_account(user, account)
+    AccountUser.create!(
+      account_id: account.id,
+      user_id: user.id,
+      role: AccountUser.roles['administrator']
+    )
+  end
+
+  def create_user
+    @user = User.new(email: @email,
+                     password: user_password,
+                     password_confirmation: user_password,
+                     name: user_full_name)
+    @user.type = 'SuperAdmin' if @super_admin
+    @user.confirm if @confirmed
+    @user.save!
+  end
+end

research/chatwoot/app/builders/agent_builder.rb

@@ -0,0 +1,56 @@
+# The AgentBuilder class is responsible for creating a new agent.
+# It initializes with necessary attributes and provides a perform method
+# to create a user and account user in a transaction.
+class AgentBuilder
+  # Initializes an AgentBuilder with necessary attributes.
+  # @param email [String] the email of the user.
+  # @param name [String] the name of the user.
+  # @param role [String] the role of the user, defaults to 'agent' if not provided.
+  # @param inviter [User] the user who is inviting the agent (Current.user in most cases).
+  # @param availability [String] the availability status of the user, defaults to 'offline' if not provided.
+  # @param auto_offline [Boolean] the auto offline status of the user.
+  pattr_initialize [:email, { name: '' }, :inviter, :account, { role: :agent }, { availability: :offline }, { auto_offline: false }]
+
+  # Creates a user and account user in a transaction.
+  # @return [User] the created user.
+  def perform
+    ActiveRecord::Base.transaction do
+      @user = find_or_create_user
+      create_account_user
+    end
+    @user
+  end
+
+  private
+
+  # Finds a user by email or creates a new one with a temporary password.
+  # @return [User] the found or created user.
+  def find_or_create_user
+    user = User.from_email(email)
+    return user if user
+
+    temp_password = "1!aA#{SecureRandom.alphanumeric(12)}"
+    User.create!(email: email, name: name, password: temp_password, password_confirmation: temp_password)
+  end
+
+  # Checks if the user needs confirmation.
+  # @return [Boolean] true if the user is persisted and not confirmed, false otherwise.
+  def user_needs_confirmation?
+    @user.persisted? && !@user.confirmed?
+  end
+
+  # Creates an account user linking the user to the current account.
+  def create_account_user
+    AccountUser.create!({
+      account_id: account.id,
+      user_id: @user.id,
+      inviter_id: inviter.id
+    }.merge({
+      role: role,
+      availability: availability,
+      auto_offline: auto_offline
+    }.compact))
+  end
+end
+
+AgentBuilder.prepend_mod_with('AgentBuilder')

research/chatwoot/app/builders/campaigns/campaign_conversation_builder.rb

@@ -0,0 +1,43 @@
+class Campaigns::CampaignConversationBuilder
+  pattr_initialize [:contact_inbox_id!, :campaign_display_id!, :conversation_additional_attributes, :custom_attributes]
+
+  def perform
+    @contact_inbox = ContactInbox.find(@contact_inbox_id)
+    @campaign = @contact_inbox.inbox.campaigns.find_by!(display_id: campaign_display_id)
+
+    ActiveRecord::Base.transaction do
+      @contact_inbox.lock!
+
+      # We won't send campaigns if a conversation is already present
+      raise 'Conversation already present' if @contact_inbox.reload.conversations.present?
+
+      @conversation = ::Conversation.create!(conversation_params)
+      Messages::MessageBuilder.new(@campaign.sender, @conversation, message_params).perform
+    end
+    @conversation
+  rescue StandardError => e
+    Rails.logger.info(e.message)
+    nil
+  end
+
+  private
+
+  def message_params
+    ActionController::Parameters.new({
+                                       content: @campaign.message,
+                                       campaign_id: @campaign.id
+                                     })
+  end
+
+  def conversation_params
+    {
+      account_id: @campaign.account_id,
+      inbox_id: @contact_inbox.inbox_id,
+      contact_id: @contact_inbox.contact_id,
+      contact_inbox_id: @contact_inbox.id,
+      campaign_id: @campaign.id,
+      additional_attributes: conversation_additional_attributes,
+      custom_attributes: custom_attributes || {}
+    }
+  end
+end

research/chatwoot/app/builders/contact_inbox_builder.rb

@@ -0,0 +1,107 @@
+# This Builder will create a contact inbox with specified attributes. If the contact inbox already exists, it will be returned.
+# For Specific Channels like whatsapp, email etc . it smartly generated appropriate the source id when none is provided.
+
+class ContactInboxBuilder
+  pattr_initialize [:contact, :inbox, :source_id, { hmac_verified: false }]
+
+  def perform
+    @source_id ||= generate_source_id
+    create_contact_inbox if source_id.present?
+  end
+
+  private
+
+  def generate_source_id
+    case @inbox.channel_type
+    when 'Channel::TwilioSms'
+      twilio_source_id
+    when 'Channel::Whatsapp'
+      wa_source_id
+    when 'Channel::Email'
+      email_source_id
+    when 'Channel::Sms'
+      phone_source_id
+    when 'Channel::Api', 'Channel::WebWidget'
+      SecureRandom.uuid
+    else
+      raise "Unsupported operation for this channel: #{@inbox.channel_type}"
+    end
+  end
+
+  def email_source_id
+    raise ActionController::ParameterMissing, 'contact email' unless @contact.email
+
+    @contact.email
+  end
+
+  def phone_source_id
+    raise ActionController::ParameterMissing, 'contact phone number' unless @contact.phone_number
+
+    @contact.phone_number
+  end
+
+  def wa_source_id
+    raise ActionController::ParameterMissing, 'contact phone number' unless @contact.phone_number
+
+    # whatsapp doesn't want the + in e164 format
+    @contact.phone_number.delete('+').to_s
+  end
+
+  def twilio_source_id
+    raise ActionController::ParameterMissing, 'contact phone number' unless @contact.phone_number
+
+    case @inbox.channel.medium
+    when 'sms'
+      @contact.phone_number
+    when 'whatsapp'
+      "whatsapp:#{@contact.phone_number}"
+    end
+  end
+
+  def create_contact_inbox
+    attrs = {
+      contact_id: @contact.id,
+      inbox_id: @inbox.id,
+      source_id: @source_id
+    }
+
+    ::ContactInbox.where(attrs).first_or_create!(hmac_verified: hmac_verified || false)
+  rescue ActiveRecord::RecordNotUnique
+    Rails.logger.info("[ContactInboxBuilder] RecordNotUnique #{@source_id} #{@contact.id} #{@inbox.id}")
+    update_old_contact_inbox
+    retry
+  end
+
+  def update_old_contact_inbox
+    # The race condition occurs when there’s a contact inbox with the
+    # same source ID but linked to a different contact. This can happen
+    # if the agent updates the contact’s email or phone number, or
+    # if the contact is merged with another.
+    #
+    # We update the old contact inbox source_id to a random value to
+    # avoid disrupting the current flow. However, the root cause of
+    # this issue is a flaw in the contact inbox model design.
+    # Contact inbox is essentially tracking a session and is not
+    # needed for non-live chat channels.
+    raise ActiveRecord::RecordNotUnique unless allowed_channels?
+
+    contact_inbox = ::ContactInbox.find_by(inbox_id: @inbox.id, source_id: @source_id)
+    return if contact_inbox.blank?
+
+    contact_inbox.update!(source_id: new_source_id)
+  end
+
+  def new_source_id
+    if @inbox.whatsapp? || @inbox.sms? || @inbox.twilio?
+      "whatsapp:#{@source_id}#{rand(100)}"
+    else
+      "#{rand(10)}#{@source_id}"
+    end
+  end
+
+  def allowed_channels?
+    @inbox.email? || @inbox.sms? || @inbox.twilio? || @inbox.whatsapp?
+  end
+end
+
+ContactInboxBuilder.prepend_mod_with('ContactInboxBuilder')

research/chatwoot/app/builders/contact_inbox_with_contact_builder.rb

@@ -0,0 +1,110 @@
+# This Builder will create a contact and contact inbox with specified attributes.
+# If an existing identified contact exisits, it will be returned.
+# for contact inbox logic it uses the contact inbox builder
+
+class ContactInboxWithContactBuilder
+  pattr_initialize [:inbox!, :contact_attributes!, :source_id, :hmac_verified]
+
+  def perform
+    find_or_create_contact_and_contact_inbox
+  # in case of race conditions where contact is created by another thread
+  # we will try to find the contact and create a contact inbox
+  rescue ActiveRecord::RecordNotUnique
+    find_or_create_contact_and_contact_inbox
+  end
+
+  def find_or_create_contact_and_contact_inbox
+    @contact_inbox = inbox.contact_inboxes.find_by(source_id: source_id) if source_id.present?
+    return @contact_inbox if @contact_inbox
+
+    ActiveRecord::Base.transaction(requires_new: true) do
+      build_contact_with_contact_inbox
+    end
+    update_contact_avatar(@contact) unless @contact.avatar.attached?
+    @contact_inbox
+  end
+
+  private
+
+  def build_contact_with_contact_inbox
+    @contact = find_contact || create_contact
+    @contact_inbox = create_contact_inbox
+  end
+
+  def account
+    @account ||= inbox.account
+  end
+
+  def create_contact_inbox
+    ContactInboxBuilder.new(
+      contact: @contact,
+      inbox: @inbox,
+      source_id: @source_id,
+      hmac_verified: hmac_verified
+    ).perform
+  end
+
+  def update_contact_avatar(contact)
+    ::Avatar::AvatarFromUrlJob.perform_later(contact, contact_attributes[:avatar_url]) if contact_attributes[:avatar_url]
+  end
+
+  def create_contact
+    account.contacts.create!(
+      name: contact_attributes[:name] || ::Haikunator.haikunate(1000),
+      phone_number: contact_attributes[:phone_number],
+      email: contact_attributes[:email],
+      identifier: contact_attributes[:identifier],
+      additional_attributes: contact_attributes[:additional_attributes],
+      custom_attributes: contact_attributes[:custom_attributes]
+    )
+  end
+
+  def find_contact
+    contact = find_contact_by_identifier(contact_attributes[:identifier])
+    contact ||= find_contact_by_email(contact_attributes[:email])
+    contact ||= find_contact_by_phone_number(contact_attributes[:phone_number])
+    contact ||= find_contact_by_instagram_source_id(source_id) if instagram_channel?
+
+    contact
+  end
+
+  def instagram_channel?
+    inbox.channel_type == 'Channel::Instagram'
+  end
+
+  # There might be existing contact_inboxes created through Channel::FacebookPage
+  # with the same Instagram source_id. New Instagram interactions should create fresh contact_inboxes
+  # while still reusing contacts if found in Facebook channels so that we can create
+  # new conversations with the same contact.
+  def find_contact_by_instagram_source_id(instagram_id)
+    return if instagram_id.blank?
+
+    existing_contact_inbox = ContactInbox.joins(:inbox)
+                                         .where(source_id: instagram_id)
+                                         .where(
+                                           'inboxes.channel_type = ? AND inboxes.account_id = ?',
+                                           'Channel::FacebookPage',
+                                           account.id
+                                         ).first
+
+    existing_contact_inbox&.contact
+  end
+
+  def find_contact_by_identifier(identifier)
+    return if identifier.blank?
+
+    account.contacts.find_by(identifier: identifier)
+  end
+
+  def find_contact_by_email(email)
+    return if email.blank?
+
+    account.contacts.from_email(email)
+  end
+
+  def find_contact_by_phone_number(phone_number)
+    return if phone_number.blank?
+
+    account.contacts.find_by(phone_number: phone_number)
+  end
+end

research/chatwoot/app/builders/conversation_builder.rb

@@ -0,0 +1,40 @@
+class ConversationBuilder
+  pattr_initialize [:params!, :contact_inbox!]
+
+  def perform
+    look_up_exising_conversation || create_new_conversation
+  end
+
+  private
+
+  def look_up_exising_conversation
+    return unless @contact_inbox.inbox.lock_to_single_conversation?
+
+    @contact_inbox.conversations.last
+  end
+
+  def create_new_conversation
+    ::Conversation.create!(conversation_params)
+  end
+
+  def conversation_params
+    additional_attributes = params[:additional_attributes]&.permit! || {}
+    custom_attributes = params[:custom_attributes]&.permit! || {}
+    status = params[:status].present? ? { status: params[:status] } : {}
+
+    # TODO: temporary fallback for the old bot status in conversation, we will remove after couple of releases
+    # commenting this out to see if there are any errors, if not we can remove this in subsequent releases
+    # status = { status: 'pending' } if status[:status] == 'bot'
+    {
+      account_id: @contact_inbox.inbox.account_id,
+      inbox_id: @contact_inbox.inbox_id,
+      contact_id: @contact_inbox.contact_id,
+      contact_inbox_id: @contact_inbox.id,
+      additional_attributes: additional_attributes,
+      custom_attributes: custom_attributes,
+      snoozed_until: params[:snoozed_until],
+      assignee_id: params[:assignee_id],
+      team_id: params[:team_id]
+    }.merge(status)
+  end
+end

research/chatwoot/app/builders/csat_surveys/response_builder.rb

@@ -0,0 +1,28 @@
+class CsatSurveys::ResponseBuilder
+  pattr_initialize [:message]
+
+  def perform
+    raise 'Invalid Message' unless message.input_csat?
+
+    conversation = message.conversation
+    rating = message.content_attributes.dig('submitted_values', 'csat_survey_response', 'rating')
+    feedback_message = message.content_attributes.dig('submitted_values', 'csat_survey_response', 'feedback_message')
+
+    return if rating.blank?
+
+    process_csat_response(conversation, rating, feedback_message)
+  end
+
+  private
+
+  def process_csat_response(conversation, rating, feedback_message)
+    csat_survey_response = message.csat_survey_response || CsatSurveyResponse.new(
+      message_id: message.id, account_id: message.account_id, conversation_id: message.conversation_id,
+      contact_id: conversation.contact_id, assigned_agent: conversation.assignee
+    )
+    csat_survey_response.rating = rating
+    csat_survey_response.feedback_message = feedback_message
+    csat_survey_response.save!
+    csat_survey_response
+  end
+end

research/chatwoot/app/builders/email/base_builder.rb

@@ -0,0 +1,54 @@
+class Email::BaseBuilder
+  pattr_initialize [:inbox!]
+
+  private
+
+  def channel
+    @channel ||= inbox.channel
+  end
+
+  def account
+    @account ||= inbox.account
+  end
+
+  def conversation
+    @conversation ||= message.conversation
+  end
+
+  def custom_sender_name
+    message&.sender&.available_name || I18n.t('conversations.reply.email.header.notifications')
+  end
+
+  def sender_name(sender_email)
+    # Friendly: <agent_name> from <business_name>
+    # Professional: <business_name>
+    if inbox.friendly?
+      I18n.t(
+        'conversations.reply.email.header.friendly_name',
+        sender_name: custom_sender_name,
+        business_name: business_name,
+        from_email: sender_email
+      )
+    else
+      I18n.t(
+        'conversations.reply.email.header.professional_name',
+        business_name: business_name,
+        from_email: sender_email
+      )
+    end
+  end
+
+  def business_name
+    inbox.business_name || inbox.sanitized_name
+  end
+
+  def account_support_email
+    # Parse the email to ensure it's in the correct format, the user
+    # can save it in the format "Name <email@domain.com>"
+    parse_email(account.support_email)
+  end
+
+  def parse_email(email_string)
+    Mail::Address.new(email_string).address
+  end
+end

research/chatwoot/app/builders/email/from_builder.rb

@@ -0,0 +1,51 @@
+class Email::FromBuilder < Email::BaseBuilder
+  pattr_initialize [:inbox!, :message!]
+
+  def build
+    return sender_name(account_support_email) unless inbox.email?
+
+    from_email = case email_channel_type
+                 when :standard_imap_smtp,
+                      :google_oauth,
+                      :microsoft_oauth,
+                      :forwarding_own_smtp
+                   channel.email
+                 when :imap_chatwoot_smtp,
+                      :forwarding_chatwoot_smtp
+                   channel.verified_for_sending ? channel.email : account_support_email
+                 else
+                   account_support_email
+                 end
+
+    sender_name(from_email)
+  end
+
+  private
+
+  def email_channel_type
+    return :google_oauth if channel.google?
+    return :microsoft_oauth if channel.microsoft?
+    return :standard_imap_smtp if imap_and_smtp_enabled?
+    return :imap_chatwoot_smtp if imap_enabled_without_smtp?
+    return :forwarding_own_smtp if forwarding_with_own_smtp?
+    return :forwarding_chatwoot_smtp if forwarding_without_smtp?
+
+    :unknown
+  end
+
+  def imap_and_smtp_enabled?
+    channel.imap_enabled && channel.smtp_enabled
+  end
+
+  def imap_enabled_without_smtp?
+    channel.imap_enabled && !channel.smtp_enabled
+  end
+
+  def forwarding_with_own_smtp?
+    !channel.imap_enabled && channel.smtp_enabled
+  end
+
+  def forwarding_without_smtp?
+    !channel.imap_enabled && !channel.smtp_enabled
+  end
+end

research/chatwoot/app/builders/email/reply_to_builder.rb

@@ -0,0 +1,21 @@
+class Email::ReplyToBuilder < Email::BaseBuilder
+  pattr_initialize [:inbox!, :message!]
+
+  def build
+    reply_to = if inbox.email?
+                 channel.email
+               elsif inbound_email_enabled?
+                 "reply+#{conversation.uuid}@#{account.inbound_email_domain}"
+               else
+                 account_support_email
+               end
+
+    sender_name(reply_to)
+  end
+
+  private
+
+  def inbound_email_enabled?
+    account.feature_enabled?('inbound_emails') && account.inbound_email_domain.present?
+  end
+end

research/chatwoot/app/builders/messages/facebook/message_builder.rb

@@ -0,0 +1,157 @@
+# This class creates both outgoing messages from chatwoot and echo outgoing messages based on the flag `outgoing_echo`
+# Assumptions
+# 1. Incase of an outgoing message which is echo, source_id will NOT be nil,
+#    based on this we are showing "not sent from chatwoot" message in frontend
+#    Hence there is no need to set user_id in message for outgoing echo messages.
+
+class Messages::Facebook::MessageBuilder < Messages::Messenger::MessageBuilder
+  attr_reader :response
+
+  def initialize(response, inbox, outgoing_echo: false)
+    super()
+    @response = response
+    @inbox = inbox
+    @outgoing_echo = outgoing_echo
+    @sender_id = (@outgoing_echo ? @response.recipient_id : @response.sender_id)
+    @message_type = (@outgoing_echo ? :outgoing : :incoming)
+    @attachments = (@response.attachments || [])
+  end
+
+  def perform
+    # This channel might require reauthorization, may be owner might have changed the fb password
+    return if @inbox.channel.reauthorization_required?
+
+    ActiveRecord::Base.transaction do
+      build_contact_inbox
+      build_message
+    end
+  rescue Koala::Facebook::AuthenticationError => e
+    Rails.logger.warn("Facebook authentication error for inbox: #{@inbox.id} with error: #{e.message}")
+    Rails.logger.error e
+    @inbox.channel.authorization_error!
+  rescue StandardError => e
+    ChatwootExceptionTracker.new(e, account: @inbox.account).capture_exception
+    true
+  end
+
+  private
+
+  def build_contact_inbox
+    @contact_inbox = ::ContactInboxWithContactBuilder.new(
+      source_id: @sender_id,
+      inbox: @inbox,
+      contact_attributes: contact_params
+    ).perform
+  end
+
+  def build_message
+    @message = conversation.messages.create!(message_params)
+
+    @attachments.each do |attachment|
+      process_attachment(attachment)
+    end
+  end
+
+  def conversation
+    @conversation ||= set_conversation_based_on_inbox_config
+  end
+
+  def set_conversation_based_on_inbox_config
+    if @inbox.lock_to_single_conversation
+      Conversation.where(conversation_params).order(created_at: :desc).first || build_conversation
+    else
+      find_or_build_for_multiple_conversations
+    end
+  end
+
+  def find_or_build_for_multiple_conversations
+    # If lock to single conversation is disabled, we will create a new conversation if previous conversation is resolved
+    last_conversation = Conversation.where(conversation_params).where.not(status: :resolved).order(created_at: :desc).first
+    return build_conversation if last_conversation.nil?
+
+    last_conversation
+  end
+
+  def build_conversation
+    Conversation.create!(conversation_params.merge(
+                           contact_inbox_id: @contact_inbox.id
+                         ))
+  end
+
+  def location_params(attachment)
+    lat = attachment['payload']['coordinates']['lat']
+    long = attachment['payload']['coordinates']['long']
+    {
+      external_url: attachment['url'],
+      coordinates_lat: lat,
+      coordinates_long: long,
+      fallback_title: attachment['title']
+    }
+  end
+
+  def fallback_params(attachment)
+    {
+      fallback_title: attachment['title'],
+      external_url: attachment['url']
+    }
+  end
+
+  def conversation_params
+    {
+      account_id: @inbox.account_id,
+      inbox_id: @inbox.id,
+      contact_id: @contact_inbox.contact_id
+    }
+  end
+
+  def message_params
+    {
+      account_id: conversation.account_id,
+      inbox_id: conversation.inbox_id,
+      message_type: @message_type,
+      content: response.content,
+      source_id: response.identifier,
+      content_attributes: {
+        in_reply_to_external_id: response.in_reply_to_external_id
+      },
+      sender: @outgoing_echo ? nil : @contact_inbox.contact
+    }
+  end
+
+  def process_contact_params_result(result)
+    {
+      name: "#{result['first_name'] || 'John'} #{result['last_name'] || 'Doe'}",
+      account_id: @inbox.account_id,
+      avatar_url: result['profile_pic']
+    }
+  end
+
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/MethodLength
+  def contact_params
+    begin
+      k = Koala::Facebook::API.new(@inbox.channel.page_access_token) if @inbox.facebook?
+      result = k.get_object(@sender_id) || {}
+    rescue Koala::Facebook::AuthenticationError => e
+      Rails.logger.warn("Facebook authentication error for inbox: #{@inbox.id} with error: #{e.message}")
+      Rails.logger.error e
+      @inbox.channel.authorization_error!
+      raise
+    rescue Koala::Facebook::ClientError => e
+      result = {}
+      # OAuthException, code: 100, error_subcode: 2018218, message: (#100) No profile available for this user
+      # We don't need to capture this error as we don't care about contact params in case of echo messages
+      if e.message.include?('2018218')
+        Rails.logger.warn e
+      else
+        ChatwootExceptionTracker.new(e, account: @inbox.account).capture_exception unless @outgoing_echo
+      end
+    rescue StandardError => e
+      result = {}
+      ChatwootExceptionTracker.new(e, account: @inbox.account).capture_exception
+    end
+    process_contact_params_result(result)
+  end
+  # rubocop:enable Metrics/AbcSize
+  # rubocop:enable Metrics/MethodLength
+end

research/chatwoot/app/builders/messages/instagram/base_message_builder.rb

@@ -0,0 +1,201 @@
+class Messages::Instagram::BaseMessageBuilder < Messages::Messenger::MessageBuilder
+  attr_reader :messaging
+
+  def initialize(messaging, inbox, outgoing_echo: false)
+    super()
+    @messaging = messaging
+    @inbox = inbox
+    @outgoing_echo = outgoing_echo
+  end
+
+  def perform
+    return if @inbox.channel.reauthorization_required?
+
+    ActiveRecord::Base.transaction do
+      build_message
+    end
+  rescue StandardError => e
+    handle_error(e)
+  end
+
+  private
+
+  def attachments
+    @messaging[:message][:attachments] || {}
+  end
+
+  def message_type
+    @outgoing_echo ? :outgoing : :incoming
+  end
+
+  def message_identifier
+    message[:mid]
+  end
+
+  def message_source_id
+    @outgoing_echo ? recipient_id : sender_id
+  end
+
+  def message_is_unsupported?
+    message[:is_unsupported].present? && @messaging[:message][:is_unsupported] == true
+  end
+
+  def sender_id
+    @messaging[:sender][:id]
+  end
+
+  def recipient_id
+    @messaging[:recipient][:id]
+  end
+
+  def message
+    @messaging[:message]
+  end
+
+  def contact
+    @contact ||= @inbox.contact_inboxes.find_by(source_id: message_source_id)&.contact
+  end
+
+  def conversation
+    @conversation ||= set_conversation_based_on_inbox_config
+  end
+
+  def set_conversation_based_on_inbox_config
+    if @inbox.lock_to_single_conversation
+      find_conversation_scope.order(created_at: :desc).first || build_conversation
+    else
+      find_or_build_for_multiple_conversations
+    end
+  end
+
+  def find_conversation_scope
+    Conversation.where(conversation_params)
+  end
+
+  def find_or_build_for_multiple_conversations
+    last_conversation = find_conversation_scope.where.not(status: :resolved).order(created_at: :desc).first
+    return build_conversation if last_conversation.nil?
+
+    last_conversation
+  end
+
+  def message_content
+    @messaging[:message][:text]
+  end
+
+  def story_reply_attributes
+    message[:reply_to][:story] if message[:reply_to].present? && message[:reply_to][:story].present?
+  end
+
+  def message_reply_attributes
+    message[:reply_to][:mid] if message[:reply_to].present? && message[:reply_to][:mid].present?
+  end
+
+  def build_message
+    # Duplicate webhook events may be sent for the same message
+    # when a user is connected to the Instagram account through both Messenger and Instagram login.
+    # There is chance for echo events to be sent for the same message.
+    # Therefore, we need to check if the message already exists before creating it.
+    return if message_already_exists?
+
+    return if message_content.blank? && all_unsupported_files?
+
+    @message = conversation.messages.create!(message_params)
+    save_story_id
+
+    attachments.each do |attachment|
+      process_attachment(attachment)
+    end
+  end
+
+  def save_story_id
+    return if story_reply_attributes.blank?
+
+    @message.save_story_info(story_reply_attributes)
+    create_story_reply_attachment(story_reply_attributes['url'])
+  end
+
+  def create_story_reply_attachment(story_url)
+    return if story_url.blank?
+
+    attachment = @message.attachments.new(
+      file_type: :ig_story,
+      account_id: @message.account_id,
+      external_url: story_url
+    )
+    attachment.save!
+    begin
+      attach_file(attachment, story_url)
+    rescue Down::Error, StandardError => e
+      Rails.logger.warn "Failed to download Instagram story attachment: #{e.message}"
+    end
+    @message.content_attributes[:image_type] = 'ig_story_reply'
+    @message.save!
+  end
+
+  def build_conversation
+    @contact_inbox ||= contact.contact_inboxes.find_by!(source_id: message_source_id)
+    Conversation.create!(conversation_params.merge(
+                           contact_inbox_id: @contact_inbox.id,
+                           additional_attributes: additional_conversation_attributes
+                         ))
+  end
+
+  def additional_conversation_attributes
+    {}
+  end
+
+  def conversation_params
+    {
+      account_id: @inbox.account_id,
+      inbox_id: @inbox.id,
+      contact_id: contact.id
+    }
+  end
+
+  def message_params
+    params = {
+      account_id: conversation.account_id,
+      inbox_id: conversation.inbox_id,
+      message_type: message_type,
+      status: @outgoing_echo ? :delivered : :sent,
+      source_id: message_identifier,
+      content: message_content,
+      sender: @outgoing_echo ? nil : contact,
+      content_attributes: {
+        in_reply_to_external_id: message_reply_attributes
+      }
+    }
+
+    params[:content_attributes][:external_echo] = true if @outgoing_echo
+    params[:content_attributes][:is_unsupported] = true if message_is_unsupported?
+    params
+  end
+
+  def message_already_exists?
+    find_message_by_source_id(@messaging[:message][:mid]).present?
+  end
+
+  def find_message_by_source_id(source_id)
+    return unless source_id
+
+    @message = Message.find_by(source_id: source_id)
+  end
+
+  def all_unsupported_files?
+    return if attachments.empty?
+
+    attachments_type = attachments.pluck(:type).uniq.first
+    unsupported_file_type?(attachments_type)
+  end
+
+  def handle_error(error)
+    ChatwootExceptionTracker.new(error, account: @inbox.account).capture_exception
+    true
+  end
+
+  # Abstract methods to be implemented by subclasses
+  def get_story_object_from_source_id(source_id)
+    raise NotImplementedError
+  end
+end

research/chatwoot/app/builders/messages/instagram/message_builder.rb

@@ -0,0 +1,42 @@
+class Messages::Instagram::MessageBuilder < Messages::Instagram::BaseMessageBuilder
+  def initialize(messaging, inbox, outgoing_echo: false)
+    super(messaging, inbox, outgoing_echo: outgoing_echo)
+  end
+
+  private
+
+  def get_story_object_from_source_id(source_id)
+    url = "#{base_uri}/#{source_id}?fields=story,from&access_token=#{@inbox.channel.access_token}"
+
+    response = HTTParty.get(url)
+
+    return JSON.parse(response.body).with_indifferent_access if response.success?
+
+    # Create message first if it doesn't exist
+    @message ||= conversation.messages.create!(message_params)
+    handle_error_response(response)
+    nil
+  end
+
+  def handle_error_response(response)
+    parsed_response = JSON.parse(response.body)
+    error_code = parsed_response.dig('error', 'code')
+
+    # https://developers.facebook.com/docs/messenger-platform/error-codes
+    # Access token has expired or become invalid.
+    channel.authorization_error! if error_code == 190
+
+    # There was a problem scraping data from the provided link.
+    # https://developers.facebook.com/docs/graph-api/guides/error-handling/ search for error code 1609005
+    if error_code == 1_609_005
+      @message.attachments.destroy_all
+      @message.update(content: I18n.t('conversations.messages.instagram_deleted_story_content'))
+    end
+
+    Rails.logger.error("[InstagramStoryFetchError]: #{parsed_response.dig('error', 'message')} #{error_code}")
+  end
+
+  def base_uri
+    "https://graph.instagram.com/#{GlobalConfigService.load('INSTAGRAM_API_VERSION', 'v22.0')}"
+  end
+end

research/chatwoot/app/builders/messages/instagram/messenger/message_builder.rb

@@ -0,0 +1,33 @@
+class Messages::Instagram::Messenger::MessageBuilder < Messages::Instagram::BaseMessageBuilder
+  def initialize(messaging, inbox, outgoing_echo: false)
+    super(messaging, inbox, outgoing_echo: outgoing_echo)
+  end
+
+  private
+
+  def get_story_object_from_source_id(source_id)
+    k = Koala::Facebook::API.new(@inbox.channel.page_access_token) if @inbox.facebook?
+    k.get_object(source_id, fields: %w[story from]) || {}
+  rescue Koala::Facebook::AuthenticationError
+    @inbox.channel.authorization_error!
+    raise
+  rescue Koala::Facebook::ClientError => e
+    # The exception occurs when we are trying fetch the deleted story or blocked story.
+    @message.attachments.destroy_all
+    @message.update(content: I18n.t('conversations.messages.instagram_deleted_story_content'))
+    Rails.logger.error e
+    {}
+  rescue StandardError => e
+    ChatwootExceptionTracker.new(e, account: @inbox.account).capture_exception
+    {}
+  end
+
+  def find_conversation_scope
+    Conversation.where(conversation_params)
+                .where("additional_attributes ->> 'type' = 'instagram_direct_message'")
+  end
+
+  def additional_conversation_attributes
+    { type: 'instagram_direct_message' }
+  end
+end

research/chatwoot/app/builders/messages/message_builder.rb

@@ -0,0 +1,227 @@
+class Messages::MessageBuilder
+  include ::FileTypeHelper
+  include ::EmailHelper
+  include ::DataHelper
+
+  attr_reader :message
+
+  def initialize(user, conversation, params)
+    @params = params
+    @private = params[:private] || false
+    @conversation = conversation
+    @user = user
+    @account = conversation.account
+    @message_type = params[:message_type] || 'outgoing'
+    @attachments = params[:attachments]
+    @automation_rule = content_attributes&.dig(:automation_rule_id)
+    return unless params.instance_of?(ActionController::Parameters)
+
+    @in_reply_to = content_attributes&.dig(:in_reply_to)
+    @items = content_attributes&.dig(:items)
+  end
+
+  def perform
+    @message = @conversation.messages.build(message_params)
+    process_attachments
+    process_emails
+    # When the message has no quoted content, it will just be rendered as a regular message
+    # The frontend is equipped to handle this case
+    process_email_content
+    @message.save!
+    @message
+  end
+
+  private
+
+  # Extracts content attributes from the given params.
+  # - Converts ActionController::Parameters to a regular hash if needed.
+  # - Attempts to parse a JSON string if content is a string.
+  # - Returns an empty hash if content is not present, if there's a parsing error, or if it's an unexpected type.
+  def content_attributes
+    params = convert_to_hash(@params)
+    content_attributes = params.fetch(:content_attributes, {})
+
+    return safe_parse_json(content_attributes) if content_attributes.is_a?(String)
+    return content_attributes if content_attributes.is_a?(Hash)
+
+    {}
+  end
+
+  def process_attachments
+    return if @attachments.blank?
+
+    @attachments.each do |uploaded_attachment|
+      attachment = @message.attachments.build(
+        account_id: @message.account_id,
+        file: uploaded_attachment
+      )
+
+      attachment.file_type = if uploaded_attachment.is_a?(String)
+                               file_type_by_signed_id(
+                                 uploaded_attachment
+                               )
+                             else
+                               file_type(uploaded_attachment&.content_type)
+                             end
+    end
+  end
+
+  def process_emails
+    return unless @conversation.inbox&.inbox_type == 'Email'
+
+    cc_emails = process_email_string(@params[:cc_emails])
+    bcc_emails = process_email_string(@params[:bcc_emails])
+    to_emails = process_email_string(@params[:to_emails])
+
+    all_email_addresses = cc_emails + bcc_emails + to_emails
+    validate_email_addresses(all_email_addresses)
+
+    @message.content_attributes[:cc_emails] = cc_emails
+    @message.content_attributes[:bcc_emails] = bcc_emails
+    @message.content_attributes[:to_emails] = to_emails
+  end
+
+  def process_email_content
+    return unless should_process_email_content?
+
+    @message.content_attributes ||= {}
+    email_attributes = build_email_attributes
+    @message.content_attributes[:email] = email_attributes
+  end
+
+  def process_email_string(email_string)
+    return [] if email_string.blank?
+
+    email_string.gsub(/\s+/, '').split(',')
+  end
+
+  def message_type
+    if @conversation.inbox.channel_type != 'Channel::Api' && @message_type == 'incoming'
+      raise StandardError, 'Incoming messages are only allowed in Api inboxes'
+    end
+
+    @message_type
+  end
+
+  def sender
+    message_type == 'outgoing' ? (message_sender || @user) : @conversation.contact
+  end
+
+  def external_created_at
+    @params[:external_created_at].present? ? { external_created_at: @params[:external_created_at] } : {}
+  end
+
+  def automation_rule_id
+    @automation_rule.present? ? { content_attributes: { automation_rule_id: @automation_rule } } : {}
+  end
+
+  def campaign_id
+    @params[:campaign_id].present? ? { additional_attributes: { campaign_id: @params[:campaign_id] } } : {}
+  end
+
+  def template_params
+    @params[:template_params].present? ? { additional_attributes: { template_params: JSON.parse(@params[:template_params].to_json) } } : {}
+  end
+
+  def message_sender
+    return if @params[:sender_type] != 'AgentBot'
+
+    AgentBot.where(account_id: [nil, @conversation.account.id]).find_by(id: @params[:sender_id])
+  end
+
+  def message_params
+    {
+      account_id: @conversation.account_id,
+      inbox_id: @conversation.inbox_id,
+      message_type: message_type,
+      content: @params[:content],
+      private: @private,
+      sender: sender,
+      content_type: @params[:content_type],
+      content_attributes: content_attributes.presence,
+      items: @items,
+      in_reply_to: @in_reply_to,
+      echo_id: @params[:echo_id],
+      source_id: @params[:source_id]
+    }.merge(external_created_at).merge(automation_rule_id).merge(campaign_id).merge(template_params)
+  end
+
+  def email_inbox?
+    @conversation.inbox&.inbox_type == 'Email'
+  end
+
+  def should_process_email_content?
+    email_inbox? && !@private && @message.content.present?
+  end
+
+  def build_email_attributes
+    email_attributes = ensure_indifferent_access(@message.content_attributes[:email] || {})
+    normalized_content = normalize_email_body(@message.content)
+
+    # Process liquid templates in normalized content with code block protection
+    processed_content = process_liquid_in_email_body(normalized_content)
+
+    # Use custom HTML content if provided, otherwise generate from message content
+    email_attributes[:html_content] = if custom_email_content_provided?
+                                        build_custom_html_content
+                                      else
+                                        build_html_content(processed_content)
+                                      end
+
+    email_attributes[:text_content] = build_text_content(processed_content)
+    email_attributes
+  end
+
+  def build_html_content(normalized_content)
+    html_content = ensure_indifferent_access(@message.content_attributes.dig(:email, :html_content) || {})
+    rendered_html = render_email_html(normalized_content)
+    html_content[:full] = rendered_html
+    html_content[:reply] = rendered_html
+    html_content
+  end
+
+  def build_text_content(normalized_content)
+    text_content = ensure_indifferent_access(@message.content_attributes.dig(:email, :text_content) || {})
+    text_content[:full] = normalized_content
+    text_content[:reply] = normalized_content
+    text_content
+  end
+
+  def custom_email_content_provided?
+    @params[:email_html_content].present?
+  end
+
+  def build_custom_html_content
+    html_content = ensure_indifferent_access(@message.content_attributes.dig(:email, :html_content) || {})
+
+    html_content[:full] = @params[:email_html_content]
+    html_content[:reply] = @params[:email_html_content]
+
+    html_content
+  end
+
+  # Liquid processing methods for email content
+  def process_liquid_in_email_body(content)
+    return content if content.blank?
+    return content unless should_process_liquid?
+
+    # Protect code blocks from liquid processing
+    modified_content = modified_liquid_content(content)
+    template = Liquid::Template.parse(modified_content)
+    template.render(drops_with_sender)
+  rescue Liquid::Error
+    content
+  end
+
+  def should_process_liquid?
+    @message_type == 'outgoing' || @message_type == 'template'
+  end
+
+  def drops_with_sender
+    message_drops(@conversation).merge({
+                                         'agent' => UserDrop.new(sender)
+                                       })
+  end
+end
+
+Messages::MessageBuilder.prepend_mod_with('Messages::MessageBuilder')

research/chatwoot/app/builders/messages/messenger/message_builder.rb

@@ -0,0 +1,106 @@
+class Messages::Messenger::MessageBuilder
+  include ::FileTypeHelper
+
+  def process_attachment(attachment)
+    # This check handles very rare case if there are multiple files to attach with only one usupported file
+    return if unsupported_file_type?(attachment['type'])
+
+    attachment_obj = @message.attachments.new(attachment_params(attachment).except(:remote_file_url))
+    attachment_obj.save!
+    attach_file(attachment_obj, attachment_params(attachment)[:remote_file_url]) if attachment_params(attachment)[:remote_file_url]
+    fetch_story_link(attachment_obj) if attachment_obj.file_type == 'story_mention'
+    fetch_ig_story_link(attachment_obj) if attachment_obj.file_type == 'ig_story'
+    fetch_ig_post_link(attachment_obj) if attachment_obj.file_type == 'ig_post'
+    update_attachment_file_type(attachment_obj)
+  end
+
+  def attach_file(attachment, file_url)
+    attachment_file = Down.download(
+      file_url
+    )
+    attachment.file.attach(
+      io: attachment_file,
+      filename: attachment_file.original_filename,
+      content_type: attachment_file.content_type
+    )
+  end
+
+  def attachment_params(attachment)
+    file_type = attachment['type'].to_sym
+    params = { file_type: file_type, account_id: @message.account_id }
+
+    if [:image, :file, :audio, :video, :share, :story_mention, :ig_reel, :ig_post, :ig_story].include? file_type
+      params.merge!(file_type_params(attachment))
+    elsif file_type == :location
+      params.merge!(location_params(attachment))
+    elsif file_type == :fallback
+      params.merge!(fallback_params(attachment))
+    end
+
+    params
+  end
+
+  def file_type_params(attachment)
+    # Handle different URL field names for different attachment types
+    url = case attachment['type'].to_sym
+          when :ig_story
+            attachment['payload']['story_media_url']
+          else
+            attachment['payload']['url']
+          end
+
+    {
+      external_url: url,
+      remote_file_url: url
+    }
+  end
+
+  def update_attachment_file_type(attachment)
+    return if @message.reload.attachments.blank?
+    return unless attachment.file_type == 'share' || attachment.file_type == 'story_mention'
+
+    attachment.file_type = file_type(attachment.file&.content_type)
+    attachment.save!
+  end
+
+  def fetch_story_link(attachment)
+    message = attachment.message
+    result = get_story_object_from_source_id(message.source_id)
+
+    return if result.blank?
+
+    story_id = result['story']['mention']['id']
+    story_sender = result['from']['username']
+    message.content_attributes[:story_sender] = story_sender
+    message.content_attributes[:story_id] = story_id
+    message.content_attributes[:image_type] = 'story_mention'
+    message.content = I18n.t('conversations.messages.instagram_story_content', story_sender: story_sender)
+    message.save!
+  end
+
+  def fetch_ig_story_link(attachment)
+    message = attachment.message
+    # For ig_story, we don't have the same API call as story_mention, so we'll set it up similarly but with generic content
+    message.content_attributes[:image_type] = 'ig_story'
+    message.content = I18n.t('conversations.messages.instagram_shared_story_content')
+    message.save!
+  end
+
+  def fetch_ig_post_link(attachment)
+    message = attachment.message
+    message.content_attributes[:image_type] = 'ig_post'
+    message.content = I18n.t('conversations.messages.instagram_shared_post_content')
+    message.save!
+  end
+
+  # This is a placeholder method to be overridden by child classes
+  def get_story_object_from_source_id(_source_id)
+    {}
+  end
+
+  private
+
+  def unsupported_file_type?(attachment_type)
+    [:template, :unsupported_type, :ephemeral].include? attachment_type.to_sym
+  end
+end

research/chatwoot/app/builders/notification_builder.rb

@@ -0,0 +1,39 @@
+class NotificationBuilder
+  pattr_initialize [:notification_type!, :user!, :account!, :primary_actor!, :secondary_actor]
+
+  def perform
+    build_notification
+  end
+
+  private
+
+  def current_user
+    Current.user
+  end
+
+  def user_subscribed_to_notification?
+    notification_setting = user.notification_settings.find_by(account_id: account.id)
+    # added for the case where an assignee might be removed from the account but remains in conversation
+    return false if notification_setting.blank?
+
+    return true if notification_setting.public_send("email_#{notification_type}?")
+    return true if notification_setting.public_send("push_#{notification_type}?")
+
+    false
+  end
+
+  def build_notification
+    # Create conversation_creation notification only if user is subscribed to it
+    return if notification_type == 'conversation_creation' && !user_subscribed_to_notification?
+    # skip notifications for blocked conversations except for user mentions
+    return if primary_actor.contact.blocked? && notification_type != 'conversation_mention'
+
+    user.notifications.create!(
+      notification_type: notification_type,
+      account: account,
+      primary_actor: primary_actor,
+      # secondary_actor is secondary_actor if present, else current_user
+      secondary_actor: secondary_actor || current_user
+    )
+  end
+end

research/chatwoot/app/builders/notification_subscription_builder.rb

@@ -0,0 +1,34 @@
+class NotificationSubscriptionBuilder
+  pattr_initialize [:params, :user!]
+
+  def perform
+    # if multiple accounts were used to login in same browser
+    move_subscription_to_user if identifier_subscription && identifier_subscription.user_id != user.id
+    identifier_subscription.blank? ? build_identifier_subscription : update_identifier_subscription
+    identifier_subscription
+  end
+
+  private
+
+  def identifier
+    @identifier ||= params[:subscription_attributes][:endpoint] if params[:subscription_type] == 'browser_push'
+    @identifier ||= params[:subscription_attributes][:device_id] if params[:subscription_type] == 'fcm'
+    @identifier
+  end
+
+  def identifier_subscription
+    @identifier_subscription ||= NotificationSubscription.find_by(identifier: identifier)
+  end
+
+  def move_subscription_to_user
+    @identifier_subscription.update(user_id: user.id)
+  end
+
+  def build_identifier_subscription
+    @identifier_subscription = user.notification_subscriptions.create!(params.merge(identifier: identifier))
+  end
+
+  def update_identifier_subscription
+    identifier_subscription.update(params.merge(identifier: identifier))
+  end
+end

research/chatwoot/app/builders/v2/report_builder.rb

@@ -0,0 +1,138 @@
+class V2::ReportBuilder
+  include DateRangeHelper
+  include ReportHelper
+  attr_reader :account, :params
+
+  DEFAULT_GROUP_BY = 'day'.freeze
+  AGENT_RESULTS_PER_PAGE = 25
+
+  def initialize(account, params)
+    @account = account
+    @params = params
+
+    timezone_offset = (params[:timezone_offset] || 0).to_f
+    @timezone = ActiveSupport::TimeZone[timezone_offset]&.name
+  end
+
+  def timeseries
+    return send(params[:metric]) if metric_valid?
+
+    Rails.logger.error "ReportBuilder: Invalid metric - #{params[:metric]}"
+    {}
+  end
+
+  # For backward compatible with old report
+  def build
+    if %w[avg_first_response_time avg_resolution_time reply_time].include?(params[:metric])
+      timeseries.each_with_object([]) do |p, arr|
+        arr << { value: p[1], timestamp: p[0].in_time_zone(@timezone).to_i, count: @grouped_values.count[p[0]] }
+      end
+    else
+      timeseries.each_with_object([]) do |p, arr|
+        arr << { value: p[1], timestamp: p[0].in_time_zone(@timezone).to_i }
+      end
+    end
+  end
+
+  def summary
+    {
+      conversations_count: conversations.count,
+      incoming_messages_count: incoming_messages.count,
+      outgoing_messages_count: outgoing_messages.count,
+      avg_first_response_time: avg_first_response_time_summary,
+      avg_resolution_time: avg_resolution_time_summary,
+      resolutions_count: resolutions.count,
+      reply_time: reply_time_summary
+    }
+  end
+
+  def short_summary
+    {
+      conversations_count: conversations.count,
+      avg_first_response_time: avg_first_response_time_summary,
+      avg_resolution_time: avg_resolution_time_summary
+    }
+  end
+
+  def bot_summary
+    {
+      bot_resolutions_count: bot_resolutions.count,
+      bot_handoffs_count: bot_handoffs.count
+    }
+  end
+
+  def conversation_metrics
+    if params[:type].equal?(:account)
+      live_conversations
+    else
+      agent_metrics.sort_by { |hash| hash[:metric][:open] }.reverse
+    end
+  end
+
+  private
+
+  def metric_valid?
+    %w[conversations_count
+       incoming_messages_count
+       outgoing_messages_count
+       avg_first_response_time
+       avg_resolution_time reply_time
+       resolutions_count
+       bot_resolutions_count
+       bot_handoffs_count
+       reply_time].include?(params[:metric])
+  end
+
+  def inbox
+    @inbox ||= account.inboxes.find(params[:id])
+  end
+
+  def user
+    @user ||= account.users.find(params[:id])
+  end
+
+  def label
+    @label ||= account.labels.find(params[:id])
+  end
+
+  def team
+    @team ||= account.teams.find(params[:id])
+  end
+
+  def get_grouped_values(object_scope)
+    @grouped_values = object_scope.group_by_period(
+      params[:group_by] || DEFAULT_GROUP_BY,
+      :created_at,
+      default_value: 0,
+      range: range,
+      permit: %w[day week month year hour],
+      time_zone: @timezone
+    )
+  end
+
+  def agent_metrics
+    account_users = @account.account_users.page(params[:page]).per(AGENT_RESULTS_PER_PAGE)
+    account_users.each_with_object([]) do |account_user, arr|
+      @user = account_user.user
+      arr << {
+        id: @user.id,
+        name: @user.name,
+        email: @user.email,
+        thumbnail: @user.avatar_url,
+        availability: account_user.availability_status,
+        metric: live_conversations
+      }
+    end
+  end
+
+  def live_conversations
+    @open_conversations = scope.conversations.where(account_id: @account.id).open
+    metric = {
+      open: @open_conversations.count,
+      unattended: @open_conversations.unattended.count
+    }
+    metric[:unassigned] = @open_conversations.unassigned.count if params[:type].equal?(:account)
+    metric[:pending] = @open_conversations.pending.count if params[:type].equal?(:account)
+    metric
+  end
+end

research/chatwoot/app/builders/v2/reports/agent_summary_builder.rb

@@ -0,0 +1,39 @@
+class V2::Reports::AgentSummaryBuilder < V2::Reports::BaseSummaryBuilder
+  pattr_initialize [:account!, :params!]
+
+  def build
+    load_data
+    prepare_report
+  end
+
+  private
+
+  attr_reader :conversations_count, :resolved_count,
+              :avg_resolution_time, :avg_first_response_time, :avg_reply_time
+
+  def fetch_conversations_count
+    account.conversations.where(created_at: range).group('assignee_id').count
+  end
+
+  def prepare_report
+    account.account_users.map do |account_user|
+      build_agent_stats(account_user)
+    end
+  end
+
+  def build_agent_stats(account_user)
+    user_id = account_user.user_id
+    {
+      id: user_id,
+      conversations_count: conversations_count[user_id] || 0,
+      resolved_conversations_count: resolved_count[user_id] || 0,
+      avg_resolution_time: avg_resolution_time[user_id],
+      avg_first_response_time: avg_first_response_time[user_id],
+      avg_reply_time: avg_reply_time[user_id]
+    }
+  end
+
+  def group_by_key
+    :user_id
+  end
+end

research/chatwoot/app/builders/v2/reports/base_summary_builder.rb

@@ -0,0 +1,56 @@
+class V2::Reports::BaseSummaryBuilder
+  include DateRangeHelper
+
+  def build
+    load_data
+    prepare_report
+  end
+
+  private
+
+  def load_data
+    @conversations_count = fetch_conversations_count
+    load_reporting_events_data
+  end
+
+  def load_reporting_events_data
+    # Extract the column name for indexing (e.g., 'conversations.team_id' -> 'team_id')
+    index_key = group_by_key.to_s.split('.').last
+
+    results = reporting_events
+              .select(
+                "#{group_by_key} as #{index_key}",
+                "COUNT(CASE WHEN name = 'conversation_resolved' THEN 1 END) as resolved_count",
+                "AVG(CASE WHEN name = 'conversation_resolved' THEN #{average_value_key} END) as avg_resolution_time",
+                "AVG(CASE WHEN name = 'first_response' THEN #{average_value_key} END) as avg_first_response_time",
+                "AVG(CASE WHEN name = 'reply_time' THEN #{average_value_key} END) as avg_reply_time"
+              )
+              .group(group_by_key)
+              .index_by { |record| record.public_send(index_key) }
+
+    @resolved_count = results.transform_values(&:resolved_count)
+    @avg_resolution_time = results.transform_values(&:avg_resolution_time)
+    @avg_first_response_time = results.transform_values(&:avg_first_response_time)
+    @avg_reply_time = results.transform_values(&:avg_reply_time)
+  end
+
+  def reporting_events
+    @reporting_events ||= account.reporting_events.where(created_at: range)
+  end
+
+  def fetch_conversations_count
+    # Override this method
+  end
+
+  def group_by_key
+    # Override this method
+  end
+
+  def prepare_report
+    # Override this method
+  end
+
+  def average_value_key
+    ActiveModel::Type::Boolean.new.cast(params[:business_hours]).present? ? :value_in_business_hours : :value
+  end
+end

research/chatwoot/app/builders/v2/reports/bot_metrics_builder.rb

@@ -0,0 +1,54 @@
+class V2::Reports::BotMetricsBuilder
+  include DateRangeHelper
+  attr_reader :account, :params
+
+  def initialize(account, params)
+    @account = account
+    @params = params
+  end
+
+  def metrics
+    {
+      conversation_count: bot_conversations.count,
+      message_count: bot_messages.count,
+      resolution_rate: bot_resolution_rate.to_i,
+      handoff_rate: bot_handoff_rate.to_i
+    }
+  end
+
+  private
+
+  def bot_activated_inbox_ids
+    @bot_activated_inbox_ids ||= account.inboxes.filter(&:active_bot?).map(&:id)
+  end
+
+  def bot_conversations
+    @bot_conversations ||= account.conversations.where(inbox_id: bot_activated_inbox_ids).where(created_at: range)
+  end
+
+  def bot_messages
+    @bot_messages ||= account.messages.outgoing.where(conversation_id: bot_conversations.ids).where(created_at: range)
+  end
+
+  def bot_resolutions_count
+    account.reporting_events.joins(:conversation).select(:conversation_id).where(account_id: account.id, name: :conversation_bot_resolved,
+                                                                                 created_at: range).distinct.count
+  end
+
+  def bot_handoffs_count
+    account.reporting_events.joins(:conversation).select(:conversation_id).where(account_id: account.id, name: :conversation_bot_handoff,
+                                                                                 created_at: range).distinct.count
+  end
+
+  def bot_resolution_rate
+    return 0 if bot_conversations.count.zero?
+
+    bot_resolutions_count.to_f / bot_conversations.count * 100
+  end
+
+  def bot_handoff_rate
+    return 0 if bot_conversations.count.zero?
+
+    bot_handoffs_count.to_f / bot_conversations.count * 100
+  end
+end

research/chatwoot/app/builders/v2/reports/channel_summary_builder.rb

@@ -0,0 +1,38 @@
+class V2::Reports::ChannelSummaryBuilder
+  include DateRangeHelper
+
+  pattr_initialize [:account!, :params!]
+
+  def build
+    conversations_by_channel_and_status.transform_values { |status_counts| build_channel_stats(status_counts) }
+  end
+
+  private
+
+  def conversations_by_channel_and_status
+    account.conversations
+           .joins(:inbox)
+           .where(created_at: range)
+           .group('inboxes.channel_type', 'conversations.status')
+           .count
+           .each_with_object({}) do |((channel_type, status), count), grouped|
+      grouped[channel_type] ||= {}
+      grouped[channel_type][status] = count
+    end
+  end
+
+  def build_channel_stats(status_counts)
+    open_count = status_counts['open'] || 0
+    resolved_count = status_counts['resolved'] || 0
+    pending_count = status_counts['pending'] || 0
+    snoozed_count = status_counts['snoozed'] || 0
+
+    {
+      open: open_count,
+      resolved: resolved_count,
+      pending: pending_count,
+      snoozed: snoozed_count,
+      total: open_count + resolved_count + pending_count + snoozed_count
+    }
+  end
+end

research/chatwoot/app/builders/v2/reports/conversations/base_report_builder.rb

@@ -0,0 +1,30 @@
+class V2::Reports::Conversations::BaseReportBuilder
+  pattr_initialize :account, :params
+
+  private
+
+  AVG_METRICS = %w[avg_first_response_time avg_resolution_time reply_time].freeze
+  COUNT_METRICS = %w[
+    conversations_count
+    incoming_messages_count
+    outgoing_messages_count
+    resolutions_count
+    bot_resolutions_count
+    bot_handoffs_count
+  ].freeze
+
+  def builder_class(metric)
+    case metric
+    when *AVG_METRICS
+      V2::Reports::Timeseries::AverageReportBuilder
+    when *COUNT_METRICS
+      V2::Reports::Timeseries::CountReportBuilder
+    end
+  end
+
+  def log_invalid_metric
+    Rails.logger.error "ReportBuilder: Invalid metric - #{params[:metric]}"
+
+    {}
+  end
+end

research/chatwoot/app/builders/v2/reports/conversations/metric_builder.rb

@@ -0,0 +1,30 @@
+class V2::Reports::Conversations::MetricBuilder < V2::Reports::Conversations::BaseReportBuilder
+  def summary
+    {
+      conversations_count: count('conversations_count'),
+      incoming_messages_count: count('incoming_messages_count'),
+      outgoing_messages_count: count('outgoing_messages_count'),
+      avg_first_response_time: count('avg_first_response_time'),
+      avg_resolution_time: count('avg_resolution_time'),
+      resolutions_count: count('resolutions_count'),
+      reply_time: count('reply_time')
+    }
+  end
+
+  def bot_summary
+    {
+      bot_resolutions_count: count('bot_resolutions_count'),
+      bot_handoffs_count: count('bot_handoffs_count')
+    }
+  end
+
+  private
+
+  def count(metric)
+    builder_class(metric).new(account, builder_params(metric)).aggregate_value
+  end
+
+  def builder_params(metric)
+    params.merge({ metric: metric })
+  end
+end

research/chatwoot/app/builders/v2/reports/conversations/report_builder.rb

@@ -0,0 +1,21 @@
+class V2::Reports::Conversations::ReportBuilder < V2::Reports::Conversations::BaseReportBuilder
+  def timeseries
+    perform_action(:timeseries)
+  end
+
+  def aggregate_value
+    perform_action(:aggregate_value)
+  end
+
+  private
+
+  def perform_action(method_name)
+    return builder.new(account, params).public_send(method_name) if builder.present?
+
+    log_invalid_metric
+  end
+
+  def builder
+    builder_class(params[:metric])
+  end
+end

research/chatwoot/app/builders/v2/reports/first_response_time_distribution_builder.rb

@@ -0,0 +1,68 @@
+class V2::Reports::FirstResponseTimeDistributionBuilder
+  include DateRangeHelper
+
+  attr_reader :account, :params
+
+  def initialize(account:, params:)
+    @account = account
+    @params = params
+  end
+
+  def build
+    build_distribution
+  end
+
+  private
+
+  def build_distribution
+    results = fetch_aggregated_counts
+    map_to_channel_types(results)
+  end
+
+  def fetch_aggregated_counts
+    ReportingEvent
+      .where(account_id: account.id, name: 'first_response')
+      .where(range_condition)
+      .group(:inbox_id)
+      .select(
+        :inbox_id,
+        bucket_case_statements
+      )
+  end
+
+  def bucket_case_statements
+    <<~SQL.squish
+      COUNT(CASE WHEN value < 3600 THEN 1 END) AS bucket_0_1h,
+      COUNT(CASE WHEN value >= 3600 AND value < 14400 THEN 1 END) AS bucket_1_4h,
+      COUNT(CASE WHEN value >= 14400 AND value < 28800 THEN 1 END) AS bucket_4_8h,
+      COUNT(CASE WHEN value >= 28800 AND value < 86400 THEN 1 END) AS bucket_8_24h,
+      COUNT(CASE WHEN value >= 86400 THEN 1 END) AS bucket_24h_plus
+    SQL
+  end
+
+  def range_condition
+    range.present? ? { created_at: range } : {}
+  end
+
+  def inbox_channel_types
+    @inbox_channel_types ||= account.inboxes.pluck(:id, :channel_type).to_h
+  end
+
+  def map_to_channel_types(results)
+    results.each_with_object({}) do |row, hash|
+      channel_type = inbox_channel_types[row.inbox_id]
+      next unless channel_type
+
+      hash[channel_type] ||= empty_buckets
+      hash[channel_type]['0-1h'] += row.bucket_0_1h
+      hash[channel_type]['1-4h'] += row.bucket_1_4h
+      hash[channel_type]['4-8h'] += row.bucket_4_8h
+      hash[channel_type]['8-24h'] += row.bucket_8_24h
+      hash[channel_type]['24h+'] += row.bucket_24h_plus
+    end
+  end
+
+  def empty_buckets
+    { '0-1h' => 0, '1-4h' => 0, '4-8h' => 0, '8-24h' => 0, '24h+' => 0 }
+  end
+end

research/chatwoot/app/builders/v2/reports/inbox_label_matrix_builder.rb

@@ -0,0 +1,65 @@
+class V2::Reports::InboxLabelMatrixBuilder
+  include DateRangeHelper
+
+  attr_reader :account, :params
+
+  def initialize(account:, params:)
+    @account = account
+    @params = params
+  end
+
+  def build
+    {
+      inboxes: filtered_inboxes.map { |inbox| { id: inbox.id, name: inbox.name } },
+      labels: filtered_labels.map { |label| { id: label.id, title: label.title } },
+      matrix: build_matrix
+    }
+  end
+
+  private
+
+  def filtered_inboxes
+    @filtered_inboxes ||= begin
+      inboxes = account.inboxes
+      inboxes = inboxes.where(id: params[:inbox_ids]) if params[:inbox_ids].present?
+      inboxes.order(:name).to_a
+    end
+  end
+
+  def filtered_labels
+    @filtered_labels ||= begin
+      labels = account.labels
+      labels = labels.where(id: params[:label_ids]) if params[:label_ids].present?
+      labels.order(:title).to_a
+    end
+  end
+
+  def conversation_filter
+    filter = { account_id: account.id }
+    filter[:created_at] = range if range.present?
+    filter[:inbox_id] = params[:inbox_ids] if params[:inbox_ids].present?
+    filter
+  end
+
+  def fetch_grouped_counts
+    label_names = filtered_labels.map(&:title)
+    return {} if label_names.empty?
+
+    ActsAsTaggableOn::Tagging
+      .joins('INNER JOIN conversations ON taggings.taggable_id = conversations.id')
+      .joins('INNER JOIN tags ON taggings.tag_id = tags.id')
+      .where(taggable_type: 'Conversation', context: 'labels', conversations: conversation_filter)
+      .where(tags: { name: label_names })
+      .group('conversations.inbox_id', 'tags.name')
+      .count
+  end
+
+  def build_matrix
+    counts = fetch_grouped_counts
+    filtered_inboxes.map do |inbox|
+      filtered_labels.map do |label|
+        counts[[inbox.id, label.title]] || 0
+      end
+    end
+  end
+end

research/chatwoot/app/builders/v2/reports/inbox_summary_builder.rb

@@ -0,0 +1,47 @@
+class V2::Reports::InboxSummaryBuilder < V2::Reports::BaseSummaryBuilder
+  pattr_initialize [:account!, :params!]
+
+  def build
+    load_data
+    prepare_report
+  end
+
+  private
+
+  attr_reader :conversations_count, :resolved_count,
+              :avg_resolution_time, :avg_first_response_time, :avg_reply_time
+
+  def load_data
+    @conversations_count = fetch_conversations_count
+    load_reporting_events_data
+  end
+
+  def fetch_conversations_count
+    account.conversations.where(created_at: range).group(group_by_key).count
+  end
+
+  def prepare_report
+    account.inboxes.map do |inbox|
+      build_inbox_stats(inbox)
+    end
+  end
+
+  def build_inbox_stats(inbox)
+    {
+      id: inbox.id,
+      conversations_count: conversations_count[inbox.id] || 0,
+      resolved_conversations_count: resolved_count[inbox.id] || 0,
+      avg_resolution_time: avg_resolution_time[inbox.id],
+      avg_first_response_time: avg_first_response_time[inbox.id],
+      avg_reply_time: avg_reply_time[inbox.id]
+    }
+  end
+
+  def group_by_key
+    :inbox_id
+  end
+
+  def average_value_key
+    ActiveModel::Type::Boolean.new.cast(params[:business_hours]) ? :value_in_business_hours : :value
+  end
+end

research/chatwoot/app/builders/v2/reports/label_summary_builder.rb

@@ -0,0 +1,112 @@
+class V2::Reports::LabelSummaryBuilder < V2::Reports::BaseSummaryBuilder
+  attr_reader :account, :params
+
+  # rubocop:disable Lint/MissingSuper
+  # the parent class has no initialize
+  def initialize(account:, params:)
+    @account = account
+    @params = params
+
+    timezone_offset = (params[:timezone_offset] || 0).to_f
+    @timezone = ActiveSupport::TimeZone[timezone_offset]&.name
+  end
+  # rubocop:enable Lint/MissingSuper
+
+  def build
+    labels = account.labels.to_a
+    return [] if labels.empty?
+
+    report_data = collect_report_data
+    labels.map { |label| build_label_report(label, report_data) }
+  end
+
+  private
+
+  def collect_report_data
+    conversation_filter = build_conversation_filter
+    use_business_hours = use_business_hours?
+
+    {
+      conversation_counts: fetch_conversation_counts(conversation_filter),
+      resolved_counts: fetch_resolved_counts,
+      resolution_metrics: fetch_metrics(conversation_filter, 'conversation_resolved', use_business_hours),
+      first_response_metrics: fetch_metrics(conversation_filter, 'first_response', use_business_hours),
+      reply_metrics: fetch_metrics(conversation_filter, 'reply_time', use_business_hours)
+    }
+  end
+
+  def build_label_report(label, report_data)
+    {
+      id: label.id,
+      name: label.title,
+      conversations_count: report_data[:conversation_counts][label.title] || 0,
+      avg_resolution_time: report_data[:resolution_metrics][label.title] || 0,
+      avg_first_response_time: report_data[:first_response_metrics][label.title] || 0,
+      avg_reply_time: report_data[:reply_metrics][label.title] || 0,
+      resolved_conversations_count: report_data[:resolved_counts][label.title] || 0
+    }
+  end
+
+  def use_business_hours?
+    ActiveModel::Type::Boolean.new.cast(params[:business_hours])
+  end
+
+  def build_conversation_filter
+    conversation_filter = { account_id: account.id }
+    conversation_filter[:created_at] = range if range.present?
+
+    conversation_filter
+  end
+
+  def fetch_conversation_counts(conversation_filter)
+    fetch_counts(conversation_filter)
+  end
+
+  def fetch_resolved_counts
+    # Count resolution events, not conversations currently in resolved status
+    # Filter by reporting_event.created_at, not conversation.created_at
+    reporting_event_filter = { name: 'conversation_resolved', account_id: account.id }
+    reporting_event_filter[:created_at] = range if range.present?
+
+    ReportingEvent
+      .joins(conversation: { taggings: :tag })
+      .where(
+        reporting_event_filter.merge(
+          taggings: { taggable_type: 'Conversation', context: 'labels' }
+        )
+      )
+      .group('tags.name')
+      .count
+  end
+
+  def fetch_counts(conversation_filter)
+    ActsAsTaggableOn::Tagging
+      .joins('INNER JOIN conversations ON taggings.taggable_id = conversations.id')
+      .joins('INNER JOIN tags ON taggings.tag_id = tags.id')
+      .where(
+        taggable_type: 'Conversation',
+        context: 'labels',
+        conversations: conversation_filter
+      )
+      .select('tags.name, COUNT(taggings.*) AS count')
+      .group('tags.name')
+      .each_with_object({}) { |record, hash| hash[record.name] = record.count }
+  end
+
+  def fetch_metrics(conversation_filter, event_name, use_business_hours)
+    ReportingEvent
+      .joins(conversation: { taggings: :tag })
+      .where(
+        conversations: conversation_filter,
+        name: event_name,
+        taggings: { taggable_type: 'Conversation', context: 'labels' }
+      )
+      .group('tags.name')
+      .order('tags.name')
+      .select(
+        'tags.name',
+        use_business_hours ? 'AVG(reporting_events.value_in_business_hours) as avg_value' : 'AVG(reporting_events.value) as avg_value'
+      )
+      .each_with_object({}) { |record, hash| hash[record.name] = record.avg_value.to_f }
+  end
+end

research/chatwoot/app/builders/v2/reports/outgoing_messages_count_builder.rb

@@ -0,0 +1,79 @@
+class V2::Reports::OutgoingMessagesCountBuilder
+  include DateRangeHelper
+  attr_reader :account, :params
+
+  def initialize(account, params)
+    @account = account
+    @params = params
+  end
+
+  def build
+    send("build_by_#{params[:group_by]}")
+  end
+
+  private
+
+  def base_messages
+    account.messages.outgoing.unscope(:order).where(created_at: range)
+  end
+
+  def build_by_agent
+    counts = base_messages
+             .where(sender_type: 'User')
+             .where.not(sender_id: nil)
+             .group(:sender_id)
+             .count
+
+    user_names = account.users.where(id: counts.keys).index_by(&:id)
+
+    counts.map do |user_id, count|
+      user = user_names[user_id]
+      { id: user_id, name: user&.name, outgoing_messages_count: count }
+    end
+  end
+
+  def build_by_team
+    counts = base_messages
+             .joins('INNER JOIN conversations ON messages.conversation_id = conversations.id')
+             .where.not(conversations: { team_id: nil })
+             .group('conversations.team_id')
+             .count
+
+    team_names = account.teams.where(id: counts.keys).index_by(&:id)
+
+    counts.map do |team_id, count|
+      team = team_names[team_id]
+      { id: team_id, name: team&.name, outgoing_messages_count: count }
+    end
+  end
+
+  def build_by_inbox
+    counts = base_messages
+             .group(:inbox_id)
+             .count
+
+    inbox_names = account.inboxes.where(id: counts.keys).index_by(&:id)
+
+    counts.map do |inbox_id, count|
+      inbox = inbox_names[inbox_id]
+      { id: inbox_id, name: inbox&.name, outgoing_messages_count: count }
+    end
+  end
+
+  def build_by_label
+    counts = base_messages
+             .joins('INNER JOIN conversations ON messages.conversation_id = conversations.id')
+             .joins("INNER JOIN taggings ON taggings.taggable_id = conversations.id
+                     AND taggings.taggable_type = 'Conversation' AND taggings.context = 'labels'")
+             .joins('INNER JOIN tags ON tags.id = taggings.tag_id')
+             .group('tags.name')
+             .count
+
+    label_ids = account.labels.where(title: counts.keys).index_by(&:title)
+
+    counts.map do |label_name, count|
+      label = label_ids[label_name]
+      { id: label&.id, name: label_name, outgoing_messages_count: count }
+    end
+  end
+end

research/chatwoot/app/builders/v2/reports/team_summary_builder.rb

@@ -0,0 +1,37 @@
+class V2::Reports::TeamSummaryBuilder < V2::Reports::BaseSummaryBuilder
+  pattr_initialize [:account!, :params!]
+
+  private
+
+  attr_reader :conversations_count, :resolved_count,
+              :avg_resolution_time, :avg_first_response_time, :avg_reply_time
+
+  def fetch_conversations_count
+    account.conversations.where(created_at: range).group(:team_id).count
+  end
+
+  def reporting_events
+    @reporting_events ||= account.reporting_events.where(created_at: range).joins(:conversation)
+  end
+
+  def prepare_report
+    account.teams.map do |team|
+      build_team_stats(team)
+    end
+  end
+
+  def build_team_stats(team)
+    {
+      id: team.id,
+      conversations_count: conversations_count[team.id] || 0,
+      resolved_conversations_count: resolved_count[team.id] || 0,
+      avg_resolution_time: avg_resolution_time[team.id],
+      avg_first_response_time: avg_first_response_time[team.id],
+      avg_reply_time: avg_reply_time[team.id]
+    }
+  end
+
+  def group_by_key
+    'conversations.team_id'
+  end
+end

research/chatwoot/app/builders/v2/reports/timeseries/average_report_builder.rb

@@ -0,0 +1,48 @@
+class V2::Reports::Timeseries::AverageReportBuilder < V2::Reports::Timeseries::BaseTimeseriesBuilder
+  def timeseries
+    grouped_average_time = reporting_events.average(average_value_key)
+    grouped_event_count = reporting_events.count
+    grouped_average_time.each_with_object([]) do |element, arr|
+      event_date, average_time = element
+      arr << {
+        value: average_time,
+        timestamp: event_date.in_time_zone(timezone).to_i,
+        count: grouped_event_count[event_date]
+      }
+    end
+  end
+
+  def aggregate_value
+    object_scope.average(average_value_key)
+  end
+
+  private
+
+  def event_name
+    metric_to_event_name = {
+      avg_first_response_time: :first_response,
+      avg_resolution_time: :conversation_resolved,
+      reply_time: :reply_time
+    }
+    metric_to_event_name[params[:metric].to_sym]
+  end
+
+  def object_scope
+    scope.reporting_events.where(name: event_name, created_at: range, account_id: account.id)
+  end
+
+  def reporting_events
+    @grouped_values = object_scope.group_by_period(
+      group_by,
+      :created_at,
+      default_value: 0,
+      range: range,
+      permit: %w[day week month year hour],
+      time_zone: timezone
+    )
+  end
+
+  def average_value_key
+    @average_value_key ||= params[:business_hours].present? ? :value_in_business_hours : :value
+  end
+end

research/chatwoot/app/builders/v2/reports/timeseries/base_timeseries_builder.rb

@@ -0,0 +1,46 @@
+class V2::Reports::Timeseries::BaseTimeseriesBuilder
+  include TimezoneHelper
+  include DateRangeHelper
+  DEFAULT_GROUP_BY = 'day'.freeze
+
+  pattr_initialize :account, :params
+
+  def scope
+    case params[:type].to_sym
+    when :account
+      account
+    when :inbox
+      inbox
+    when :agent
+      user
+    when :label
+      label
+    when :team
+      team
+    end
+  end
+
+  def inbox
+    @inbox ||= account.inboxes.find(params[:id])
+  end
+
+  def user
+    @user ||= account.users.find(params[:id])
+  end
+
+  def label
+    @label ||= account.labels.find(params[:id])
+  end
+
+  def team
+    @team ||= account.teams.find(params[:id])
+  end
+
+  def group_by
+    @group_by ||= %w[day week month year hour].include?(params[:group_by]) ? params[:group_by] : DEFAULT_GROUP_BY
+  end
+
+  def timezone
+    @timezone ||= timezone_name_from_offset(params[:timezone_offset])
+  end
+end

research/chatwoot/app/builders/v2/reports/timeseries/count_report_builder.rb

@@ -0,0 +1,78 @@
+class V2::Reports::Timeseries::CountReportBuilder < V2::Reports::Timeseries::BaseTimeseriesBuilder
+  def timeseries
+    grouped_count.each_with_object([]) do |element, arr|
+      event_date, event_count = element
+
+      # The `event_date` is in Date format (without time), such as "Wed, 15 May 2024".
+      # We need a timestamp for the start of the day. However, we can't use `event_date.to_time.to_i`
+      # because it converts the date to 12:00 AM server timezone.
+      # The desired output should be 12:00 AM in the specified timezone.
+      arr << { value: event_count, timestamp: event_date.in_time_zone(timezone).to_i }
+    end
+  end
+
+  def aggregate_value
+    object_scope.count
+  end
+
+  private
+
+  def metric
+    @metric ||= params[:metric]
+  end
+
+  def object_scope
+    send("scope_for_#{metric}")
+  end
+
+  def scope_for_conversations_count
+    scope.conversations.where(account_id: account.id, created_at: range)
+  end
+
+  def scope_for_incoming_messages_count
+    scope.messages.where(account_id: account.id, created_at: range).incoming.unscope(:order)
+  end
+
+  def scope_for_outgoing_messages_count
+    scope.messages.where(account_id: account.id, created_at: range).outgoing.unscope(:order)
+  end
+
+  def scope_for_resolutions_count
+    scope.reporting_events.where(
+      name: :conversation_resolved,
+      account_id: account.id,
+      created_at: range
+    )
+  end
+
+  def scope_for_bot_resolutions_count
+    scope.reporting_events.where(
+      name: :conversation_bot_resolved,
+      account_id: account.id,
+      created_at: range
+    )
+  end
+
+  def scope_for_bot_handoffs_count
+    scope.reporting_events.joins(:conversation).select(:conversation_id).where(
+      name: :conversation_bot_handoff,
+      account_id: account.id,
+      created_at: range
+    ).distinct
+  end
+
+  def grouped_count
+    # IMPORTANT: time_zone parameter affects both data grouping AND output timestamps
+    # It converts timestamps to the target timezone before grouping, which means
+    # the same event can fall into different day buckets depending on timezone
+    # Example: 2024-01-15 00:00 UTC becomes 2024-01-14 16:00 PST (falls on different day)
+    @grouped_values = object_scope.group_by_period(
+      group_by,
+      :created_at,
+      default_value: 0,
+      range: range,
+      permit: %w[day week month year hour],
+      time_zone: timezone
+    ).count
+  end
+end

research/chatwoot/app/builders/year_in_review_builder.rb

@@ -0,0 +1,74 @@
+class YearInReviewBuilder
+  attr_reader :account, :user_id, :year
+
+  def initialize(account:, user_id:, year:)
+    @account = account
+    @user_id = user_id
+    @year = year
+  end
+
+  def build
+    {
+      year: year,
+      total_conversations: total_conversations_count,
+      busiest_day: busiest_day_data,
+      support_personality: support_personality_data
+    }
+  end
+
+  private
+
+  def year_range
+    @year_range ||= begin
+      start_time = Time.zone.local(year, 1, 1).beginning_of_day
+      end_time = Time.zone.local(year, 12, 31).end_of_day
+      start_time..end_time
+    end
+  end
+
+  def total_conversations_count
+    account.conversations
+           .where(assignee_id: user_id, created_at: year_range)
+           .count
+  end
+
+  def busiest_day_data
+    daily_counts = account.conversations
+                          .where(assignee_id: user_id, created_at: year_range)
+                          .group_by_day(:created_at, range: year_range, time_zone: Time.zone)
+                          .count
+
+    return nil if daily_counts.empty?
+
+    busiest_date, count = daily_counts.max_by { |_date, cnt| cnt }
+
+    return nil if count.zero?
+
+    {
+      date: busiest_date.strftime('%b %d'),
+      count: count
+    }
+  end
+
+  def support_personality_data
+    response_time = average_response_time
+
+    return { avg_response_time_seconds: 0 } if response_time.nil?
+
+    {
+      avg_response_time_seconds: response_time.to_i
+    }
+  end
+
+  def average_response_time
+    avg_time = account.reporting_events
+                      .where(
+                        name: 'first_response',
+                        user_id: user_id,
+                        created_at: year_range
+                      )
+                      .average(:value)
+
+    avg_time&.to_f
+  end
+end