Restructure omni services and add Chatwoot research snapshot

research/chatwoot/app/actions/contact_identify_action.rb

@@ -0,0 +1,139 @@
+# retain_original_contact_name: false / true
+# In case of setUser we want to update the name of the identified contact,
+# which is the default behaviour
+#
+# But, In case of contact merge during prechat form contact update.
+# We don't want to update the name of the identified original contact.
+
+class ContactIdentifyAction
+  include UrlHelper
+  pattr_initialize [:contact!, :params!, { retain_original_contact_name: false, discard_invalid_attrs: false }]
+
+  def perform
+    @attributes_to_update = [:identifier, :name, :email, :phone_number]
+
+    ActiveRecord::Base.transaction do
+      merge_if_existing_identified_contact
+      merge_if_existing_email_contact
+      merge_if_existing_phone_number_contact
+      update_contact
+    end
+    @contact
+  end
+
+  private
+
+  def account
+    @account ||= @contact.account
+  end
+
+  def merge_if_existing_identified_contact
+    return unless merge_contacts?(existing_identified_contact, :identifier)
+
+    process_contact_merge(existing_identified_contact)
+  end
+
+  def merge_if_existing_email_contact
+    return unless merge_contacts?(existing_email_contact, :email)
+
+    process_contact_merge(existing_email_contact)
+  end
+
+  def merge_if_existing_phone_number_contact
+    return unless merge_contacts?(existing_phone_number_contact, :phone_number)
+    return unless mergable_phone_contact?
+
+    process_contact_merge(existing_phone_number_contact)
+  end
+
+  def process_contact_merge(mergee_contact)
+    @contact = merge_contact(mergee_contact, @contact)
+    @attributes_to_update.delete(:name) if retain_original_contact_name
+  end
+
+  def existing_identified_contact
+    return if params[:identifier].blank?
+
+    @existing_identified_contact ||= account.contacts.find_by(identifier: params[:identifier])
+  end
+
+  def existing_email_contact
+    return if params[:email].blank?
+
+    @existing_email_contact ||= account.contacts.from_email(params[:email])
+  end
+
+  def existing_phone_number_contact
+    return if params[:phone_number].blank?
+
+    @existing_phone_number_contact ||= account.contacts.find_by(phone_number: params[:phone_number])
+  end
+
+  def merge_contacts?(existing_contact, key)
+    return if existing_contact.blank?
+
+    return true if params[:identifier].blank?
+
+    # we want to prevent merging contacts with different identifiers
+    if existing_contact.identifier.present? && existing_contact.identifier != params[:identifier]
+      # we will remove attribute from update list
+      @attributes_to_update.delete(key)
+      return false
+    end
+
+    true
+  end
+
+  # case: contact 1: email: 1@test.com, phone: 123456789
+  # params: email: 2@test.com, phone: 123456789
+  # we don't want to overwrite 1@test.com since email parameter takes higer priority
+  def mergable_phone_contact?
+    return true if params[:email].blank?
+
+    if existing_phone_number_contact.email.present? && existing_phone_number_contact.email != params[:email]
+      @attributes_to_update.delete(:phone_number)
+      return false
+    end
+    true
+  end
+
+  def update_contact
+    @contact.attributes = params.slice(*@attributes_to_update).reject do |_k, v|
+      v.blank?
+    end.merge({ custom_attributes: custom_attributes, additional_attributes: additional_attributes })
+    # blank identifier or email will throw unique index error
+    # TODO: replace reject { |_k, v| v.blank? } with compact_blank when rails is upgraded
+    @contact.discard_invalid_attrs if discard_invalid_attrs
+    @contact.save!
+    enqueue_avatar_job
+  end
+
+  def enqueue_avatar_job
+    return unless params[:avatar_url].present? && !@contact.avatar.attached?
+    return unless url_valid?(params[:avatar_url])
+
+    Avatar::AvatarFromUrlJob.perform_later(@contact, params[:avatar_url])
+  end
+
+  def merge_contact(base_contact, merge_contact)
+    return base_contact if base_contact.id == merge_contact.id
+
+    ContactMergeAction.new(
+      account: account,
+      base_contact: base_contact,
+      mergee_contact: merge_contact
+    ).perform
+  end
+
+  def custom_attributes
+    return @contact.custom_attributes if params[:custom_attributes].blank?
+
+    (@contact.custom_attributes || {}).deep_merge(params[:custom_attributes].stringify_keys)
+  end
+
+  def additional_attributes
+    return @contact.additional_attributes if params[:additional_attributes].blank?
+
+    (@contact.additional_attributes || {}).deep_merge(params[:additional_attributes].stringify_keys)
+  end
+end

research/chatwoot/app/actions/contact_merge_action.rb

@@ -0,0 +1,62 @@
+class ContactMergeAction
+  include Events::Types
+  pattr_initialize [:account!, :base_contact!, :mergee_contact!]
+
+  def perform
+    # This case happens when an agent updates a contact email in dashboard,
+    # while the contact also update his email via email collect box
+    return @base_contact if base_contact.id == mergee_contact.id
+
+    ActiveRecord::Base.transaction do
+      validate_contacts
+      merge_conversations
+      merge_messages
+      merge_contact_inboxes
+      merge_contact_notes
+      merge_and_remove_mergee_contact
+    end
+    @base_contact
+  end
+
+  private
+
+  def validate_contacts
+    return if belongs_to_account?(@base_contact) && belongs_to_account?(@mergee_contact)
+
+    raise StandardError, 'contact does not belong to the account'
+  end
+
+  def belongs_to_account?(contact)
+    @account.id == contact.account_id
+  end
+
+  def merge_conversations
+    Conversation.where(contact_id: @mergee_contact.id).update(contact_id: @base_contact.id)
+  end
+
+  def merge_contact_notes
+    Note.where(contact_id: @mergee_contact.id, account_id: @mergee_contact.account_id).update(contact_id: @base_contact.id)
+  end
+
+  def merge_messages
+    Message.where(sender: @mergee_contact).update(sender: @base_contact)
+  end
+
+  def merge_contact_inboxes
+    ContactInbox.where(contact_id: @mergee_contact.id).update(contact_id: @base_contact.id)
+  end
+
+  def merge_and_remove_mergee_contact
+    mergable_attribute_keys = %w[identifier name email phone_number additional_attributes custom_attributes]
+    base_contact_attributes = base_contact.attributes.slice(*mergable_attribute_keys).compact_blank
+    mergee_contact_attributes = mergee_contact.attributes.slice(*mergable_attribute_keys).compact_blank
+
+    # attributes in base contact are given preference
+    merged_attributes = mergee_contact_attributes.deep_merge(base_contact_attributes)
+
+    @mergee_contact.reload.destroy!
+    Rails.configuration.dispatcher.dispatch(CONTACT_MERGED, Time.zone.now, contact: @base_contact,
+                                                                           tokens: [@base_contact.contact_inboxes.filter_map(&:pubsub_token)])
+    @base_contact.update!(merged_attributes)
+  end
+end

research/chatwoot/app/assets/config/manifest.js

@@ -0,0 +1,5 @@
+//= link_tree ../images
+//= link administrate/application.css
+//= link administrate/application.js
+//= link administrate-field-active_storage/application.css
+//= link secretField.js

research/chatwoot/app/assets/javascripts/secretField.js

@@ -0,0 +1,45 @@
+// eslint-disable-next-line
+function toggleSecretField(e) {
+  e.preventDefault();
+  e.stopPropagation();
+
+  const toggler = e.currentTarget;
+  const secretField = toggler.parentElement;
+  const textElement = secretField.querySelector('[data-secret-masked]');
+
+  if (!textElement) return;
+
+  if (textElement.dataset.secretMasked === 'false') {
+    const maskedLength = secretField.dataset.secretText?.length || 10;
+    textElement.textContent = '•'.repeat(maskedLength);
+    textElement.dataset.secretMasked = 'true';
+    toggler.querySelector('svg use').setAttribute('xlink:href', '#eye-show');
+
+    return;
+  }
+
+  textElement.textContent = secretField.dataset.secretText;
+  textElement.dataset.secretMasked = 'false';
+  toggler.querySelector('svg use').setAttribute('xlink:href', '#eye-hide');
+}
+
+// eslint-disable-next-line
+function copySecretField(e) {
+  e.preventDefault();
+  e.stopPropagation();
+
+  const toggler = e.currentTarget;
+  const secretField = toggler.parentElement;
+
+  navigator.clipboard.writeText(secretField.dataset.secretText);
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  document.querySelectorAll('.cell-data__secret-field').forEach(field => {
+    const span = field.querySelector('[data-secret-masked]');
+    if (span && span.dataset.secretMasked === 'true') {
+      const len = field.dataset.secretText?.length || 10;
+      span.textContent = '•'.repeat(len);
+    }
+  });
+});

research/chatwoot/app/assets/stylesheets/administrate/application.scss

@@ -0,0 +1,32 @@
+@charset 'utf-8';
+
+@import 'reset/normalize';
+
+@import 'utilities/variables';
+@import 'utilities/text-color';
+
+@import 'selectize';
+
+@import 'library/clearfix';
+@import 'library/data-label';
+@import 'library/variables';
+
+@import 'base/forms';
+@import 'base/layout';
+@import 'base/lists';
+@import 'base/tables';
+@import 'base/typography';
+
+@import 'components/app-container';
+@import 'components/attributes';
+@import 'components/buttons';
+@import 'components/cells';
+@import 'components/field-unit';
+@import 'components/flashes';
+@import 'components/form-actions';
+@import 'components/main-content';
+@import 'components/pagination';
+@import 'components/search';
+@import 'components/reports';
+
+@import 'custom_styles';

research/chatwoot/app/assets/stylesheets/administrate/base/_forms.scss

@@ -0,0 +1,96 @@
+fieldset {
+  background-color: transparent;
+  border: 0;
+  margin: 0;
+  padding: 0;
+}
+
+legend {
+  font-weight: $font-weight-medium;
+  margin: 0;
+  padding: 0;
+}
+
+label {
+  display: block;
+  font-weight: $font-weight-medium;
+  margin: 0;
+}
+
+input,
+select {
+  display: block;
+  font-family: $base-font-family;
+  font-size: $base-font-size;
+}
+
+[type="color"],
+[type="date"],
+[type="datetime-local"],
+[type="email"],
+[type="month"],
+[type="number"],
+[type="password"],
+[type="search"],
+[type="tel"],
+[type="text"],
+[type="time"],
+[type="url"],
+[type="week"],
+input:not([type]),
+textarea {
+  appearance: none;
+  background-color: $white;
+  border: $base-border;
+  border-radius: $base-border-radius;
+  font-family: $base-font-family;
+  padding: 0.5em;
+  transition: border-color $base-duration $base-timing;
+  width: 100%;
+
+  &:hover {
+    border-color: mix($black, $base-border-color, 20%);
+  }
+
+  &:focus {
+    border-color: $action-color;
+    outline: none;
+  }
+
+  &:disabled {
+    background-color: mix($black, $white, 5%);
+    cursor: not-allowed;
+
+    &:hover {
+      border: $base-border;
+    }
+  }
+}
+
+textarea {
+  resize: vertical;
+}
+
+[type="checkbox"],
+[type="radio"] {
+  display: inline;
+  margin-right: $small-spacing / 2;
+}
+
+[type="file"] {
+  width: 100%;
+}
+
+select {
+  width: 100%;
+}
+
+[type="checkbox"],
+[type="radio"],
+[type="file"],
+select {
+  &:focus {
+    outline: $focus-outline;
+    outline-offset: $focus-outline-offset;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/base/_layout.scss

@@ -0,0 +1,22 @@
+html {
+  background-color: $color-white;
+  box-sizing: border-box;
+  font-size: 16px;
+  -webkit-font-smoothing: antialiased;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}
+
+figure {
+  margin: 0;
+}
+
+img,
+picture {
+  margin: 0;
+  max-width: 100%;
+}

research/chatwoot/app/assets/stylesheets/administrate/base/_lists.scss

@@ -0,0 +1,19 @@
+ul,
+ol {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+}
+
+dl {
+  margin-bottom: $small-spacing;
+
+  dt {
+    font-weight: $font-weight-medium;
+    margin-top: $small-spacing;
+  }
+
+  dd {
+    margin: 0;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/base/_tables.scss

@@ -0,0 +1,71 @@
+table {
+  border-collapse: collapse;
+  font-size: $font-size-default;
+  text-align: left;
+  width: 100%;
+
+  a {
+    color: inherit;
+    text-decoration: none;
+  }
+}
+
+tr {
+  border-bottom: $base-border;
+
+  th {
+    font-weight: $font-weight-medium;
+
+    &.cell-label--avatar-field {
+      a {
+        display: none;
+      }
+    }
+  }
+}
+
+tbody tr {
+  &:hover {
+    background-color: $base-background-color;
+    cursor: pointer;
+  }
+
+  &:focus {
+    outline: $focus-outline;
+    outline-offset: -($focus-outline-width);
+  }
+
+  td {
+    &.cell-data--avatar-field {
+      line-height: 1;
+      text-align: center;
+
+      img {
+        border-radius: 50%;
+        height: $space-large;
+        max-height: $space-large;
+        width: $space-large;
+      }
+    }
+  }
+}
+
+td,
+th {
+  padding: $space-slab;
+  vertical-align: middle;
+}
+
+td:first-child,
+th:first-child {
+  padding-left: 0;
+}
+
+td:last-child,
+th:last-child {
+  padding-right: 0;
+}
+
+td img {
+  max-height: 2rem;
+}

research/chatwoot/app/assets/stylesheets/administrate/base/_typography.scss

@@ -0,0 +1,44 @@
+body {
+  color: $base-font-color;
+  font-family: $base-font-family;
+  font-size: $base-font-size;
+  line-height: $base-line-height;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: $heading-font-family;
+  font-size: $base-font-size;
+  line-height: $heading-line-height;
+  margin: 0;
+}
+
+p {
+  margin: 0 0 $small-spacing;
+}
+
+a {
+  color: $action-color;
+  transition: color $base-duration $base-timing;
+
+  &:hover {
+    color: mix($black, $action-color, 25%);
+  }
+
+  &:focus {
+    outline: $focus-outline;
+    outline-offset: $focus-outline-offset;
+  }
+}
+
+hr {
+  border-bottom: $base-border;
+  border-left: 0;
+  border-right: 0;
+  border-top: 0;
+  margin: $base-spacing 0;
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_app-container.scss

@@ -0,0 +1,8 @@
+.app-container {
+  align-items: stretch;
+  display: flex;
+  margin-left: auto;
+  margin-right: auto;
+  max-width: 100rem;
+  min-height: 100vh;
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_attributes.scss

@@ -0,0 +1,26 @@
+.attribute-label {
+  @include data-label;
+  clear: left;
+  float: left;
+  margin-bottom: $base-spacing;
+  margin-top: 0.25em;
+  text-align: left;
+  width: calc(16% - 1rem);
+}
+
+.preserve-whitespace {
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+.attribute-data {
+  float: left;
+  margin-bottom: $base-spacing;
+  margin-left: 1.25rem;
+  width: calc(84% - 0.625rem);
+}
+
+.attribute--nested {
+  border: $base-border;
+  padding: $small-spacing;
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_buttons.scss

@@ -0,0 +1,50 @@
+button:not(.reset-base),
+input[type='button']:not(.reset-base),
+input[type='reset']:not(.reset-base),
+input[type='submit']:not(.reset-base),
+.button:not(.reset-base) {
+  appearance: none;
+  background-color: $color-woot;
+  border: 0;
+  border-radius: $base-border-radius;
+  color: $white;
+  cursor: pointer;
+  display: inline-flex;
+  font-size: $font-size-small;
+  -webkit-font-smoothing: antialiased;
+  font-weight: $font-weight-medium;
+  line-height: 1;
+  padding: $space-one $space-two;
+  text-decoration: none;
+  transition: background-color $base-duration $base-timing;
+  user-select: none;
+  vertical-align: middle;
+  white-space: nowrap;
+
+  &:hover {
+    background-color: mix($black, $color-woot, 20%);
+    color: $white;
+  }
+
+  &:focus {
+    outline: $focus-outline;
+    outline-offset: $focus-outline-offset;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+
+    &:hover {
+      background-color: $color-woot;
+    }
+  }
+}
+
+.button--alt {
+  background-color: transparent;
+  border: $base-border;
+  border-color: $blue;
+  color: $blue;
+  margin-bottom: $base-spacing;
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_cells.scss

@@ -0,0 +1,70 @@
+.cell-label {
+  &:hover {
+    a {
+      color: $action-color;
+    }
+
+    svg {
+      fill: $action-color;
+      transform: rotate(180deg);
+    }
+  }
+
+  a {
+    color: inherit;
+    display: inline-block;
+    transition: color $base-duration $base-timing;
+    width: 100%;
+  }
+}
+
+.cell-label--asc,
+.cell-label--desc {
+  font-weight: $font-weight-medium;
+}
+
+.cell-label__sort-indicator {
+  float: right;
+  margin-left: 5px;
+
+  svg {
+    fill: $hint-grey;
+    height: 13px;
+    transition: transform $base-duration $base-timing;
+    width: 13px;
+  }
+}
+
+.cell-label__sort-indicator--desc {
+  transform: rotate(180deg);
+}
+
+.cell-data--number,
+.cell-label--number {
+  text-align: right;
+}
+
+.cell-data__secret-field {
+  align-items: center;
+  color: $hint-grey;
+  display: flex;
+
+  span {
+    flex: 0 0 auto;
+  }
+
+  [data-secret-toggler],
+  [data-secret-copier] {
+    background: transparent;
+    border: 0;
+    color: inherit;
+    margin-left: 0.5rem;
+    padding: 0;
+
+    svg {
+      fill: currentColor;
+      height: 1.25rem;
+      width: 1.25rem;
+    }
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_field-unit.scss

@@ -0,0 +1,54 @@
+.field-unit {
+  @include administrate-clearfix;
+  align-items: center;
+  display: flex;
+  margin-bottom: $base-spacing;
+  position: relative;
+  width: 100%;
+}
+
+.field-unit__label {
+  float: left;
+  margin-left: 0.625rem;
+  text-align: right;
+  width: calc(15% - 0.625rem);
+}
+
+.field-unit__field {
+  float: left;
+  margin-left: 1.25rem;
+  max-width: 31.15rem;
+  width: 100%;
+}
+
+.field-unit--nested {
+  border: $base-border;
+  margin-left: 7.5%;
+  max-width: 37.5rem;
+  padding: $small-spacing;
+  width: 100%;
+
+  .field-unit__field {
+    width: 100%;
+  }
+
+  .field-unit__label {
+    width: 10rem;
+  }
+}
+
+.field-unit--required {
+  label::after {
+    color: $red;
+    content: ' *';
+  }
+}
+
+.attribute-data--avatar-field {
+  height: $space-larger;
+  width: $space-larger;
+
+  img {
+    border-radius: 50%;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_flashes.scss

@@ -0,0 +1,28 @@
+$base-spacing: 1.5em !default;
+$flashes: (
+  "alert": #fff6bf,
+  "error": #fbe3e4,
+  "notice": #e5edf8,
+  "success": #e6efc2,
+) !default;
+
+@each $flash-type, $color in $flashes {
+  .flash-#{$flash-type} {
+    background-color: $color;
+    color: mix($black, $color, 60%);
+    display: block;
+    margin-bottom: $base-spacing / 2;
+    padding: $base-spacing / 2;
+    text-align: center;
+
+    a {
+      color: mix($black, $color, 70%);
+      text-decoration: underline;
+
+      &:focus,
+      &:hover {
+        color: mix($black, $color, 90%);
+      }
+    }
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_form-actions.scss

@@ -0,0 +1,3 @@
+.form-actions {
+  margin-left: calc(15% + 1.25rem);
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_main-content.scss

@@ -0,0 +1,35 @@
+.main-content {
+  font-size: $font-size-default;
+  left: 21rem;
+  position: absolute;
+  right: 0;
+  top: 0;
+}
+
+.main-content__body {
+  font-size: $font-size-small;
+  padding: $space-two;
+
+  table {
+    font-size: $font-size-small;
+  }
+
+  form {
+    margin-top: $space-two;
+  }
+}
+
+.main-content__header {
+  align-items: center;
+  background-color: $color-white;
+  border-bottom: 1px solid $color-border;
+  display: flex;
+  min-height: 3.5rem;
+  padding: $space-small $space-normal;
+}
+
+.main-content__page-title {
+  font-size: $font-size-medium;
+  font-weight: $font-weight-medium;
+  margin-right: auto;
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_pagination.scss

@@ -0,0 +1,19 @@
+.pagination {
+  font-size: $font-size-default;
+  margin-top: $base-spacing;
+  padding-left: $base-spacing;
+  padding-right: $base-spacing;
+  text-align: center;
+
+  .first,
+  .prev,
+  .page,
+  .next,
+  .last {
+    margin: $small-spacing;
+  }
+
+  .current {
+    font-weight: $font-weight-medium;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_reports.scss

@@ -0,0 +1,15 @@
+.report--list {
+  display: flex;
+  padding: 0 $space-two $space-larger;
+}
+
+.report-card {
+  flex: 1;
+  font-size: $font-size-small;
+  text-align: center;
+
+  .metric {
+    font-size: $font-size-bigger;
+    font-weight: 200;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/components/_search.scss

@@ -0,0 +1,44 @@
+.search {
+  margin-left: auto;
+  margin-right: 1.25rem;
+  max-width: 27.5rem;
+  position: relative;
+  width: 100%;
+}
+
+.search__input {
+  background: $grey-1;
+  padding-left: $space-normal * 2.5;
+  padding-right: $space-normal * 2.5;
+}
+
+.search__eyeglass-icon {
+  fill: $grey-7;
+  height: $space-normal;
+  left: $space-normal;
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+  width: $space-normal;
+}
+
+.search__clear-link {
+  height: $space-normal;
+  position: absolute;
+  right: $space-normal * 0.75;
+  top: 50%;
+  transform: translateY(-50%);
+  width: $space-normal;
+}
+
+.search__clear-icon {
+  fill: $grey-5;
+  height: $space-normal;
+  position: absolute;
+  transition: fill $base-duration $base-timing;
+  width: $space-normal;
+
+  &:hover {
+    fill: $action-color;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/custom_styles.scss

@@ -0,0 +1,23 @@
+// custom styles for the dashboard
+
+.feature-cell {
+  background: $color-extra-light-blue;
+  border-radius: 10px;
+  float: left;
+  margin-left: 8px;
+  margin-top: 6px;
+  padding: 4px 12px;
+
+  .icon-container {
+    margin-right: 2px;
+  }
+
+  .value-container {
+    margin-left: 6px;
+  }
+}
+
+
+.feature-container {
+  max-width: 100rem;
+}

research/chatwoot/app/assets/stylesheets/administrate/library/_clearfix.scss

@@ -0,0 +1,7 @@
+@mixin administrate-clearfix {
+  &::after {
+    clear: both;
+    content: '';
+    display: block;
+  }
+}

research/chatwoot/app/assets/stylesheets/administrate/library/_data-label.scss

@@ -0,0 +1,8 @@
+@mixin data-label {
+  color: $hint-grey;
+  font-size: 0.8em;
+  font-weight: 400;
+  letter-spacing: 0.0357em;
+  position: relative;
+  text-transform: uppercase;
+}

research/chatwoot/app/assets/stylesheets/administrate/library/_variables.scss

@@ -0,0 +1,61 @@
+// Typography
+$base-font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto",
+  "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
+  sans-serif !default;
+$heading-font-family: $base-font-family !default;
+
+$base-font-size: 16px !default;
+
+$base-line-height: 1.5 !default;
+$heading-line-height: 1.2 !default;
+
+// Other Sizes
+$base-border-radius: 4px !default;
+$base-spacing: $base-line-height * 1em !default;
+$small-spacing: $base-spacing / 2 !default;
+
+// Colors
+$white: #fff !default;
+$black: #000 !default;
+
+$blue: #1f93ff !default;
+$red: #ff382d !default;
+$light-yellow: #ffc532 !default;
+$light-green: #44ce4b !default;
+
+$grey-0: #f6f7f7 !default;
+$grey-1: #f0f4f5 !default;
+$grey-2: #cfd8dc !default;
+$grey-5: #adb5bd !default;
+$grey-7: #293f54 !default;
+
+$hint-grey: #7b808c !default;
+
+// Font Colors
+$base-font-color: $grey-7 !default;
+$action-color: $blue !default;
+
+// Background Colors
+$base-background-color: $grey-0 !default;
+
+// Focus
+$focus-outline-color: transparentize($action-color, 0.4);
+$focus-outline-width: 3px;
+$focus-outline: $focus-outline-width solid $focus-outline-color;
+$focus-outline-offset: 1px;
+
+// Flash Colors
+$flash-colors: (
+  alert: $light-yellow,
+  error: $red,
+  notice: mix($white, $blue, 50%),
+  success: $light-green
+);
+
+// Border
+$base-border-color: $grey-1 !default;
+$base-border: 1px solid $base-border-color !default;
+
+// Transitions
+$base-duration: 250ms !default;
+$base-timing: ease-in-out !default;

research/chatwoot/app/assets/stylesheets/administrate/reset/_normalize.scss

@@ -0,0 +1,448 @@
+/*! normalize.css v7.0.0 | MIT License | github.com/necolas/normalize.css */
+
+/* Document
+   ========================================================================== */
+
+/**
+ * 1. Correct the line height in all browsers.
+ * 2. Prevent adjustments of font size after orientation changes in
+ *    IE on Windows Phone and in iOS.
+ */
+
+html {
+  line-height: 1.15; /* 1 */
+  -ms-text-size-adjust: 100%; /* 2 */
+  -webkit-text-size-adjust: 100%; /* 2 */
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Sections
+   ========================================================================== */
+
+/**
+ * Remove the margin in all browsers (opinionated).
+ */
+
+body {
+  margin: 0;
+}
+
+/**
+ * Add the correct display in IE 9-.
+ */
+
+article,
+aside,
+footer,
+header,
+nav,
+section {
+  display: block;
+}
+
+/**
+ * Correct the font size and margin on `h1` elements within `section` and
+ * `article` contexts in Chrome, Firefox, and Safari.
+ */
+
+h1 {
+  font-size: 2em;
+  margin: 0.67em 0;
+}
+
+/* Grouping content
+   ========================================================================== */
+
+/**
+ * Add the correct display in IE 9-.
+ * 1. Add the correct display in IE.
+ */
+
+figcaption,
+figure,
+main { /* 1 */
+  display: block;
+}
+
+/**
+ * Add the correct margin in IE 8.
+ */
+
+figure {
+  margin: 1em 40px;
+}
+
+/**
+ * 1. Add the correct box sizing in Firefox.
+ * 2. Show the overflow in Edge and IE.
+ */
+
+hr {
+  box-sizing: content-box; /* 1 */
+  height: 0; /* 1 */
+  overflow: visible; /* 2 */
+}
+
+/**
+ * 1. Correct the inheritance and scaling of font size in all browsers.
+ * 2. Correct the odd `em` font sizing in all browsers.
+ */
+
+pre {
+  font-family: monospace, monospace; /* 1 */
+  font-size: 1em; /* 2 */
+}
+
+/* Text-level semantics
+   ========================================================================== */
+
+/**
+ * 1. Remove the gray background on active links in IE 10.
+ * 2. Remove gaps in links underline in iOS 8+ and Safari 8+.
+ */
+
+a {
+  background-color: transparent; /* 1 */
+  -webkit-text-decoration-skip: objects; /* 2 */
+}
+
+/**
+ * 1. Remove the bottom border in Chrome 57- and Firefox 39-.
+ * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.
+ */
+
+abbr[title] {
+  border-bottom: none; /* 1 */
+  text-decoration: underline; /* 2 */
+  text-decoration: underline dotted; /* 2 */
+}
+
+/**
+ * Prevent the duplicate application of `bolder` by the next rule in Safari 6.
+ */
+
+b,
+strong {
+  font-weight: inherit;
+}
+
+/**
+ * Add the correct font weight in Chrome, Edge, and Safari.
+ */
+
+b,
+strong {
+  font-weight: bolder;
+}
+
+/**
+ * 1. Correct the inheritance and scaling of font size in all browsers.
+ * 2. Correct the odd `em` font sizing in all browsers.
+ */
+
+code,
+kbd,
+samp {
+  font-family: monospace, monospace; /* 1 */
+  font-size: 1em; /* 2 */
+}
+
+/**
+ * Add the correct font style in Android 4.3-.
+ */
+
+dfn {
+  font-style: italic;
+}
+
+/**
+ * Add the correct background and color in IE 9-.
+ */
+
+mark {
+  background-color: #ff0;
+  color: #000;
+}
+
+/**
+ * Add the correct font size in all browsers.
+ */
+
+small {
+  font-size: 80%;
+}
+
+/**
+ * Prevent `sub` and `sup` elements from affecting the line height in
+ * all browsers.
+ */
+
+sub,
+sup {
+  font-size: 75%;
+  line-height: 0;
+  position: relative;
+  vertical-align: baseline;
+}
+
+sub {
+  bottom: -0.25em;
+}
+
+sup {
+  top: -0.5em;
+}
+
+/* Embedded content
+   ========================================================================== */
+
+/**
+ * Add the correct display in IE 9-.
+ */
+
+audio,
+video {
+  display: inline-block;
+}
+
+/**
+ * Add the correct display in iOS 4-7.
+ */
+
+audio:not([controls]) {
+  display: none;
+  height: 0;
+}
+
+/**
+ * Remove the border on images inside links in IE 10-.
+ */
+
+img {
+  border-style: none;
+}
+
+/**
+ * Hide the overflow in IE.
+ */
+
+svg:not(:root) {
+  overflow: hidden;
+}
+
+/* Forms
+   ========================================================================== */
+
+/**
+ * 1. Change the font styles in all browsers (opinionated).
+ * 2. Remove the margin in Firefox and Safari.
+ */
+
+button,
+input,
+optgroup,
+select,
+textarea {
+  font-family: sans-serif; /* 1 */
+  font-size: 100%; /* 1 */
+  line-height: 1.15; /* 1 */
+  margin: 0; /* 2 */
+}
+
+/**
+ * Show the overflow in IE.
+ * 1. Show the overflow in Edge.
+ */
+
+button,
+input { /* 1 */
+  overflow: visible;
+}
+
+/**
+ * Remove the inheritance of text transform in Edge, Firefox, and IE.
+ * 1. Remove the inheritance of text transform in Firefox.
+ */
+
+button,
+select { /* 1 */
+  text-transform: none;
+}
+
+/**
+ * 1. Prevent a WebKit bug where (2) destroys native `audio` and `video`
+ *    controls in Android 4.
+ * 2. Correct the inability to style clickable types in iOS and Safari.
+ */
+
+button,
+html [type="button"], /* 1 */
+[type="reset"],
+[type="submit"] {
+  -webkit-appearance: button; /* 2 */
+}
+
+/**
+ * Remove the inner border and padding in Firefox.
+ */
+
+button::-moz-focus-inner,
+[type="button"]::-moz-focus-inner,
+[type="reset"]::-moz-focus-inner,
+[type="submit"]::-moz-focus-inner {
+  border-style: none;
+  padding: 0;
+}
+
+/**
+ * Restore the focus styles unset by the previous rule.
+ */
+
+button:-moz-focusring,
+[type="button"]:-moz-focusring,
+[type="reset"]:-moz-focusring,
+[type="submit"]:-moz-focusring {
+  outline: 1px dotted ButtonText;
+}
+
+/**
+ * Correct the padding in Firefox.
+ */
+
+fieldset {
+  padding: 0.35em 0.75em 0.625em;
+}
+
+/**
+ * 1. Correct the text wrapping in Edge and IE.
+ * 2. Correct the color inheritance from `fieldset` elements in IE.
+ * 3. Remove the padding so developers are not caught out when they zero out
+ *    `fieldset` elements in all browsers.
+ */
+
+legend {
+  box-sizing: border-box; /* 1 */
+  color: inherit; /* 2 */
+  display: table; /* 1 */
+  max-width: 100%; /* 1 */
+  padding: 0; /* 3 */
+  white-space: normal; /* 1 */
+}
+
+/**
+ * 1. Add the correct display in IE 9-.
+ * 2. Add the correct vertical alignment in Chrome, Firefox, and Opera.
+ */
+
+progress {
+  display: inline-block; /* 1 */
+  vertical-align: baseline; /* 2 */
+}
+
+/**
+ * Remove the default vertical scrollbar in IE.
+ */
+
+textarea {
+  overflow: auto;
+}
+
+/**
+ * 1. Add the correct box sizing in IE 10-.
+ * 2. Remove the padding in IE 10-.
+ */
+
+[type="checkbox"],
+[type="radio"] {
+  box-sizing: border-box; /* 1 */
+  padding: 0; /* 2 */
+}
+
+/**
+ * Correct the cursor style of increment and decrement buttons in Chrome.
+ */
+
+[type="number"]::-webkit-inner-spin-button,
+[type="number"]::-webkit-outer-spin-button {
+  height: auto;
+}
+
+/**
+ * 1. Correct the odd appearance in Chrome and Safari.
+ * 2. Correct the outline style in Safari.
+ */
+
+[type="search"] {
+  -webkit-appearance: textfield; /* 1 */
+  outline-offset: -2px; /* 2 */
+}
+
+/**
+ * Remove the inner padding and cancel buttons in Chrome and Safari on macOS.
+ */
+
+[type="search"]::-webkit-search-cancel-button,
+[type="search"]::-webkit-search-decoration {
+  -webkit-appearance: none;
+}
+
+/**
+ * 1. Correct the inability to style clickable types in iOS and Safari.
+ * 2. Change font properties to `inherit` in Safari.
+ */
+
+::-webkit-file-upload-button {
+  -webkit-appearance: button; /* 1 */
+  font: inherit; /* 2 */
+}
+
+/* Interactive
+   ========================================================================== */
+
+/*
+ * Add the correct display in IE 9-.
+ * 1. Add the correct display in Edge, IE, and Firefox.
+ */
+
+details, /* 1 */
+menu {
+  display: block;
+}
+
+/*
+ * Add the correct display in all browsers.
+ */
+
+summary {
+  display: list-item;
+}
+
+/* Scripting
+   ========================================================================== */
+
+/**
+ * Add the correct display in IE 9-.
+ */
+
+canvas {
+  display: inline-block;
+}
+
+/**
+ * Add the correct display in IE.
+ */
+
+template {
+  display: none;
+}
+
+/* Hidden
+   ========================================================================== */
+
+/**
+ * Add the correct display in IE 10-.
+ */
+
+[hidden] {
+  display: none;
+}

research/chatwoot/app/assets/stylesheets/administrate/utilities/_text-color.scss

@@ -0,0 +1,3 @@
+.text-color-red {
+  color: $alert-color;
+}

research/chatwoot/app/assets/stylesheets/administrate/utilities/_variables.scss

@@ -0,0 +1,90 @@
+// Font sizes
+$font-size-nano: 0.5rem;
+$font-size-micro: 0.675rem;
+$font-size-mini: 0.75rem;
+$font-size-small: 0.875rem;
+$font-size-default: 1rem;
+$font-size-medium: 1.125rem;
+$font-size-large: 1.375rem;
+$font-size-big: 1.5rem;
+$font-size-bigger: 1.75rem;
+$font-size-mega: 2.125rem;
+$font-size-giga: 2.5rem;
+
+// spaces
+$zero: 0;
+$space-micro: 0.125rem;
+$space-smaller: 0.25rem;
+$space-small: 0.5rem;
+$space-one: 0.675rem;
+$space-slab: 0.75rem;
+$space-normal: 1rem;
+$space-two: 1.25rem;
+$space-medium: 1.5rem;
+$space-large: 2rem;
+$space-larger: 3rem;
+$space-jumbo: 4rem;
+$space-mega: 6.25rem;
+
+// font-weight
+$font-weight-feather: 100;
+$font-weight-light: 300;
+$font-weight-normal: 400;
+$font-weight-medium: 500;
+$font-weight-bold: 600;
+$font-weight-black: 700;
+
+//Navbar
+$nav-bar-width: 23rem;
+$header-height: 5.6rem;
+
+$woot-logo-padding: $space-large $space-two;
+
+// Colors
+$color-woot: #1f93ff;
+$color-gray: #6e6f73;
+$color-light-gray: #747677;
+$color-border: #e0e6ed;
+$color-border-light: #f0f4f5;
+$color-background: #f4f6fb;
+$color-border-dark: #cad0d4;
+$color-background-light: #f9fafc;
+$color-white: #fff;
+$color-body: #3c4858;
+$color-heading: #1f2d3d;
+$color-extra-light-blue: #f5f7f9;
+
+$primary-color: $color-woot;
+$secondary-color: #5d7592;
+$success-color: #44ce4b;
+$warning-color: #ffc532;
+$alert-color: #ff382d;
+
+$masked-bg: rgba(0, 0, 0, .4);
+
+// Color-palettes
+
+$color-primary-light: #c7e3ff;
+$color-primary-dark: darken($color-woot, 20%);
+
+// Thumbnail
+$thumbnail-radius: 4rem;
+
+// chat-header
+$conv-header-height: 4rem;
+
+// Inbox List
+
+$inbox-thumb-size: 4.8rem;
+
+
+// Snackbar default
+$woot-snackbar-bg: #323232;
+$woot-snackbar-button: #ffeb3b;
+
+$swift-ease-out-duration: .4s !default;
+$swift-ease-out-timing-function: cubic-bezier(.25, .8, .25, 1) !default;
+$swift-ease-out: all $swift-ease-out-duration $swift-ease-out-timing-function !default;
+
+// Transitions
+$transition-ease-in: all 0.250s ease-in;

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

research/chatwoot/app/channels/application_cable/channel.rb

@@ -0,0 +1,2 @@
+class ApplicationCable::Channel < ActionCable::Channel::Base
+end

research/chatwoot/app/channels/application_cable/connection.rb

@@ -0,0 +1,2 @@
+class ApplicationCable::Connection < ActionCable::Connection::Base
+end

research/chatwoot/app/channels/room_channel.rb

@@ -0,0 +1,59 @@
+class RoomChannel < ApplicationCable::Channel
+  def subscribed
+    # TODO: should we only do ensure stream  if current account is present?
+    # for now going ahead with guard clauses in update_subscription and broadcast_presence
+    current_user
+    current_account
+    ensure_stream
+    update_subscription
+    broadcast_presence
+  end
+
+  def update_presence
+    update_subscription
+    broadcast_presence
+  end
+
+  private
+
+  def broadcast_presence
+    return if @current_account.blank?
+
+    data = { account_id: @current_account.id, users: ::OnlineStatusTracker.get_available_users(@current_account.id) }
+    data[:contacts] = ::OnlineStatusTracker.get_available_contacts(@current_account.id) if @current_user.is_a? User
+    ActionCable.server.broadcast(pubsub_token, { event: 'presence.update', data: data })
+  end
+
+  def ensure_stream
+    stream_from pubsub_token
+    stream_from "account_#{@current_account.id}" if @current_account.present? && @current_user.is_a?(User)
+  end
+
+  def update_subscription
+    return if @current_account.blank?
+
+    ::OnlineStatusTracker.update_presence(@current_account.id, @current_user.class.name, @current_user.id)
+  end
+
+  def pubsub_token
+    @pubsub_token ||= params[:pubsub_token]
+  end
+
+  def current_user
+    @current_user ||= if params[:user_id].blank?
+                        ContactInbox.find_by!(pubsub_token: pubsub_token).contact
+                      else
+                        User.find_by!(pubsub_token: pubsub_token, id: params[:user_id])
+                      end
+  end
+
+  def current_account
+    return if current_user.blank?
+
+    @current_account ||= if @current_user.is_a? Contact
+                           @current_user.account
+                         else
+                           @current_user.accounts.find(params[:account_id])
+                         end
+  end
+end

research/chatwoot/app/controllers/android_app_controller.rb

@@ -0,0 +1,5 @@
+class AndroidAppController < ApplicationController
+  def assetlinks
+    render layout: false
+  end
+end

research/chatwoot/app/controllers/api/base_controller.rb

@@ -0,0 +1,23 @@
+class Api::BaseController < ApplicationController
+  include AccessTokenAuthHelper
+  respond_to :json
+  before_action :authenticate_access_token!, if: :authenticate_by_access_token?
+  before_action :validate_bot_access_token!, if: :authenticate_by_access_token?
+  before_action :authenticate_user!, unless: :authenticate_by_access_token?
+
+  private
+
+  def authenticate_by_access_token?
+    request.headers[:api_access_token].present? || request.headers[:HTTP_API_ACCESS_TOKEN].present?
+  end
+
+  def check_authorization(model = nil)
+    model ||= controller_name.classify.constantize
+
+    authorize(model)
+  end
+
+  def check_admin_authorization?
+    raise Pundit::NotAuthorizedError unless Current.account_user.administrator?
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/actions/contact_merges_controller.rb

@@ -0,0 +1,27 @@
+class Api::V1::Accounts::Actions::ContactMergesController < Api::V1::Accounts::BaseController
+  before_action :set_base_contact, only: [:create]
+  before_action :set_mergee_contact, only: [:create]
+
+  def create
+    contact_merge_action = ContactMergeAction.new(
+      account: Current.account,
+      base_contact: @base_contact,
+      mergee_contact: @mergee_contact
+    )
+    contact_merge_action.perform
+  end
+
+  private
+
+  def set_base_contact
+    @base_contact = contacts.find(params[:base_contact_id])
+  end
+
+  def set_mergee_contact
+    @mergee_contact = contacts.find(params[:mergee_contact_id])
+  end
+
+  def contacts
+    @contacts ||= Current.account.contacts
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/agent_bots_controller.rb

@@ -0,0 +1,51 @@
+class Api::V1::Accounts::AgentBotsController < Api::V1::Accounts::BaseController
+  before_action :current_account
+  before_action :check_authorization
+  before_action :agent_bot, except: [:index, :create]
+
+  def index
+    @agent_bots = AgentBot.accessible_to(Current.account)
+  end
+
+  def show; end
+
+  def create
+    @agent_bot = Current.account.agent_bots.create!(permitted_params.except(:avatar_url))
+    process_avatar_from_url
+  end
+
+  def update
+    @agent_bot.update!(permitted_params.except(:avatar_url))
+    process_avatar_from_url
+  end
+
+  def avatar
+    @agent_bot.avatar.purge if @agent_bot.avatar.attached?
+    @agent_bot
+  end
+
+  def destroy
+    @agent_bot.destroy!
+    head :ok
+  end
+
+  def reset_access_token
+    @agent_bot.access_token.regenerate_token
+    @agent_bot.reload
+  end
+
+  private
+
+  def agent_bot
+    @agent_bot = AgentBot.accessible_to(Current.account).find(params[:id]) if params[:action] == 'show'
+    @agent_bot ||= Current.account.agent_bots.find(params[:id])
+  end
+
+  def permitted_params
+    params.permit(:name, :description, :outgoing_url, :avatar, :avatar_url, :bot_type, bot_config: {})
+  end
+
+  def process_avatar_from_url
+    ::Avatar::AvatarFromUrlJob.perform_later(@agent_bot, params[:avatar_url]) if params[:avatar_url].present?
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/agents_controller.rb

@@ -0,0 +1,113 @@
+class Api::V1::Accounts::AgentsController < Api::V1::Accounts::BaseController
+  before_action :fetch_agent, except: [:create, :index, :bulk_create]
+  before_action :check_authorization
+  before_action :validate_limit, only: [:create]
+  before_action :validate_limit_for_bulk_create, only: [:bulk_create]
+
+  def index
+    @agents = agents
+  end
+
+  def create
+    builder = AgentBuilder.new(
+      email: new_agent_params['email'],
+      name: new_agent_params['name'],
+      role: new_agent_params['role'],
+      availability: new_agent_params['availability'],
+      auto_offline: new_agent_params['auto_offline'],
+      inviter: current_user,
+      account: Current.account
+    )
+
+    @agent = builder.perform
+  end
+
+  def update
+    @agent.update!(agent_params.slice(:name).compact)
+    @agent.current_account_user.update!(agent_params.slice(*account_user_attributes).compact)
+  end
+
+  def destroy
+    @agent.current_account_user.destroy!
+    delete_user_record(@agent)
+    head :ok
+  end
+
+  def bulk_create
+    emails = params[:emails]
+
+    emails.each do |email|
+      builder = AgentBuilder.new(
+        email: email,
+        name: email.split('@').first,
+        inviter: current_user,
+        account: Current.account
+      )
+      begin
+        builder.perform
+      rescue ActiveRecord::RecordInvalid => e
+        Rails.logger.info "[Agent#bulk_create] ignoring email #{email}, errors: #{e.record.errors}"
+      end
+    end
+
+    # This endpoint is used to bulk create agents during onboarding
+    # onboarding_step key in present in Current account custom attributes, since this is a one time operation
+    Current.account.custom_attributes.delete('onboarding_step')
+    Current.account.save!
+    head :ok
+  end
+
+  private
+
+  def check_authorization
+    super(User)
+  end
+
+  def fetch_agent
+    @agent = agents.find(params[:id])
+  end
+
+  def account_user_attributes
+    [:role, :availability, :auto_offline]
+  end
+
+  def allowed_agent_params
+    [:name, :email, :role, :availability, :auto_offline]
+  end
+
+  def agent_params
+    params.require(:agent).permit(allowed_agent_params)
+  end
+
+  def new_agent_params
+    params.require(:agent).permit(:email, :name, :role, :availability, :auto_offline)
+  end
+
+  def agents
+    @agents ||= Current.account.users.order_by_full_name.includes(:account_users, { avatar_attachment: [:blob] })
+  end
+
+  def validate_limit_for_bulk_create
+    limit_available = params[:emails].count <= available_agent_count
+
+    render_payment_required('Account limit exceeded. Please purchase more licenses') unless limit_available
+  end
+
+  def validate_limit
+    render_payment_required('Account limit exceeded. Please purchase more licenses') unless can_add_agent?
+  end
+
+  def available_agent_count
+    Current.account.usage_limits[:agents] - agents.count
+  end
+
+  def can_add_agent?
+    available_agent_count.positive?
+  end
+
+  def delete_user_record(agent)
+    DeleteObjectJob.perform_later(agent) if agent.reload.account_users.blank?
+  end
+end
+
+Api::V1::Accounts::AgentsController.prepend_mod_with('Api::V1::Accounts::AgentsController')

research/chatwoot/app/controllers/api/v1/accounts/articles_controller.rb

@@ -0,0 +1,86 @@
+class Api::V1::Accounts::ArticlesController < Api::V1::Accounts::BaseController
+  before_action :portal
+  before_action :check_authorization
+  before_action :fetch_article, except: [:index, :create, :reorder]
+  before_action :set_current_page, only: [:index]
+
+  def index
+    @portal_articles = @portal.articles
+
+    set_article_count
+
+    @articles = @articles.search(list_params)
+
+    @articles = if list_params[:category_slug].present?
+                  @articles.order_by_position.page(@current_page)
+                else
+                  @articles.order_by_updated_at.page(@current_page)
+                end
+  end
+
+  def show; end
+  def edit; end
+
+  def create
+    params_with_defaults = article_params
+    params_with_defaults[:status] ||= :draft
+    @article = @portal.articles.create!(params_with_defaults)
+    @article.associate_root_article(article_params[:associated_article_id])
+    render json: { error: @article.errors.messages }, status: :unprocessable_entity and return unless @article.valid?
+  end
+
+  def update
+    @article.update!(article_params) if params[:article].present?
+    render json: { error: @article.errors.messages }, status: :unprocessable_entity and return unless @article.valid?
+  end
+
+  def destroy
+    @article.destroy!
+    head :ok
+  end
+
+  def reorder
+    Article.update_positions(params[:positions_hash])
+    head :ok
+  end
+
+  private
+
+  def set_article_count
+    # Search the params without status and author_id, use this to
+    # compute mine count published draft etc
+    base_search_params = list_params.except(:status, :author_id)
+    @articles = @portal_articles.search(base_search_params)
+
+    @articles_count = @articles.count
+    @mine_articles_count = @articles.search_by_author(Current.user.id).count
+    @published_articles_count = @articles.published.count
+    @draft_articles_count = @articles.draft.count
+    @archived_articles_count = @articles.archived.count
+  end
+
+  def fetch_article
+    @article = @portal.articles.find(params[:id])
+  end
+
+  def portal
+    @portal ||= Current.account.portals.find_by!(slug: params[:portal_id])
+  end
+
+  def article_params
+    params.require(:article).permit(
+      :title, :slug, :position, :content, :description, :category_id, :author_id, :associated_article_id, :status,
+      :locale, meta: [:title,
+                      :description,
+                      { tags: [] }]
+    )
+  end
+
+  def list_params
+    params.permit(:locale, :query, :page, :category_slug, :status, :author_id)
+  end
+
+  def set_current_page
+    @current_page = params[:page] || 1
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/assignable_agents_controller.rb

@@ -0,0 +1,24 @@
+class Api::V1::Accounts::AssignableAgentsController < Api::V1::Accounts::BaseController
+  before_action :fetch_inboxes
+
+  def index
+    agent_ids = @inboxes.map do |inbox|
+      authorize inbox, :show?
+      member_ids = inbox.members.pluck(:user_id)
+      member_ids
+    end
+    agent_ids = agent_ids.inject(:&)
+    agents = Current.account.users.where(id: agent_ids)
+    @assignable_agents = (agents + Current.account.administrators).uniq
+  end
+
+  private
+
+  def fetch_inboxes
+    @inboxes = Current.account.inboxes.find(permitted_params[:inbox_ids])
+  end
+
+  def permitted_params
+    params.permit(inbox_ids: [])
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/assignment_policies/inboxes_controller.rb

@@ -0,0 +1,20 @@
+class Api::V1::Accounts::AssignmentPolicies::InboxesController < Api::V1::Accounts::BaseController
+  before_action :fetch_assignment_policy
+  before_action -> { check_authorization(AssignmentPolicy) }
+
+  def index
+    @inboxes = @assignment_policy.inboxes
+  end
+
+  private
+
+  def fetch_assignment_policy
+    @assignment_policy = Current.account.assignment_policies.find(
+      params[:assignment_policy_id]
+    )
+  end
+
+  def permitted_params
+    params.permit(:assignment_policy_id)
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/assignment_policies_controller.rb

@@ -0,0 +1,36 @@
+class Api::V1::Accounts::AssignmentPoliciesController < Api::V1::Accounts::BaseController
+  before_action :fetch_assignment_policy, only: [:show, :update, :destroy]
+  before_action :check_authorization
+
+  def index
+    @assignment_policies = Current.account.assignment_policies
+  end
+
+  def show; end
+
+  def create
+    @assignment_policy = Current.account.assignment_policies.create!(assignment_policy_params)
+  end
+
+  def update
+    @assignment_policy.update!(assignment_policy_params)
+  end
+
+  def destroy
+    @assignment_policy.destroy!
+    head :ok
+  end
+
+  private
+
+  def fetch_assignment_policy
+    @assignment_policy = Current.account.assignment_policies.find(params[:id])
+  end
+
+  def assignment_policy_params
+    params.require(:assignment_policy).permit(
+      :name, :description, :assignment_order, :conversation_priority,
+      :fair_distribution_limit, :fair_distribution_window, :enabled
+    )
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/automation_rules_controller.rb

@@ -0,0 +1,68 @@
+class Api::V1::Accounts::AutomationRulesController < Api::V1::Accounts::BaseController
+  include AttachmentConcern
+
+  before_action :check_authorization
+  before_action :fetch_automation_rule, only: [:show, :update, :destroy, :clone]
+
+  def index
+    @automation_rules = Current.account.automation_rules
+  end
+
+  def show; end
+
+  def create
+    blobs, actions, error = validate_and_prepare_attachments(params[:actions])
+    return render_could_not_create_error(error) if error
+
+    @automation_rule = Current.account.automation_rules.new(automation_rules_permit)
+    @automation_rule.actions = actions
+    @automation_rule.conditions = params[:conditions]
+
+    return render_could_not_create_error(@automation_rule.errors.messages) unless @automation_rule.valid?
+
+    @automation_rule.save!
+    blobs.each { |blob| @automation_rule.files.attach(blob) }
+  end
+
+  def update
+    blobs, actions, error = validate_and_prepare_attachments(params[:actions], @automation_rule)
+    return render_could_not_create_error(error) if error
+
+    ActiveRecord::Base.transaction do
+      @automation_rule.assign_attributes(automation_rules_permit)
+      @automation_rule.actions = actions if params[:actions]
+      @automation_rule.conditions = params[:conditions] if params[:conditions]
+      @automation_rule.save!
+      blobs.each { |blob| @automation_rule.files.attach(blob) }
+    rescue StandardError => e
+      Rails.logger.error e
+      render_could_not_create_error(@automation_rule.errors.messages)
+    end
+  end
+
+  def destroy
+    @automation_rule.destroy!
+    head :ok
+  end
+
+  def clone
+    automation_rule = Current.account.automation_rules.find_by(id: params[:automation_rule_id])
+    new_rule = automation_rule.dup
+    new_rule.save!
+    @automation_rule = new_rule
+  end
+
+  private
+
+  def automation_rules_permit
+    params.permit(
+      :name, :description, :event_name, :active,
+      conditions: [:attribute_key, :filter_operator, :query_operator, :custom_attribute_type, { values: [] }],
+      actions: [:action_name, { action_params: [] }]
+    )
+  end
+
+  def fetch_automation_rule
+    @automation_rule = Current.account.automation_rules.find_by(id: params[:id])
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/base_controller.rb

@@ -0,0 +1,6 @@
+class Api::V1::Accounts::BaseController < Api::BaseController
+  include SwitchLocale
+  include EnsureCurrentAccountHelper
+  before_action :current_account
+  around_action :switch_locale_using_account_locale
+end

research/chatwoot/app/controllers/api/v1/accounts/bulk_actions_controller.rb

@@ -0,0 +1,68 @@
+class Api::V1::Accounts::BulkActionsController < Api::V1::Accounts::BaseController
+  def create
+    case normalized_type
+    when 'Conversation'
+      enqueue_conversation_job
+      head :ok
+    when 'Contact'
+      check_authorization_for_contact_action
+      enqueue_contact_job
+      head :ok
+    else
+      render json: { success: false }, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def normalized_type
+    params[:type].to_s.camelize
+  end
+
+  def enqueue_conversation_job
+    ::BulkActionsJob.perform_later(
+      account: @current_account,
+      user: current_user,
+      params: conversation_params
+    )
+  end
+
+  def enqueue_contact_job
+    Contacts::BulkActionJob.perform_later(
+      @current_account.id,
+      current_user.id,
+      contact_params
+    )
+  end
+
+  def delete_contact_action?
+    params[:action_name] == 'delete'
+  end
+
+  def check_authorization_for_contact_action
+    authorize(Contact, :destroy?) if delete_contact_action?
+  end
+
+  def conversation_params
+    # TODO: Align conversation payloads with the `{ action_name, action_attributes }`
+    # and then remove this method in favor of a common params method.
+    base = params.permit(
+      :snoozed_until,
+      fields: [:status, :assignee_id, :team_id]
+    )
+    append_common_bulk_attributes(base)
+  end
+
+  def contact_params
+    # TODO: remove this method in favor of a common params method.
+    # once legacy conversation payloads are migrated.
+    append_common_bulk_attributes({})
+  end
+
+  def append_common_bulk_attributes(base_params)
+    # NOTE: Conversation payloads historically diverged per action. Going forward we
+    # want all objects to share a common contract: `{ action_name, action_attributes }`
+    common = params.permit(:type, :action_name, ids: [], labels: [add: [], remove: []])
+    base_params.merge(common)
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/callbacks_controller.rb

@@ -0,0 +1,116 @@
+class Api::V1::Accounts::CallbacksController < Api::V1::Accounts::BaseController
+  before_action :inbox, only: [:reauthorize_page]
+
+  def register_facebook_page
+    user_access_token = params[:user_access_token]
+    page_access_token = params[:page_access_token]
+    page_id = params[:page_id]
+    inbox_name = params[:inbox_name]
+    ActiveRecord::Base.transaction do
+      facebook_channel = Current.account.facebook_pages.create!(
+        page_id: page_id, user_access_token: user_access_token,
+        page_access_token: page_access_token
+      )
+      @facebook_inbox = Current.account.inboxes.create!(name: inbox_name, channel: facebook_channel)
+      set_instagram_id(page_access_token, facebook_channel)
+      set_avatar(@facebook_inbox, page_id)
+    end
+  rescue StandardError => e
+    ChatwootExceptionTracker.new(e).capture_exception
+    Rails.logger.error "Error in register_facebook_page: #{e.message}"
+    # Additional log statements
+    log_additional_info
+  end
+
+  def log_additional_info
+    Rails.logger.debug do
+      "user_access_token: #{params[:user_access_token]} , page_access_token: #{params[:page_access_token]} ,
+      page_id: #{params[:page_id]}, inbox_name: #{params[:inbox_name]}"
+    end
+  end
+
+  def facebook_pages
+    pages = []
+    fb_pages = fb_object.get_connections('me', 'accounts')
+    pages.concat(fb_pages)
+    while fb_pages.respond_to?(:next_page) && (next_page = fb_pages.next_page)
+      fb_pages = next_page
+      pages.concat(fb_pages)
+    end
+    @page_details = mark_already_existing_facebook_pages(pages)
+  end
+
+  def set_instagram_id(page_access_token, facebook_channel)
+    fb_object = Koala::Facebook::API.new(page_access_token)
+    response = fb_object.get_connections('me', '', { fields: 'instagram_business_account' })
+    return if response['instagram_business_account'].blank?
+
+    instagram_id = response['instagram_business_account']['id']
+    facebook_channel.update(instagram_id: instagram_id)
+  rescue StandardError => e
+    Rails.logger.error "Error in set_instagram_id: #{e.message}"
+  end
+
+  # get params[:inbox_id], current_account. params[:omniauth_token]
+  def reauthorize_page
+    if @inbox&.facebook?
+      fb_page_id = @inbox.channel.page_id
+      page_details = fb_object.get_connections('me', 'accounts')
+
+      if (page_detail = (page_details || []).detect { |page| fb_page_id == page['id'] })
+        update_fb_page(fb_page_id, page_detail['access_token'])
+        render and return
+      end
+    end
+
+    head :unprocessable_entity
+  end
+
+  private
+
+  def inbox
+    @inbox = Current.account.inboxes.find_by(id: params[:inbox_id])
+  end
+
+  def update_fb_page(fb_page_id, access_token)
+    fb_page = get_fb_page(fb_page_id)
+    ActiveRecord::Base.transaction do
+      fb_page&.update!(user_access_token: @user_access_token, page_access_token: access_token)
+      set_instagram_id(access_token, fb_page)
+      fb_page&.reauthorized!
+    rescue StandardError => e
+      ChatwootExceptionTracker.new(e).capture_exception
+      Rails.logger.error "Error in update_fb_page: #{e.message}"
+    end
+  end
+
+  def get_fb_page(fb_page_id)
+    Current.account.facebook_pages.find_by(page_id: fb_page_id)
+  end
+
+  def fb_object
+    @user_access_token = long_lived_token(params[:omniauth_token])
+    Koala::Facebook::API.new(@user_access_token)
+  end
+
+  def long_lived_token(omniauth_token)
+    koala = Koala::Facebook::OAuth.new(GlobalConfigService.load('FB_APP_ID', ''), GlobalConfigService.load('FB_APP_SECRET', ''))
+    koala.exchange_access_token_info(omniauth_token)['access_token']
+  rescue StandardError => e
+    Rails.logger.error "Error in long_lived_token: #{e.message}"
+  end
+
+  def mark_already_existing_facebook_pages(data)
+    return [] if data.empty?
+
+    data.inject([]) do |result, page_detail|
+      page_detail[:exists] = Current.account.facebook_pages.exists?(page_id: page_detail['id'])
+      result << page_detail
+    end
+  end
+
+  def set_avatar(facebook_inbox, page_id)
+    avatar_url = "https://graph.facebook.com/#{page_id}/picture?type=large"
+    Avatar::AvatarFromUrlJob.perform_later(facebook_inbox, avatar_url)
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/campaigns_controller.rb

@@ -0,0 +1,34 @@
+class Api::V1::Accounts::CampaignsController < Api::V1::Accounts::BaseController
+  before_action :campaign, except: [:index, :create]
+  before_action :check_authorization
+
+  def index
+    @campaigns = Current.account.campaigns
+  end
+
+  def show; end
+
+  def create
+    @campaign = Current.account.campaigns.create!(campaign_params)
+  end
+
+  def update
+    @campaign.update!(campaign_params)
+  end
+
+  def destroy
+    @campaign.destroy!
+    head :ok
+  end
+
+  private
+
+  def campaign
+    @campaign ||= Current.account.campaigns.find_by(display_id: params[:id])
+  end
+
+  def campaign_params
+    params.require(:campaign).permit(:title, :description, :message, :enabled, :trigger_only_during_business_hours, :inbox_id, :sender_id,
+                                     :scheduled_at, audience: [:type, :id], trigger_rules: {}, template_params: {})
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/canned_responses_controller.rb

@@ -0,0 +1,44 @@
+class Api::V1::Accounts::CannedResponsesController < Api::V1::Accounts::BaseController
+  before_action :fetch_canned_response, only: [:update, :destroy]
+
+  def index
+    render json: canned_responses
+  end
+
+  def create
+    @canned_response = Current.account.canned_responses.new(canned_response_params)
+    @canned_response.save!
+    render json: @canned_response
+  end
+
+  def update
+    @canned_response.update!(canned_response_params)
+    render json: @canned_response
+  end
+
+  def destroy
+    @canned_response.destroy!
+    head :ok
+  end
+
+  private
+
+  def fetch_canned_response
+    @canned_response = Current.account.canned_responses.find(params[:id])
+  end
+
+  def canned_response_params
+    params.require(:canned_response).permit(:short_code, :content)
+  end
+
+  def canned_responses
+    if params[:search]
+      Current.account.canned_responses
+             .where('short_code ILIKE :search OR content ILIKE :search', search: "%#{params[:search]}%")
+             .order_by_search(params[:search])
+
+    else
+      Current.account.canned_responses
+    end
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/captain/preferences_controller.rb

@@ -0,0 +1,76 @@
+class Api::V1::Accounts::Captain::PreferencesController < Api::V1::Accounts::BaseController
+  before_action :current_account
+  before_action :authorize_account_update, only: [:update]
+
+  def show
+    render json: preferences_payload
+  end
+
+  def update
+    params_to_update = captain_params
+    @current_account.captain_models = params_to_update[:captain_models] if params_to_update[:captain_models]
+    @current_account.captain_features = params_to_update[:captain_features] if params_to_update[:captain_features]
+    @current_account.save!
+
+    render json: preferences_payload
+  end
+
+  private
+
+  def preferences_payload
+    {
+      providers: Llm::Models.providers,
+      models: Llm::Models.models,
+      features: features_with_account_preferences
+    }
+  end
+
+  def authorize_account_update
+    authorize @current_account, :update?
+  end
+
+  def captain_params
+    permitted = {}
+    permitted[:captain_models] = merged_captain_models if params[:captain_models].present?
+    permitted[:captain_features] = merged_captain_features if params[:captain_features].present?
+    permitted
+  end
+
+  def merged_captain_models
+    existing_models = @current_account.captain_models || {}
+    existing_models.merge(permitted_captain_models)
+  end
+
+  def merged_captain_features
+    existing_features = @current_account.captain_features || {}
+    existing_features.merge(permitted_captain_features)
+  end
+
+  def permitted_captain_models
+    params.require(:captain_models).permit(
+      :editor, :assistant, :copilot, :label_suggestion,
+      :audio_transcription, :help_center_search
+    ).to_h.stringify_keys
+  end
+
+  def permitted_captain_features
+    params.require(:captain_features).permit(
+      :editor, :assistant, :copilot, :label_suggestion,
+      :audio_transcription, :help_center_search
+    ).to_h.stringify_keys
+  end
+
+  def features_with_account_preferences
+    preferences = Current.account.captain_preferences
+    account_features = preferences[:features] || {}
+    account_models = preferences[:models] || {}
+
+    Llm::Models.feature_keys.index_with do |feature_key|
+      config = Llm::Models.feature_config(feature_key)
+      config.merge(
+        enabled: account_features[feature_key] == true,
+        selected: account_models[feature_key] || config[:default]
+      )
+    end
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/categories_controller.rb

@@ -0,0 +1,58 @@
+class Api::V1::Accounts::CategoriesController < Api::V1::Accounts::BaseController
+  before_action :portal
+  before_action :check_authorization
+  before_action :fetch_category, except: [:index, :create]
+  before_action :set_current_page, only: [:index]
+
+  def index
+    @current_locale = params[:locale]
+    @categories = @portal.categories.search(params)
+  end
+
+  def show; end
+
+  def create
+    @category = @portal.categories.create!(category_params)
+    @category.related_categories << related_categories_records
+    render json: { error: @category.errors.messages }, status: :unprocessable_entity and return unless @category.valid?
+
+    @category.save!
+  end
+
+  def update
+    @category.update!(category_params)
+    @category.related_categories = related_categories_records if related_categories_records.any?
+    render json: { error: @category.errors.messages }, status: :unprocessable_entity and return unless @category.valid?
+
+    @category.save!
+  end
+
+  def destroy
+    @category.destroy!
+    head :ok
+  end
+
+  private
+
+  def fetch_category
+    @category = @portal.categories.find(params[:id])
+  end
+
+  def portal
+    @portal ||= Current.account.portals.find_by(slug: params[:portal_id])
+  end
+
+  def related_categories_records
+    @portal.categories.where(id: params[:category][:related_category_ids])
+  end
+
+  def category_params
+    params.require(:category).permit(
+      :name, :description, :position, :slug, :locale, :icon, :parent_category_id, :associated_category_id
+    )
+  end
+
+  def set_current_page
+    @current_page = params[:page] || 1
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb

@@ -0,0 +1,70 @@
+# TODO : Move this to inboxes controller and deprecate this controller
+# No need to retain this controller as we could handle everything centrally in inboxes controller
+
+class Api::V1::Accounts::Channels::TwilioChannelsController < Api::V1::Accounts::BaseController
+  before_action :authorize_request
+
+  def create
+    process_create
+  rescue StandardError => e
+    render_could_not_create_error(e.message)
+  end
+
+  private
+
+  def authorize_request
+    authorize ::Inbox
+  end
+
+  def process_create
+    ActiveRecord::Base.transaction do
+      authenticate_twilio
+      build_inbox
+      setup_webhooks if @twilio_channel.sms?
+    end
+  end
+
+  def authenticate_twilio
+    client = if permitted_params[:api_key_sid].present?
+               Twilio::REST::Client.new(permitted_params[:api_key_sid], permitted_params[:auth_token], permitted_params[:account_sid])
+             else
+               Twilio::REST::Client.new(permitted_params[:account_sid], permitted_params[:auth_token])
+             end
+    client.messages.list(limit: 1)
+  end
+
+  def setup_webhooks
+    ::Twilio::WebhookSetupService.new(inbox: @inbox).perform
+  end
+
+  def phone_number
+    return if permitted_params[:phone_number].blank?
+
+    medium == 'sms' ? permitted_params[:phone_number] : "whatsapp:#{permitted_params[:phone_number]}"
+  end
+
+  def medium
+    permitted_params[:medium]
+  end
+
+  def build_inbox
+    @twilio_channel = Current.account.twilio_sms.create!(
+      account_sid: permitted_params[:account_sid],
+      auth_token: permitted_params[:auth_token],
+      api_key_sid: permitted_params[:api_key_sid],
+      messaging_service_sid: permitted_params[:messaging_service_sid].presence,
+      phone_number: phone_number,
+      medium: medium
+    )
+    @inbox = Current.account.inboxes.create!(
+      name: permitted_params[:name],
+      channel: @twilio_channel
+    )
+  end
+
+  def permitted_params
+    params.require(:twilio_channel).permit(
+      :messaging_service_sid, :phone_number, :account_sid, :auth_token, :name, :medium, :api_key_sid
+    )
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contact_inboxes_controller.rb

@@ -0,0 +1,21 @@
+class Api::V1::Accounts::ContactInboxesController < Api::V1::Accounts::BaseController
+  before_action :ensure_inbox
+
+  def filter
+    contact_inbox = @inbox.contact_inboxes.where(inbox_id: permitted_params[:inbox_id], source_id: permitted_params[:source_id])
+    return head :not_found if contact_inbox.empty?
+
+    @contact = contact_inbox.first.contact
+  end
+
+  private
+
+  def ensure_inbox
+    @inbox = Current.account.inboxes.find(permitted_params[:inbox_id])
+    authorize @inbox, :show?
+  end
+
+  def permitted_params
+    params.permit(:inbox_id, :source_id)
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contacts/base_controller.rb

@@ -0,0 +1,9 @@
+class Api::V1::Accounts::Contacts::BaseController < Api::V1::Accounts::BaseController
+  before_action :ensure_contact
+
+  private
+
+  def ensure_contact
+    @contact = Current.account.contacts.find(params[:contact_id])
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contacts/contact_inboxes_controller.rb

@@ -0,0 +1,20 @@
+class Api::V1::Accounts::Contacts::ContactInboxesController < Api::V1::Accounts::Contacts::BaseController
+  include HmacConcern
+  before_action :ensure_inbox, only: [:create]
+
+  def create
+    @contact_inbox = ContactInboxBuilder.new(
+      contact: @contact,
+      inbox: @inbox,
+      source_id: params[:source_id],
+      hmac_verified: hmac_verified?
+    ).perform
+  end
+
+  private
+
+  def ensure_inbox
+    @inbox = Current.account.inboxes.find(params[:inbox_id])
+    authorize @inbox, :show?
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contacts/conversations_controller.rb

@@ -0,0 +1,17 @@
+class Api::V1::Accounts::Contacts::ConversationsController < Api::V1::Accounts::Contacts::BaseController
+  def index
+    # Start with all conversations for this contact
+    conversations = Current.account.conversations.includes(
+      :assignee, :contact, :inbox, :taggings
+    ).where(contact_id: @contact.id)
+
+    # Apply permission-based filtering using the existing service
+    conversations = Conversations::PermissionFilterService.new(
+      conversations,
+      Current.user,
+      Current.account
+    ).perform
+
+    @conversations = conversations.order(last_activity_at: :desc).limit(20)
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contacts/labels_controller.rb

@@ -0,0 +1,13 @@
+class Api::V1::Accounts::Contacts::LabelsController < Api::V1::Accounts::Contacts::BaseController
+  include LabelConcern
+
+  private
+
+  def model
+    @model ||= @contact
+  end
+
+  def permitted_params
+    params.permit(labels: [])
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contacts/notes_controller.rb

@@ -0,0 +1,32 @@
+class Api::V1::Accounts::Contacts::NotesController < Api::V1::Accounts::Contacts::BaseController
+  before_action :note, except: [:index, :create]
+
+  def index
+    @notes = @contact.notes.latest.includes(:user)
+  end
+
+  def show; end
+
+  def create
+    @note = @contact.notes.create!(note_params)
+  end
+
+  def update
+    @note.update(note_params)
+  end
+
+  def destroy
+    @note.destroy!
+    head :ok
+  end
+
+  private
+
+  def note
+    @note ||= @contact.notes.find(params[:id])
+  end
+
+  def note_params
+    params.require(:note).permit(:content).merge({ contact_id: @contact.id, user_id: Current.user.id })
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/contacts_controller.rb

@@ -0,0 +1,214 @@
+class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
+  include Sift
+  sort_on :email, type: :string
+  sort_on :name, internal_name: :order_on_name, type: :scope, scope_params: [:direction]
+  sort_on :phone_number, type: :string
+  sort_on :last_activity_at, internal_name: :order_on_last_activity_at, type: :scope, scope_params: [:direction]
+  sort_on :created_at, internal_name: :order_on_created_at, type: :scope, scope_params: [:direction]
+  sort_on :company, internal_name: :order_on_company_name, type: :scope, scope_params: [:direction]
+  sort_on :city, internal_name: :order_on_city, type: :scope, scope_params: [:direction]
+  sort_on :country, internal_name: :order_on_country_name, type: :scope, scope_params: [:direction]
+
+  RESULTS_PER_PAGE = 15
+
+  before_action :check_authorization
+  before_action :set_current_page, only: [:index, :active, :search, :filter]
+  before_action :fetch_contact, only: [:show, :update, :destroy, :avatar, :contactable_inboxes, :destroy_custom_attributes]
+  before_action :set_include_contact_inboxes, only: [:index, :active, :search, :filter, :show, :update]
+
+  def index
+    @contacts = fetch_contacts(resolved_contacts)
+    @contacts_count = @contacts.total_count
+  end
+
+  def search
+    render json: { error: 'Specify search string with parameter q' }, status: :unprocessable_entity if params[:q].blank? && return
+
+    contacts = Current.account.contacts.where(
+      'name ILIKE :search OR email ILIKE :search OR phone_number ILIKE :search OR contacts.identifier LIKE :search',
+      search: "%#{params[:q].strip}%"
+    )
+    @contacts = fetch_contacts_with_has_more(contacts)
+  end
+
+  def import
+    render json: { error: I18n.t('errors.contacts.import.failed') }, status: :unprocessable_entity and return if params[:import_file].blank?
+
+    ActiveRecord::Base.transaction do
+      import = Current.account.data_imports.create!(data_type: 'contacts')
+      import.import_file.attach(params[:import_file])
+    end
+
+    head :ok
+  end
+
+  def export
+    column_names = params['column_names']
+    filter_params = { :payload => params.permit!['payload'], :label => params.permit!['label'] }
+    Account::ContactsExportJob.perform_later(Current.account.id, Current.user.id, column_names, filter_params)
+    head :ok, message: I18n.t('errors.contacts.export.success')
+  end
+
+  # returns online contacts
+  def active
+    contacts = Current.account.contacts.where(id: ::OnlineStatusTracker
+                  .get_available_contact_ids(Current.account.id))
+    @contacts = fetch_contacts(contacts)
+    @contacts_count = @contacts.total_count
+  end
+
+  def show; end
+
+  def filter
+    result = ::Contacts::FilterService.new(Current.account, Current.user, params.permit!).perform
+    contacts = result[:contacts]
+    @contacts_count = result[:count]
+    @contacts = fetch_contacts(contacts)
+  rescue CustomExceptions::CustomFilter::InvalidAttribute,
+         CustomExceptions::CustomFilter::InvalidOperator,
+         CustomExceptions::CustomFilter::InvalidQueryOperator,
+         CustomExceptions::CustomFilter::InvalidValue => e
+    render_could_not_create_error(e.message)
+  end
+
+  def contactable_inboxes
+    @all_contactable_inboxes = Contacts::ContactableInboxesService.new(contact: @contact).get
+    @contactable_inboxes = @all_contactable_inboxes.select { |contactable_inbox| policy(contactable_inbox[:inbox]).show? }
+  end
+
+  # TODO : refactor this method into dedicated contacts/custom_attributes controller class and routes
+  def destroy_custom_attributes
+    @contact.custom_attributes = @contact.custom_attributes.excluding(params[:custom_attributes])
+    @contact.save!
+  end
+
+  def create
+    ActiveRecord::Base.transaction do
+      @contact = Current.account.contacts.new(permitted_params.except(:avatar_url))
+      @contact.save!
+      @contact_inbox = build_contact_inbox
+      process_avatar_from_url
+    end
+  end
+
+  def update
+    @contact.assign_attributes(contact_update_params)
+    @contact.save!
+    process_avatar_from_url
+  end
+
+  def destroy
+    if ::OnlineStatusTracker.get_presence(
+      @contact.account.id, 'Contact', @contact.id
+    )
+      return render_error({ message: I18n.t('contacts.online.delete', contact_name: @contact.name.capitalize) },
+                          :unprocessable_entity)
+    end
+
+    @contact.destroy!
+    head :ok
+  end
+
+  def avatar
+    @contact.avatar.purge if @contact.avatar.attached?
+    @contact
+  end
+
+  private
+
+  # TODO: Move this to a finder class
+  def resolved_contacts
+    return @resolved_contacts if @resolved_contacts
+
+    @resolved_contacts = Current.account.contacts.resolved_contacts(use_crm_v2: Current.account.feature_enabled?('crm_v2'))
+
+    @resolved_contacts = @resolved_contacts.tagged_with(params[:labels], any: true) if params[:labels].present?
+    @resolved_contacts
+  end
+
+  def set_current_page
+    @current_page = params[:page] || 1
+  end
+
+  def fetch_contacts(contacts)
+    # Build includes hash to avoid separate query when contact_inboxes are needed
+    includes_hash = { avatar_attachment: [:blob] }
+    includes_hash[:contact_inboxes] = { inbox: :channel } if @include_contact_inboxes
+
+    filtrate(contacts)
+      .includes(includes_hash)
+      .page(@current_page)
+      .per(RESULTS_PER_PAGE)
+  end
+
+  def fetch_contacts_with_has_more(contacts)
+    includes_hash = { avatar_attachment: [:blob] }
+    includes_hash[:contact_inboxes] = { inbox: :channel } if @include_contact_inboxes
+
+    # Calculate offset manually to fetch one extra record for has_more check
+    offset = (@current_page.to_i - 1) * RESULTS_PER_PAGE
+    results = filtrate(contacts)
+              .includes(includes_hash)
+              .offset(offset)
+              .limit(RESULTS_PER_PAGE + 1)
+              .to_a
+
+    @has_more = results.size > RESULTS_PER_PAGE
+    results = results.first(RESULTS_PER_PAGE) if @has_more
+    @contacts_count = results.size
+    results
+  end
+
+  def build_contact_inbox
+    return if params[:inbox_id].blank?
+
+    inbox = Current.account.inboxes.find(params[:inbox_id])
+    ContactInboxBuilder.new(
+      contact: @contact,
+      inbox: inbox,
+      source_id: params[:source_id]
+    ).perform
+  end
+
+  def permitted_params
+    params.permit(:name, :identifier, :email, :phone_number, :avatar, :blocked, :avatar_url, additional_attributes: {}, custom_attributes: {})
+  end
+
+  def contact_custom_attributes
+    return @contact.custom_attributes.merge(permitted_params[:custom_attributes]) if permitted_params[:custom_attributes]
+
+    @contact.custom_attributes
+  end
+
+  def contact_additional_attributes
+    return @contact.additional_attributes.merge(permitted_params[:additional_attributes]) if permitted_params[:additional_attributes]
+
+    @contact.additional_attributes
+  end
+
+  def contact_update_params
+    permitted_params.except(:custom_attributes, :avatar_url)
+                    .merge({ custom_attributes: contact_custom_attributes })
+                    .merge({ additional_attributes: contact_additional_attributes })
+  end
+
+  def set_include_contact_inboxes
+    @include_contact_inboxes = if params[:include_contact_inboxes].present?
+                                 params[:include_contact_inboxes] == 'true'
+                               else
+                                 true
+                               end
+  end
+
+  def fetch_contact
+    @contact = Current.account.contacts.includes(contact_inboxes: [:inbox]).find(params[:id])
+  end
+
+  def process_avatar_from_url
+    ::Avatar::AvatarFromUrlJob.perform_later(@contact, params[:avatar_url]) if params[:avatar_url].present?
+  end
+
+  def render_error(error, error_status)
+    render json: error, status: error_status
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/assignments_controller.rb

@@ -0,0 +1,45 @@
+class Api::V1::Accounts::Conversations::AssignmentsController < Api::V1::Accounts::Conversations::BaseController
+  # assigns agent/team to a conversation
+  def create
+    if params.key?(:assignee_id) || agent_bot_assignment?
+      set_agent
+    elsif params.key?(:team_id)
+      set_team
+    else
+      render json: nil
+    end
+  end
+
+  private
+
+  def set_agent
+    resource = Conversations::AssignmentService.new(
+      conversation: @conversation,
+      assignee_id: params[:assignee_id],
+      assignee_type: params[:assignee_type]
+    ).perform
+
+    render_agent(resource)
+  end
+
+  def render_agent(resource)
+    case resource
+    when User
+      render partial: 'api/v1/models/agent', formats: [:json], locals: { resource: resource }
+    when AgentBot
+      render partial: 'api/v1/models/agent_bot_slim', formats: [:json], locals: { resource: resource }
+    else
+      render json: nil
+    end
+  end
+
+  def set_team
+    @team = Current.account.teams.find_by(id: params[:team_id])
+    @conversation.update!(team: @team)
+    render json: @team
+  end
+
+  def agent_bot_assignment?
+    params[:assignee_type].to_s == 'AgentBot'
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/base_controller.rb

@@ -0,0 +1,10 @@
+class Api::V1::Accounts::Conversations::BaseController < Api::V1::Accounts::BaseController
+  before_action :conversation
+
+  private
+
+  def conversation
+    @conversation ||= Current.account.conversations.find_by!(display_id: params[:conversation_id])
+    authorize @conversation, :show?
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/direct_uploads_controller.rb

@@ -0,0 +1,17 @@
+class Api::V1::Accounts::Conversations::DirectUploadsController < ActiveStorage::DirectUploadsController
+  include EnsureCurrentAccountHelper
+  before_action :current_account
+  before_action :conversation
+
+  def create
+    return if @conversation.nil? || @current_account.nil?
+
+    super
+  end
+
+  private
+
+  def conversation
+    @conversation ||= Current.account.conversations.find_by(display_id: params[:conversation_id])
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/draft_messages_controller.rb

@@ -0,0 +1,28 @@
+class Api::V1::Accounts::Conversations::DraftMessagesController < Api::V1::Accounts::Conversations::BaseController
+  def show
+    render json: { has_draft: false } and return unless Redis::Alfred.exists?(draft_redis_key)
+
+    draft_message = Redis::Alfred.get(draft_redis_key)
+    render json: { has_draft: true, message: draft_message }
+  end
+
+  def update
+    Redis::Alfred.set(draft_redis_key, draft_message_params)
+    head :ok
+  end
+
+  def destroy
+    Redis::Alfred.delete(draft_redis_key)
+    head :ok
+  end
+
+  private
+
+  def draft_redis_key
+    format(Redis::Alfred::CONVERSATION_DRAFT_MESSAGE, id: @conversation.id)
+  end
+
+  def draft_message_params
+    params.dig(:draft_message, :message) || ''
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/labels_controller.rb

@@ -0,0 +1,13 @@
+class Api::V1::Accounts::Conversations::LabelsController < Api::V1::Accounts::Conversations::BaseController
+  include LabelConcern
+
+  private
+
+  def model
+    @model ||= @conversation
+  end
+
+  def permitted_params
+    params.permit(:conversation_id, labels: [])
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/messages_controller.rb

@@ -0,0 +1,80 @@
+class Api::V1::Accounts::Conversations::MessagesController < Api::V1::Accounts::Conversations::BaseController
+  before_action :ensure_api_inbox, only: :update
+
+  def index
+    @messages = message_finder.perform
+  end
+
+  def create
+    user = Current.user || @resource
+    mb = Messages::MessageBuilder.new(user, @conversation, params)
+    @message = mb.perform
+  rescue StandardError => e
+    render_could_not_create_error(e.message)
+  end
+
+  def update
+    Messages::StatusUpdateService.new(message, permitted_params[:status], permitted_params[:external_error]).perform
+    @message = message
+  end
+
+  def destroy
+    ActiveRecord::Base.transaction do
+      message.update!(content: I18n.t('conversations.messages.deleted'), content_type: :text, content_attributes: { deleted: true })
+      message.attachments.destroy_all
+    end
+  end
+
+  def retry
+    return if message.blank?
+
+    service = Messages::StatusUpdateService.new(message, 'sent')
+    service.perform
+    message.update!(content_attributes: {})
+    ::SendReplyJob.perform_later(message.id)
+  rescue StandardError => e
+    render_could_not_create_error(e.message)
+  end
+
+  def translate
+    return head :ok if already_translated_content_available?
+
+    translated_content = Integrations::GoogleTranslate::ProcessorService.new(
+      message: message,
+      target_language: permitted_params[:target_language]
+    ).perform
+
+    if translated_content.present?
+      translations = {}
+      translations[permitted_params[:target_language]] = translated_content
+      translations = message.translations.merge!(translations) if message.translations.present?
+      message.update!(translations: translations)
+    end
+
+    render json: { content: translated_content }
+  end
+
+  private
+
+  def message
+    @message ||= @conversation.messages.find(permitted_params[:id])
+  end
+
+  def message_finder
+    @message_finder ||= MessageFinder.new(@conversation, params)
+  end
+
+  def permitted_params
+    params.permit(:id, :target_language, :status, :external_error)
+  end
+
+  def already_translated_content_available?
+    message.translations.present? && message.translations[permitted_params[:target_language]].present?
+  end
+
+  # API inbox check
+  def ensure_api_inbox
+    # Only API inboxes can update messages
+    render json: { error: 'Message status update is only allowed for API inboxes' }, status: :forbidden unless @conversation.inbox.api?
+  end
+end

research/chatwoot/app/controllers/api/v1/accounts/conversations/participants_controller.rb

@@ -0,0 +1,41 @@
+class Api::V1::Accounts::Conversations::ParticipantsController < Api::V1::Accounts::Conversations::BaseController
+  def show
+    @participants = @conversation.conversation_participants
+  end
+
+  def create
+    ActiveRecord::Base.transaction do
+      @participants = participants_to_be_added_ids.map { |user_id| @conversation.conversation_participants.find_or_create_by(user_id: user_id) }
+    end
+  end
+
+  def update
+    ActiveRecord::Base.transaction do
+      participants_to_be_added_ids.each { |user_id| @conversation.conversation_participants.find_or_create_by(user_id: user_id) }
+      participants_to_be_removed_ids.each { |user_id| @conversation.conversation_participants.find_by(user_id: user_id)&.destroy }
+    end
+    @participants = @conversation.conversation_participants
+    render action: 'show'
+  end
+
+  def destroy
+    ActiveRecord::Base.transaction do
+      params[:user_ids].map { |user_id| @conversation.conversation_participants.find_by(user_id: user_id)&.destroy }
+    end
+    head :ok
+  end
+
+  private
+
+  def participants_to_be_added_ids
+    params[:user_ids] - current_participant_ids
+  end
+
+  def participants_to_be_removed_ids
+    current_participant_ids - params[:user_ids]
+  end
+
+  def current_participant_ids
+    @current_participant_ids ||= @conversation.conversation_participants.pluck(:user_id)
+  end
+end