feat: update status on agent bot assignment

Google OAuth signups now persist the same first-party attribution
cookies as email signups on Chatwoot Cloud.

This keeps attribution capture owned by the website and reuses the
existing Enterprise-only account attribution service. The OAuth callback
only records the already-shaped first-touch and last-touch cookie
payload after a new account is created.

## What changed

- Added Enterprise-only attribution persistence to the Google OAuth
signup account creation path.
- Reuses `Internal::Accounts::MarketingAttributionService`.
- Keeps attribution best-effort so failures do not interrupt OAuth
signup.
- Leaves existing email signup and SAML behavior unchanged.

## How to test

- Start from a Chatwoot Cloud-like setup with attribution cookies
present.
- Sign up using the Google OAuth button.
- Confirm the created account has
`internal_attributes['marketing_attribution']` with `first_touch` and
`last_touch`.
- Confirm existing Google OAuth login still redirects normally.

Validation run locally:

- `bundle exec rspec
spec/enterprise/controllers/enterprise/devise_overrides/google_oauth_attribution_spec.rb`
- `bundle exec rspec
spec/controllers/devise/omniauth_callbacks_controller_spec.rb
spec/enterprise/controllers/enterprise/devise_overrides/google_oauth_attribution_spec.rb`
- `bundle exec rubocop
enterprise/app/controllers/enterprise/devise_overrides/omniauth_callbacks_controller.rb
spec/enterprise/controllers/enterprise/devise_overrides/google_oauth_attribution_spec.rb`

.annotaterb.yml

@@ -0,0 +1,65 @@
+---
+:position: before
+:position_in_additional_file_patterns: before
+:position_in_class: before
+:position_in_factory: before
+:position_in_fixture: before
+:position_in_routes: before
+:position_in_serializer: before
+:position_in_test: before
+:classified_sort: true
+:exclude_controllers: true
+:exclude_factories: true
+:exclude_fixtures: true
+:exclude_helpers: true
+:exclude_scaffolds: true
+:exclude_serializers: true
+:exclude_sti_subclasses: false
+:exclude_tests: true
+:force: false
+:format_markdown: false
+:format_rdoc: false
+:format_yard: false
+:frozen: false
+:grouped_polymorphic: false
+:ignore_model_sub_dir: false
+:ignore_unknown_models: false
+:include_version: false
+:show_check_constraints: false
+:show_complete_foreign_keys: false
+:show_foreign_keys: true
+:show_indexes: true
+:show_indexes_include: false
+:simple_indexes: false
+:sort: false
+:timestamp: false
+:trace: false
+:with_comment: true
+:with_column_comments: true
+:with_table_comments: true
+:position_of_column_comment: :with_name
+:active_admin: false
+:command:
+:debug: false
+:hide_default_column_types: json,jsonb,hstore
+:hide_limit_column_types: integer,bigint,boolean
+:timestamp_columns:
+- created_at
+- updated_at
+:ignore_columns:
+:ignore_routes:
+:models: true
+:routes: false
+:skip_on_db_migrate: false
+:target_action: :do_annotations
+:wrapper:
+:wrapper_close:
+:wrapper_open:
+:classes_default_to_s: []
+:additional_file_patterns: []
+:model_dir:
+- app/models
+- enterprise/app/models
+:require: []
+:root_dir:
+- ''

.bundler-audit.yml

@@ -1,3 +1,23 @@
 ---
 ignore:
   - CVE-2021-41098 # https://github.com/chatwoot/chatwoot/issues/3097 (update once azure blob storage is updated)
+  - GHSA-57hq-95w6-v4fc # Devise confirmable race condition — patched locally in User model (remove once on Devise 5+)
+  # Devise 5 is currently blocked by devise-secure_password/devise_token_auth/devise-two-factor.
+  # Chatwoot does not enable Timeoutable, so the timeout redirect path is not reachable.
+  - GHSA-jp94-3292-c3xv
+  # Rails 7.1 has no patched release for the Active Storage proxy range
+  # advisories. Chatwoot limits proxy range requests locally.
+  - CVE-2026-33658
+  # Rails 7.1 has no patched release for this Active Storage direct-upload
+  # advisory. Chatwoot filters internal metadata keys locally.
+  - CVE-2026-33173
+  - CVE-2026-33174
+  # Rails 7.1 has no patched release for these Rails advisories. These are not
+  # reachable through Chatwoot's current usage patterns and should be removed
+  # once we upgrade to Rails 7.2.3.1+.
+  - CVE-2026-33168
+  - CVE-2026-33169
+  - CVE-2026-33170
+  - CVE-2026-33176
+  - CVE-2026-33195
+  - CVE-2026-33202

.circleci/config.yml

@@ -1,7 +1,9 @@
 version: 2.1
 orbs:
   node: circleci/node@6.1.0
+  qlty-orb: qltysh/qlty-orb@0.0
 
+# Shared defaults for setup steps
 defaults: &defaults
   working_directory: ~/build
   machine:
@@ -11,21 +13,147 @@ defaults: &defaults
     RAILS_LOG_TO_STDOUT: false
     COVERAGE: true
     LOG_LEVEL: warn
-  parallelism: 4
 
 jobs:
-  build:
+  # Separate job for linting (no parallelism needed)
+  lint:
     <<: *defaults
     steps:
       - checkout
+
+      # Install minimal system dependencies for linting
+      - run:
+          name: Install System Dependencies
+          command: |
+            sudo apt-get update
+            DEBIAN_FRONTEND=noninteractive sudo apt-get install -y \
+              libpq-dev \
+              build-essential \
+              git \
+              curl \
+              libssl-dev \
+              zlib1g-dev \
+              libreadline-dev \
+              libyaml-dev \
+              openjdk-11-jdk \
+              jq \
+              software-properties-common \
+              ca-certificates \
+              imagemagick \
+              libxml2-dev \
+              libxslt1-dev \
+              file \
+              g++ \
+              gcc \
+              autoconf \
+              gnupg2 \
+              patch \
+              ruby-dev \
+              liblzma-dev \
+              libgmp-dev \
+              libncurses5-dev \
+              libffi-dev \
+              libgdbm6 \
+              libgdbm-dev \
+              libvips
+
+      - run:
+          name: Install RVM and Ruby 3.4.4
+          command: |
+            sudo apt-get install -y gpg
+            gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+            \curl -sSL https://get.rvm.io | bash -s stable
+            echo 'source ~/.rvm/scripts/rvm' >> $BASH_ENV
+            source ~/.rvm/scripts/rvm
+            rvm install "3.4.4"
+            rvm use 3.4.4 --default
+            gem install bundler -v 2.5.16
+
+      - run:
+          name: Install Application Dependencies
+          command: |
+            source ~/.rvm/scripts/rvm
+            bundle install
+
       - node/install:
-          node-version: '23.7'
+          node-version: '24.13'
       - node/install-pnpm
       - node/install-packages:
           pkg-manager: pnpm
           override-ci-command: pnpm i
-      - run: node --version
-      - run: pnpm --version
+
+      # Swagger verification
+      - run:
+          name: Verify swagger API specification
+          command: |
+            bundle exec rake swagger:build
+            if [[ `git status swagger/swagger.json --porcelain` ]]
+            then
+              echo "ERROR: The swagger.json file is not in sync with the yaml specification. Run 'rake swagger:build' and commit 'swagger/swagger.json'."
+              exit 1
+            fi
+            mkdir -p ~/tmp
+            curl -L https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.19.0/openapi-generator-cli-7.19.0.jar > ~/tmp/openapi-generator-cli-7.19.0.jar
+            java -jar ~/tmp/openapi-generator-cli-7.19.0.jar validate -i swagger/swagger.json
+
+      # Bundle audit
+      - run:
+          name: Bundle audit
+          command: bundle exec bundle audit update && bundle exec bundle audit check -v
+
+      # Rubocop linting
+      - run:
+          name: Rubocop
+          command: bundle exec rubocop --parallel
+
+      # ESLint linting
+      - run:
+          name: eslint
+          command: pnpm run eslint
+
+  # Separate job for frontend tests
+  frontend-tests:
+    <<: *defaults
+    steps:
+      - checkout
+      - node/install:
+          node-version: '24.13'
+      - node/install-pnpm
+      - node/install-packages:
+          pkg-manager: pnpm
+          override-ci-command: pnpm i
+
+      - run:
+          name: Run frontend tests (with coverage)
+          command: pnpm run test:coverage
+
+      - run:
+          name: Move coverage files if they exist
+          command: |
+            if [ -d "coverage" ]; then
+              mkdir -p ~/build/coverage
+              cp -r coverage ~/build/coverage/frontend || true
+            fi
+          when: always
+
+      - persist_to_workspace:
+          root: ~/build
+          paths:
+            - coverage
+
+  # Backend tests with parallelization
+  backend-tests:
+    <<: *defaults
+    parallelism: 20
+    steps:
+      - checkout
+      - node/install:
+          node-version: '24.13'
+      - node/install-pnpm
+      - node/install-packages:
+          pkg-manager: pnpm
+          override-ci-command: pnpm i
+
       - run:
           name: Add PostgreSQL repository and update
           command: |
@@ -89,29 +217,51 @@ jobs:
           command: |
             source ~/.rvm/scripts/rvm
             bundle install
-            # pnpm install
+
+      # Install and configure OpenSearch
+      - run:
+          name: Install OpenSearch
+          command: |
+            # Download and install OpenSearch 2.11.0 (compatible with Elasticsearch 7.x clients)
+            wget https://artifacts.opensearch.org/releases/bundle/opensearch/2.11.0/opensearch-2.11.0-linux-x64.tar.gz
+            tar -xzf opensearch-2.11.0-linux-x64.tar.gz
+            sudo mv opensearch-2.11.0 /opt/opensearch
 
       - run:
-          name: Download cc-test-reporter
+          name: Configure and Start OpenSearch
           command: |
-            mkdir -p ~/tmp
-            curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ~/tmp/cc-test-reporter
-            chmod +x ~/tmp/cc-test-reporter
+            # Configure OpenSearch for single-node testing
+            cat > /opt/opensearch/config/opensearch.yml \<< EOF
+            cluster.name: chatwoot-test
+            node.name: node-1
+            network.host: 0.0.0.0
+            http.port: 9200
+            discovery.type: single-node
+            plugins.security.disabled: true
+            EOF
+
+            # Set ownership and permissions
+            sudo chown -R $USER:$USER /opt/opensearch
+
+            # Start OpenSearch in background
+            /opt/opensearch/bin/opensearch -d -p /tmp/opensearch.pid
 
-      # Swagger verification
       - run:
-          name: Verify swagger API specification
+          name: Wait for OpenSearch to be ready
           command: |
-            bundle exec rake swagger:build
-            if [[ `git status swagger/swagger.json --porcelain` ]]
-            then
-              echo "ERROR: The swagger.json file is not in sync with the yaml specification. Run 'rake swagger:build' and commit 'swagger/swagger.json'."
-              exit 1
-            fi
-            curl -L https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.3.0/openapi-generator-cli-6.3.0.jar > ~/tmp/openapi-generator-cli-6.3.0.jar
-            java -jar ~/tmp/openapi-generator-cli-6.3.0.jar validate -i swagger/swagger.json
+            echo "Waiting for OpenSearch to start..."
+            for i in {1..30}; do
+              if curl -s http://localhost:9200/_cluster/health | grep -q '"status"'; then
+                echo "OpenSearch is ready!"
+                exit 0
+              fi
+              echo "Waiting... ($i/30)"
+              sleep 2
+            done
+            echo "OpenSearch failed to start"
+            exit 1
 
-      # we remove the FRONTED_URL from the .env before running the tests
+      # Configure environment and database
       - run:
           name: Database Setup and Configure Environment Variables
           command: |
@@ -127,65 +277,98 @@ jobs:
             sed -i -e '/POSTGRES_USERNAME/ s/=.*/=chatwoot/' .env
             sed -i -e "/POSTGRES_PASSWORD/ s/=.*/=$pg_pass/" .env
             echo -en "\nINSTALLATION_ENV=circleci" >> ".env"
+            echo -en "\nOPENSEARCH_URL=http://localhost:9200" >> ".env"
 
       # Database setup
       - run:
           name: Run DB migrations
           command: bundle exec rails db:chatwoot_prepare
 
-      # Bundle audit
-      - run:
-          name: Bundle audit
-          command: bundle exec bundle audit update && bundle exec bundle audit check -v
-
-      # Rubocop linting
-      - run:
-          name: Rubocop
-          command: bundle exec rubocop
-
-      # ESLint linting
-      - run:
-          name: eslint
-          command: pnpm run eslint
-
-      - run:
-          name: Run frontend tests
-          command: |
-            mkdir -p ~/build/coverage/frontend
-            ~/tmp/cc-test-reporter before-build
-            pnpm run test:coverage
-
-      - run:
-          name: Code Climate Test Coverage (Frontend)
-          command: |
-            ~/tmp/cc-test-reporter format-coverage -t lcov -o "~/build/coverage/frontend/codeclimate.frontend_$CIRCLE_NODE_INDEX.json"
-
-      # Run backend tests
+      # Run backend tests (parallelized)
       - run:
           name: Run backend tests
           command: |
             mkdir -p ~/tmp/test-results/rspec
             mkdir -p ~/tmp/test-artifacts
             mkdir -p ~/build/coverage/backend
-            ~/tmp/cc-test-reporter before-build
-            TESTFILES=$(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)
-            bundle exec rspec --format progress \
+
+            # Use round-robin distribution (same as GitHub Actions) for better test isolation
+            # This prevents tests with similar timing from being grouped on the same runner
+            SPEC_FILES=($(find spec -name '*_spec.rb' | sort))
+            TESTS=""
+
+            for i in "${!SPEC_FILES[@]}"; do
+              if [ $(( i % $CIRCLE_NODE_TOTAL )) -eq $CIRCLE_NODE_INDEX ]; then
+                TESTS="$TESTS ${SPEC_FILES[$i]}"
+              fi
+            done
+
+            bundle exec rspec -I ./spec --require coverage_helper --require spec_helper --format progress \
                               --format RspecJunitFormatter \
                               --out ~/tmp/test-results/rspec.xml \
-                              -- ${TESTFILES}
+                              -- $TESTS
           no_output_timeout: 30m
 
-      - run:
-          name: Code Climate Test Coverage (Backend)
-          command: |
-            ~/tmp/cc-test-reporter format-coverage -t simplecov -o "~/build/coverage/backend/codeclimate.$CIRCLE_NODE_INDEX.json"
+      # Store test results for better splitting in future runs
+      - store_test_results:
+          path: ~/tmp/test-results
 
       - run:
-          name: List coverage directory contents
+          name: Move coverage files if they exist
           command: |
-            ls -R ~/build/coverage
+            if [ -d "coverage" ]; then
+              mkdir -p ~/build/coverage
+              cp -r coverage ~/build/coverage/backend || true
+            fi
+          when: always
 
       - persist_to_workspace:
           root: ~/build
           paths:
             - coverage
+
+  # Collect coverage from all jobs
+  coverage:
+    <<: *defaults
+    steps:
+      - checkout
+      - attach_workspace:
+          at: ~/build
+
+      # Qlty coverage publish
+      - qlty-orb/coverage_publish:
+          files: |
+            coverage/frontend/lcov.info
+
+      - run:
+          name: List coverage directory contents
+          command: |
+            ls -R ~/build/coverage || echo "No coverage directory"
+
+      - store_artifacts:
+          path: coverage
+          destination: coverage
+
+  build:
+    <<: *defaults
+    steps:
+      - run:
+          name: Legacy build aggregator
+          command: |
+            echo "All main jobs passed; build job kept only for GitHub required check compatibility."
+
+workflows:
+  version: 2
+  build:
+    jobs:
+      - lint
+      - frontend-tests
+      - backend-tests
+      - coverage:
+          requires:
+            - frontend-tests
+            - backend-tests
+      - build:
+          requires:
+            - lint
+            - coverage

.devcontainer/docker-compose.base.yml

@@ -10,7 +10,7 @@ services:
       dockerfile: .devcontainer/Dockerfile.base
       args:
         VARIANT: 'ubuntu-22.04'
-        NODE_VERSION: '23.7.0'
+        NODE_VERSION: '24.13.0'
         RUBY_VERSION: '3.4.4'
         # On Linux, you may need to update USER_UID and USER_GID below if not your local UID is not 1000.
         USER_UID: '1000'

.devcontainer/docker-compose.yml

@@ -11,7 +11,7 @@ services:
       dockerfile: .devcontainer/Dockerfile
       args:
         VARIANT: 'ubuntu-22.04'
-        NODE_VERSION: '23.7.0'
+        NODE_VERSION: '24.13.0'
         RUBY_VERSION: '3.4.4'
         # On Linux, you may need to update USER_UID and USER_GID below if not your local UID is not 1000.
         USER_UID: '1000'

.env.example

@@ -6,6 +6,13 @@
 # Use `rake secret` to generate this variable
 SECRET_KEY_BASE=replace_with_lengthy_secure_hex
 
+# Active Record Encryption keys (required for MFA/2FA functionality)
+# Generate these keys by running: rails db:encryption:init
+# IMPORTANT: Use different keys for each environment (development, staging, production)
+# ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=
+# ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=
+# ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=
+
 # Replace with the URL you are planning to use for your app
 FRONTEND_URL=http://0.0.0.0:3000
 # To use a dedicated URL for help center pages
@@ -91,6 +98,8 @@ SMTP_OPENSSL_VERIFY_MODE=peer
 # Mail Incoming
 # This is the domain set for the reply emails when conversation continuity is enabled
 MAILER_INBOUND_EMAIL_DOMAIN=
+# Maximum time in seconds to process a single IMAP email
+# EMAIL_PROCESSING_TIMEOUT_SECONDS=60
 # Set this to the appropriate ingress channel with regards to incoming emails
 # Possible values are :
 # relay for Exim, Postfix, Qmail
@@ -98,6 +107,7 @@ MAILER_INBOUND_EMAIL_DOMAIN=
 # mandrill for Mandrill
 # postmark for Postmark
 # sendgrid for Sendgrid
+# ses for Amazon SES
 RAILS_INBOUND_EMAIL_SERVICE=
 # Use one of the following based on the email ingress service
 # Ref: https://edgeguides.rubyonrails.org/action_mailbox_basics.html
@@ -107,6 +117,10 @@ RAILS_INBOUND_EMAIL_PASSWORD=
 MAILGUN_INGRESS_SIGNING_KEY=
 MANDRILL_INGRESS_API_KEY=
 
+# SNS topic ARN for ActionMailbox (format: arn:aws:sns:region:account-id:topic-name)
+# Configure only if the rails_inbound_email_service = ses
+ACTION_MAILBOX_SES_SNS_TOPIC=
+
 # Creating Your Inbound Webhook Instructions for Postmark and Sendgrid:
 # Inbound webhook URL format:
 #    https://actionmailbox:[YOUR_RAILS_INBOUND_EMAIL_PASSWORD]@[YOUR_CHATWOOT_DOMAIN.COM]/rails/action_mailbox/[RAILS_INBOUND_EMAIL_SERVICE]/inbound_emails
@@ -208,6 +222,7 @@ ANDROID_SHA256_CERT_FINGERPRINT=AC:73:8E:DE:EB:56:EA:CC:10:87:02:A7:65:37:7B:38:
 ## https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#environment-variables
 # DD_TRACE_AGENT_URL=
 
+
 # MaxMindDB API key to download GeoLite2 City database
 # IP_LOOKUP_API_KEY=
 
@@ -219,6 +234,10 @@ ANDROID_SHA256_CERT_FINGERPRINT=AC:73:8E:DE:EB:56:EA:CC:10:87:02:A7:65:37:7B:38:
 # Comma-separated list of trusted IPs that bypass Rack Attack throttling rules
 # RACK_ATTACK_ALLOWED_IPS=127.0.0.1,::1,192.168.0.10
 
+## SafeFetch private network access
+## Keep disabled by default. Self-hosted installations can enable this to allow SafeFetch requests to private network URLs.
+# SAFE_FETCH_ALLOW_PRIVATE_NETWORK=false
+
 ## Running chatwoot as an API only server
 ## setting this value to true will disable the frontend dashboard endpoints
 # CW_API_ONLY_SERVER=false
@@ -249,6 +268,8 @@ AZURE_APP_SECRET=
 ## Change these values to fine tune performance
 # control the concurrency setting of sidekiq
 # SIDEKIQ_CONCURRENCY=10
+# Enable verbose logging each time a job is dequeued in Sidekiq
+# ENABLE_SIDEKIQ_DEQUEUE_LOGGER=false
 
 
 # AI powered features
@@ -259,3 +280,6 @@ AZURE_APP_SECRET=
 # Set to true if you want to remove stale contact inboxes
 # contact_inboxes with no conversation older than 90 days will be removed
 # REMOVE_STALE_CONTACT_INBOX_JOB_STATUS=false
+
+# REDIS_ALFRED_SIZE=10
+# REDIS_VELMA_SIZE=10

.github/scripts/ghsa_linear_sync.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Sync triage GitHub security advisories to Linear issues."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import requests
+
+GITHUB_API = "https://api.github.com"
+LINEAR_API = "https://api.linear.app/graphql"
+
+SEVERITY_PRIORITY = {"critical": 1, "high": 2, "medium": 3, "low": 4}
+SEVERITY_COLOR = {
+    "critical": 15548997,
+    "high": 15105570,
+    "medium": 15844367,
+    "low": 3066993,
+}
+DEFAULT_COLOR = 9807270
+
+
+def required_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        sys.exit(f"Missing required env var: {name}")
+    return value
+
+
+def fetch_triage_advisories(repo: str, token: str) -> list[dict[str, Any]]:
+    url: str | None = f"{GITHUB_API}/repos/{repo}/security-advisories"
+    params: dict[str, Any] | None = {"state": "triage", "per_page": 100}
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "Authorization": f"Bearer {token}",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    advisories: list[dict[str, Any]] = []
+    while url:
+        r = requests.get(url, headers=headers, params=params, timeout=30)
+        r.raise_for_status()
+        advisories.extend(r.json())
+        next_link = r.links.get("next")
+        url = next_link["url"] if next_link else None
+        params = None
+    return advisories
+
+
+def linear_call(query: str, variables: dict[str, Any], api_key: str) -> dict[str, Any]:
+    r = requests.post(
+        LINEAR_API,
+        headers={"Authorization": api_key},
+        json={"query": query, "variables": variables},
+        timeout=30,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def linear_issue_exists(ghsa_id: str, api_key: str) -> bool:
+    query = (
+        "query($q: String!) { issues(filter: {title: {contains: $q}}, first: 1) "
+        "{ nodes { id } } }"
+    )
+    resp = linear_call(query, {"q": ghsa_id}, api_key)
+    return len(resp.get("data", {}).get("issues", {}).get("nodes", [])) > 0
+
+
+def linear_create_issue(input_data: dict[str, Any], api_key: str) -> dict[str, str] | None:
+    query = (
+        "mutation($input: IssueCreateInput!) { issueCreate(input: $input) "
+        "{ success issue { identifier url } } }"
+    )
+    resp = linear_call(query, {"input": input_data}, api_key)
+    create = resp.get("data", {}).get("issueCreate") or {}
+    if not create.get("success"):
+        return None
+    return create.get("issue")
+
+
+def reporter_login(advisory: dict[str, Any]) -> str:
+    for credit in advisory.get("credits") or []:
+        user = (credit or {}).get("user") or {}
+        if user.get("login"):
+            return user["login"]
+    return "unknown"
+
+
+def cvss_score(advisory: dict[str, Any]) -> str:
+    score = (advisory.get("cvss") or {}).get("score")
+    return str(score) if score is not None else "n/a"
+
+
+def build_description(adv: dict[str, Any]) -> str:
+    return (
+        f"**GHSA:** {adv['ghsa_id']}\n"
+        f"**CVE:** {adv.get('cve_id') or 'n/a'}\n"
+        f"**Severity:** {adv.get('severity') or 'unknown'} (CVSS {cvss_score(adv)})\n"
+        f"**Reporter:** {reporter_login(adv)}\n"
+        f"**Reported:** {(adv.get('created_at') or '').split('T')[0]}\n"
+        f"**Advisory:** {adv['html_url']}\n\n"
+        f"---\n\n"
+        f"{adv.get('description') or 'No description provided.'}"
+    )
+
+
+def post_discord(adv: dict[str, Any], issue: dict[str, str], webhook_url: str) -> None:
+    severity = adv.get("severity") or "unknown"
+    title = f"[{adv['ghsa_id']}] {adv['summary']}"[:250]
+    payload = {
+        "username": "GHSA Sync",
+        "embeds": [
+            {
+                "title": title,
+                "url": issue["url"],
+                "color": SEVERITY_COLOR.get(severity, DEFAULT_COLOR),
+                "fields": [
+                    {"name": "Linear", "value": issue["identifier"], "inline": True},
+                    {
+                        "name": "Severity",
+                        "value": f"{severity} (CVSS {cvss_score(adv)})",
+                        "inline": True,
+                    },
+                    {
+                        "name": "Advisory",
+                        "value": f"[GitHub]({adv['html_url']})",
+                        "inline": True,
+                    },
+                ],
+            }
+        ],
+    }
+    try:
+        requests.post(webhook_url, json=payload, timeout=10)
+    except requests.RequestException:
+        pass
+
+
+def main() -> int:
+    repo = required_env("GITHUB_REPOSITORY")
+    gh_token = required_env("GHSA_READ_TOKEN")
+    linear_api_key = required_env("LINEAR_API_KEY")
+    team_id = required_env("LINEAR_TEAM_ID")
+    project_id = required_env("LINEAR_PROJECT_ID")
+    label_id = required_env("LINEAR_LABEL_ID")
+    discord_webhook = os.environ.get("DISCORD_WEBHOOK_URL") or None
+
+    advisories = fetch_triage_advisories(repo, gh_token)
+    print(f"Fetched {len(advisories)} triage advisories")
+
+    created = skipped = failed = 0
+
+    for adv in advisories:
+        ghsa_id = adv.get("ghsa_id")
+        if not ghsa_id:
+            failed += 1
+            continue
+
+        try:
+            if linear_issue_exists(ghsa_id, linear_api_key):
+                skipped += 1
+                continue
+
+            severity = adv.get("severity") or "unknown"
+            issue = linear_create_issue(
+                {
+                    "title": f"[{ghsa_id}] {adv.get('summary', '')}",
+                    "description": build_description(adv),
+                    "teamId": team_id,
+                    "projectId": project_id,
+                    "labelIds": [label_id],
+                    "priority": SEVERITY_PRIORITY.get(severity, 3),
+                },
+                linear_api_key,
+            )
+        except requests.RequestException:
+            failed += 1
+            continue
+
+        if not issue:
+            failed += 1
+            continue
+
+        created += 1
+        if discord_webhook:
+            post_discord(adv, issue, discord_webhook)
+
+    print(f"Created {created}, skipped {skipped}, failed {failed}")
+    return 1 if failed > 0 else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/deploy_check.yml

@@ -11,6 +11,9 @@ concurrency:
   group: pr-${{ github.workflow }}-${{ github.head_ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   deployment_check:
     name: Check Deployment

.github/workflows/frontend-fe.yml

@@ -8,6 +8,9 @@ on:
     branches:
       - develop
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-22.04
@@ -26,7 +29,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 23
+          node-version: 24
           cache: 'pnpm'
 
       - name: Install pnpm dependencies

.github/workflows/ghsa-linear-sync.yml

@@ -0,0 +1,29 @@
+name: Sync GHSA advisories to Linear
+
+on:
+  schedule:
+    - cron: '0 4 * * *'  # daily at 09:30 IST
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: pip install requests==2.32.3
+      - name: Sync advisories
+        env:
+          GHSA_READ_TOKEN: ${{ secrets.GHSA_READ_TOKEN }}
+          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+          LINEAR_TEAM_ID: ${{ secrets.LINEAR_TEAM_ID }}
+          LINEAR_PROJECT_ID: ${{ secrets.LINEAR_PROJECT_ID }}
+          LINEAR_LABEL_ID: ${{ secrets.LINEAR_LABEL_ID }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+        run: python3 .github/scripts/ghsa_linear_sync.py

.github/workflows/logging_percentage_check.yml

@@ -10,6 +10,9 @@ concurrency:
   group: pr-${{ github.workflow }}-${{ github.head_ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   log_lines_check:
     runs-on: ubuntu-latest

.github/workflows/nightly_installer.yml

@@ -14,6 +14,9 @@ on:
     - cron: "0 0 * * *"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   nightly:
     runs-on: ubuntu-24.04

.github/workflows/publish_codespace_image.yml

@@ -3,6 +3,10 @@ name: Publish Codespace Base Image
 on:
   workflow_dispatch:
 
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   publish-code-space-image:
     runs-on: ubuntu-latest

.github/workflows/publish_ee_docker.yml

@@ -18,6 +18,9 @@ on:
 env:
   DOCKER_REPO: chatwoot/chatwoot
 
+permissions:
+  contents: read
+
 jobs:
   build:
     strategy:

.github/workflows/publish_foss_docker.yml

@@ -18,6 +18,9 @@ on:
 env:
   DOCKER_REPO: chatwoot/chatwoot
 
+permissions:
+  contents: read
+
 jobs:
   build:
     strategy:

.github/workflows/run_foss_spec.yml

@@ -1,4 +1,6 @@
 name: Run Chatwoot CE spec
+permissions:
+  contents: read
 on:
   push:
     branches:
@@ -8,11 +10,58 @@ on:
   workflow_dispatch:
 
 jobs:
-  test:
-    runs-on: ubuntu-22.04
+  # Separate linting jobs for faster feedback
+  lint-backend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Run Rubocop
+        run: bundle exec rubocop --parallel
+
+  lint-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'pnpm'
+      - name: Install pnpm dependencies
+        run: pnpm i
+      - name: Run ESLint
+        run: pnpm run eslint
+
+  # Frontend tests run in parallel with backend
+  frontend-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'pnpm'
+      - name: Install pnpm dependencies
+        run: pnpm i
+      - name: Run frontend tests
+        run: pnpm run test:coverage
+
+  # Backend tests with parallelization
+  backend-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ci_node_total: [16]
+        ci_node_index: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
+
     services:
       postgres:
-        image: pgvector/pgvector:pg15
+        image: pgvector/pgvector:pg16
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: ''
@@ -20,8 +69,6 @@ jobs:
           POSTGRES_HOST_AUTH_METHOD: trust
         ports:
           - 5432:5432
-        # needed because the postgres container does not provide a healthcheck
-        # tmpfs makes DB faster by using RAM
         options: >-
           --mount type=tmpfs,destination=/var/lib/postgresql/data
           --health-cmd pg_isready
@@ -29,7 +76,7 @@ jobs:
           --health-timeout 5s
           --health-retries 5
       redis:
-        image: redis
+        image: redis:alpine
         ports:
           - 6379:6379
         options: --entrypoint redis-server
@@ -43,11 +90,11 @@ jobs:
 
       - uses: ruby/setup-ruby@v1
         with:
-          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          bundler-cache: true
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 23
+          node-version: 24
           cache: 'pnpm'
 
       - name: Install pnpm dependencies
@@ -64,19 +111,36 @@ jobs:
       - name: Seed database
         run: bundle exec rake db:schema:load
 
-      - name: Run frontend tests
-        run: pnpm run test:coverage
-
-      # Run rails tests
-      - name: Run backend tests
+      - name: Run backend tests (parallelized)
         run: |
-          bundle exec rspec --profile=10 --format documentation
+          # Get all spec files and split them using round-robin distribution
+          # This ensures slow tests are distributed evenly across all nodes
+          SPEC_FILES=($(find spec -name '*_spec.rb' | sort))
+          TESTS=""
+
+          for i in "${!SPEC_FILES[@]}"; do
+            # Assign spec to this node if: index % total == node_index
+            if [ $(( i % ${{ matrix.ci_node_total }} )) -eq ${{ matrix.ci_node_index }} ]; then
+              TESTS="$TESTS ${SPEC_FILES[$i]}"
+            fi
+          done
+
+          if [ -n "$TESTS" ]; then
+            bundle exec rspec --profile=10 --format progress --format json --out tmp/rspec_results.json $TESTS
+          fi
         env:
           NODE_OPTIONS: --openssl-legacy-provider
 
-      - name: Upload rails log folder
+      - name: Upload test results
         uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: rails-log-folder
+          name: rspec-results-${{ matrix.ci_node_index }}
+          path: tmp/rspec_results.json
+
+      - name: Upload rails log folder
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: rails-log-folder-${{ matrix.ci_node_index }}
           path: log

.github/workflows/run_mfa_spec.yml

@@ -0,0 +1,100 @@
+name: Run MFA Tests
+permissions:
+  contents: read
+
+on:
+  pull_request:
+
+# If two pushes happen within a short time in the same PR, cancel the run of the oldest push
+concurrency:
+  group: pr-${{ github.workflow }}-${{ github.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    # Only run if MFA test keys are available
+    if: github.event_name == 'workflow_dispatch' || (github.repository == 'chatwoot/chatwoot' && github.actor != 'dependabot[bot]')
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: ''
+          POSTGRES_DB: postgres
+          POSTGRES_HOST_AUTH_METHOD: trust
+        ports:
+          - 5432:5432
+        options: >-
+          --mount type=tmpfs,destination=/var/lib/postgresql/data
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+        options: --entrypoint redis-server
+
+    env:
+      RAILS_ENV: test
+      POSTGRES_HOST: localhost
+      # Active Record encryption keys required for MFA - test keys only, not for production use
+      ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: 'test_key_a6cde8f7b9c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7'
+      ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: 'test_key_b7def9a8c0d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d8'
+      ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: 'test_salt_c8efa0b9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d9'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Create database
+        run: bundle exec rake db:create
+
+      - name: Install pgvector extension
+        run: |
+          PGPASSWORD="" psql -h localhost -U postgres -d chatwoot_test -c "CREATE EXTENSION IF NOT EXISTS vector;"
+
+      - name: Seed database
+        run: bundle exec rake db:schema:load
+
+      - name: Run MFA-related backend tests
+        run: |
+          bundle exec rspec \
+            spec/services/mfa/token_service_spec.rb \
+            spec/services/mfa/authentication_service_spec.rb \
+            spec/requests/api/v1/profile/mfa_controller_spec.rb \
+            spec/controllers/devise_overrides/sessions_controller_spec.rb \
+            spec/models/application_record_external_credentials_encryption_spec.rb \
+            --profile=10 \
+            --format documentation
+        env:
+          NODE_OPTIONS: --openssl-legacy-provider
+
+      - name: Run MFA-related tests in user_spec
+        run: |
+          # Run specific MFA-related tests from user_spec
+          bundle exec rspec spec/models/user_spec.rb \
+            -e "two factor" \
+            -e "2FA" \
+            -e "MFA" \
+            -e "otp" \
+            -e "backup code" \
+            --profile=10 \
+            --format documentation
+        env:
+          NODE_OPTIONS: --openssl-legacy-provider
+
+      - name: Upload test logs
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: mfa-test-logs
+          path: |
+            log/test.log
+            tmp/screenshots/

.github/workflows/size-limit.yml

@@ -10,6 +10,9 @@ concurrency:
   group: pr-${{ github.workflow }}-${{ github.head_ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-22.04
@@ -28,7 +31,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 23
+          node-version: 24
           cache: 'pnpm'
 
       - name: pnpm

.github/workflows/test_docker_build.yml

@@ -7,6 +7,9 @@ on:
       - master
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   test-build:
     strategy:
@@ -36,5 +39,5 @@ jobs:
           platforms: ${{ matrix.platform }}
           push: false
           load: false
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=${{ matrix.platform }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.platform }}

.gitignore

@@ -94,4 +94,13 @@ yarn-debug.log*
 .vscode
 .claude/settings.local.json
 .cursor
+.codex/
+.claude/
 CLAUDE.local.md
+
+# Histoire deployment
+.netlify
+.histoire
+.pnpm-store/*
+local/
+Procfile.worktree

.nvmrc

@@ -1 +1 @@
-20.5.1
+24.13.0

.qlty/qlty.toml

@@ -39,7 +39,7 @@ exclude_patterns = [
   "**/target/**",
   "**/templates/**",
   "**/testdata/**",
-  "**/vendor/**", "spec/", "**/specs/**/**", "**/spec/**/**", "db/*", "bin/**/*", "db/**/*", "config/**/*", "public/**/*", "vendor/**/*", "node_modules/**/*", "lib/tasks/auto_annotate_models.rake", "app/test-matchers.js", "docs/*", "**/*.md", "**/*.yml", "app/javascript/dashboard/i18n/locale", "**/*.stories.js", "stories/", "app/javascript/dashboard/components/widgets/conversation/advancedFilterItems/index.js", "app/javascript/shared/constants/countries.js", "app/javascript/dashboard/components/widgets/conversation/advancedFilterItems/languages.js", "app/javascript/dashboard/routes/dashboard/contacts/contactFilterItems/index.js", "app/javascript/dashboard/routes/dashboard/settings/automation/constants.js", "app/javascript/dashboard/components/widgets/FilterInput/FilterOperatorTypes.js", "app/javascript/dashboard/routes/dashboard/settings/reports/constants.js", "app/javascript/dashboard/store/captain/storeFactory.js", "app/javascript/dashboard/i18n/index.js", "app/javascript/widget/i18n/index.js", "app/javascript/survey/i18n/index.js", "app/javascript/shared/constants/locales.js", "app/javascript/dashboard/helper/specs/macrosFixtures.js", "app/javascript/dashboard/routes/dashboard/settings/macros/constants.js", "**/fixtures/**", "**/*/fixtures.js",
+  "**/vendor/**", "spec/", "**/specs/**/**", "**/spec/**/**", "db/*", "bin/**/*", "db/**/*", "config/**/*", "public/**/*", "vendor/**/*", "node_modules/**/*", "lib/tasks/auto_annotate_models.rake", "app/test-matchers.js", "docs/*", "**/*.md", "**/*.yml", "app/javascript/dashboard/i18n/locale", "**/*.stories.js", "stories/", "app/javascript/dashboard/components/widgets/conversation/advancedFilterItems/index.js", "app/javascript/shared/constants/countries.js", "app/javascript/dashboard/components/widgets/conversation/advancedFilterItems/languages.js", "app/javascript/dashboard/routes/dashboard/contacts/contactFilterItems/index.js", "app/javascript/dashboard/routes/dashboard/settings/automation/constants.js", "app/javascript/dashboard/components/widgets/FilterInput/FilterOperatorTypes.js", "app/javascript/dashboard/routes/dashboard/settings/reports/constants.js", "app/javascript/dashboard/store/storeFactory.js", "app/javascript/dashboard/i18n/index.js", "app/javascript/widget/i18n/index.js", "app/javascript/survey/i18n/index.js", "app/javascript/shared/constants/locales.js", "app/javascript/dashboard/helper/specs/macrosFixtures.js", "app/javascript/dashboard/routes/dashboard/settings/macros/constants.js", "**/fixtures/**", "**/*/fixtures.js",
 ]
 
 test_patterns = [

.rubocop.yml

@@ -7,6 +7,8 @@ plugins:
 require:
   - ./rubocop/use_from_email.rb
   - ./rubocop/custom_cop_location.rb
+  - ./rubocop/attachment_download.rb
+  - ./rubocop/one_class_per_file.rb
 
 Layout/LineLength:
   Max: 150
@@ -23,7 +25,7 @@ Metrics/MethodLength:
     - 'enterprise/lib/captain/agent.rb'
 
 RSpec/ExampleLength:
-  Max: 25
+  Max: 50
 
 Style/Documentation:
   Enabled: false
@@ -40,6 +42,12 @@ Style/SymbolArray:
 Style/OpenStructUse:
   Enabled: false
 
+Chatwoot/AttachmentDownload:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
 Style/OptionalBooleanParameter:
   Exclude:
     - 'app/services/email_templates/db_resolver_service.rb'
@@ -87,7 +95,7 @@ Metrics/ModuleLength:
 Rails/HelperInstanceVariable:
   Exclude:
     - enterprise/app/helpers/captain/chat_helper.rb
-
+    - enterprise/app/helpers/captain/chat_response_helper.rb
 Rails/ApplicationController:
   Exclude:
     - 'app/controllers/api/v1/widget/messages_controller.rb'
@@ -205,6 +213,9 @@ UseFromEmail:
 CustomCopLocation:
   Enabled: true
 
+Style/OneClassPerFile:
+  Enabled: true
+
 AllCops:
   NewCops: enable
   Exclude:
@@ -336,4 +347,4 @@ FactoryBot/RedundantFactoryOption:
   Enabled: false
 
 FactoryBot/FactoryAssociationWithStrategy:
-  Enabled: false
+  Enabled: false

AGENTS.md

@@ -4,12 +4,20 @@
 
 - **Setup**: `bundle install && pnpm install`
 - **Run Dev**: `pnpm dev` or `overmind start -f ./Procfile.dev`
+- **Seed Local Test Data**: `bundle exec rails db:seed` (quickly populates minimal data for standard feature verification)
+- **Seed Search Test Data**: `bundle exec rails search:setup_test_data` (bulk fixture generation for search/performance/manual load scenarios)
+- **Seed Account Sample Data (richer test data)**: `Seeders::AccountSeeder` is available as an internal utility and is exposed through Super Admin `Accounts#seed`, but can be used directly in dev workflows too:
+  - UI path: Super Admin → Accounts → Seed (enqueues `Internal::SeedAccountJob`).
+  - CLI path: `bundle exec rails runner "Internal::SeedAccountJob.perform_now(Account.find(<id>))"` (or call `Seeders::AccountSeeder.new(account: Account.find(<id>)).perform!` directly).
 - **Lint JS/Vue**: `pnpm eslint` / `pnpm eslint:fix`
 - **Lint Ruby**: `bundle exec rubocop -a`
 - **Test JS**: `pnpm test` or `pnpm test:watch`
 - **Test Ruby**: `bundle exec rspec spec/path/to/file_spec.rb`
 - **Single Test**: `bundle exec rspec spec/path/to/file_spec.rb:LINE_NUMBER`
 - **Run Project**: `overmind start -f Procfile.dev`
+- **Ruby Version**: Manage Ruby via `rbenv` and install the version listed in `.ruby-version` (e.g., `rbenv install $(cat .ruby-version)`)
+- **rbenv setup**: Before running any `bundle` or `rspec` commands, init rbenv in your shell (`eval "$(rbenv init -)"`) so the correct Ruby/Bundler versions are used
+- Always prefer `bundle exec` for Ruby CLI tasks (rspec, rake, rubocop, etc.)
 
 ## Code Style
 
@@ -37,13 +45,38 @@
 
 - MVP focus: Least code change, happy-path only
 - No unnecessary defensive programming
+- Ship the happy path first: limit guards/fallbacks to what production has proven necessary, then iterate
+- Prefer minimal, readable code over elaborate abstractions; clarity beats cleverness
 - Break down complex tasks into small, testable units
 - Iterate after confirmation
 - Avoid writing specs unless explicitly asked
 - Remove dead/unreachable/unused code
 - Don’t write multiple versions or backups for the same logic — pick the best approach and implement it
+- Prefer `with_modified_env` (from spec helpers) over stubbing `ENV` directly in specs
+- Specs in parallel/reloading environments: prefer comparing `error.class.name` over constant class equality when asserting raised errors
+
+## Codex Worktree Workflow
+
+- Use a separate git worktree + branch per task to keep changes isolated.
+- Keep Codex-specific local setup under `.codex/` and use `Procfile.worktree` for worktree process orchestration.
+- The setup workflow in `.codex/environments/environment.toml` should dynamically generate per-worktree DB/port values (Rails, Vite, Redis DB index) to avoid collisions.
+- Start each worktree with its own Overmind socket/title so multiple instances can run at the same time.
+
+## Commit Messages
+
+- Prefer Conventional Commits: `type(scope): subject` (scope optional)
+- Example: `feat(auth): add user authentication`
 - Don't reference Claude in commit messages
 
+## PR Description Format
+
+- Start with a short, user-facing paragraph describing the product change.
+- Add a `Closes` section with relevant issue links (GitHub, Linear, etc.).
+- For feature PRs, add `How to test` from a product/UX standpoint.
+- For bugfix PRs, use `How to reproduce` when helpful.
+- Optionally add a `What changed` section for implementation highlights.
+- Do not add a `How this was tested` section listing specs/commands.
+
 ## Project-Specific
 
 - **Translations**:
@@ -73,3 +106,8 @@ Practical checklist for any change impacting core logic or public APIs
 - Keep request/response contracts stable across OSS and Enterprise; update both sets of routes/controllers when introducing new APIs.
 - When renaming/moving shared code, mirror the change in `enterprise/` to prevent drift.
 - Tests: Add Enterprise-specific specs under `spec/enterprise`, mirroring OSS spec layout where applicable.
+- When modifying existing OSS features for Enterprise-only behavior, add an Enterprise module (via `prepend_mod_with`/`include_mod_with`) instead of editing OSS files directly—especially for policies, controllers, and services. For Enterprise-exclusive features, place code directly under `enterprise/`.
+
+## Branding / White-labeling note
+
+- For user-facing strings that currently contain "Chatwoot" but should adapt to branded/self-hosted installs, prefer applying `replaceInstallationName` from `shared/composables/useBranding` in the UI layer (for example tooltip and suggestion labels) instead of adding hardcoded brand-specific copy.

Gemfile

@@ -21,6 +21,8 @@ gem 'telephone_number'
 gem 'time_diff'
 gem 'tzinfo-data'
 gem 'valid_email2'
+gem 'email-provider-info'
+gem 'gemoji'
 # compress javascript config.assets.js_compressor
 gem 'uglifier'
 ##-- used for single column multiple binary flags in notification settings/feature flagging --##
@@ -39,6 +41,8 @@ gem 'json_refs'
 gem 'rack-attack', '>= 6.7.0'
 # a utility tool for streaming, flexible and safe downloading of remote files
 gem 'down'
+# SSRF-safe URL fetching
+gem 'ssrf_filter', '~> 1.5'
 # authentication type to fetch and send mail over oauth2.0
 gem 'gmail_xoauth'
 # Lock net-smtp to 0.3.4 to avoid issues with gmail_xoauth2
@@ -54,6 +58,9 @@ gem 'azure-storage-blob', git: 'https://github.com/chatwoot/azure-storage-ruby',
 gem 'google-cloud-storage', '>= 1.48.0', require: false
 gem 'image_processing'
 
+##-- for actionmailbox --##
+gem 'aws-actionmailbox-ses', '~> 0'
+
 ##-- gems for database --#
 gem 'groupdate'
 gem 'pg'
@@ -62,10 +69,14 @@ gem 'redis-namespace'
 # super fast record imports in bulk
 gem 'activerecord-import'
 
+gem 'searchkick'
+gem 'opensearch-ruby'
+gem 'faraday_middleware-aws-sigv4'
+
 ##--- gems for server & infra configuration ---##
 gem 'dotenv-rails', '>= 3.0.0'
 gem 'foreman'
-gem 'puma'
+gem 'puma', '~> 7.2', '>= 7.2.1'
 gem 'vite_rails'
 # metrics on heroku
 gem 'barnes'
@@ -74,9 +85,13 @@ gem 'barnes'
 gem 'devise', '>= 4.9.4'
 gem 'devise-secure_password', git: 'https://github.com/chatwoot/devise-secure_password', branch: 'chatwoot'
 gem 'devise_token_auth', '>= 1.2.3'
+gem 'rails-i18n', '~> 7.0'
+# two-factor authentication
+gem 'devise-two-factor', '>= 5.0.0'
 # authorization
-gem 'jwt'
+gem 'jwt', '~> 2.10', '>= 2.10.3'
 gem 'pundit'
+
 # super admin
 gem 'administrate', '>= 0.20.1'
 gem 'administrate-field-active_storage', '>= 1.0.3'
@@ -89,14 +104,14 @@ gem 'wisper', '2.0.0'
 ##--- gems for channels ---##
 gem 'facebook-messenger'
 gem 'line-bot-api'
-gem 'twilio-ruby', '~> 5.66'
+gem 'twilio-ruby'
 # twitty will handle subscription of twitter account events
 # gem 'twitty', git: 'https://github.com/chatwoot/twitty'
 gem 'twitty', '~> 0.1.5'
 # facebook client
 gem 'koala'
 # slack client
-gem 'slack-ruby-client', '~> 2.5.2'
+gem 'slack-ruby-client', '~> 2.7.0'
 # for dialogflow integrations
 gem 'google-cloud-dialogflow-v2', '>= 0.24.0'
 gem 'grpc'
@@ -118,9 +133,9 @@ gem 'sentry-ruby', require: false
 gem 'sentry-sidekiq', '>= 5.19.0', require: false
 
 ##-- background job processing --##
-gem 'sidekiq', '>= 7.3.1'
+gem 'sidekiq', '~> 7.3', '>= 7.3.1'
 # We want cron jobs
-gem 'sidekiq-cron', '>= 1.12.0'
+gem 'sidekiq-cron', '>= 2.4.0'
 # for sidekiq healthcheck
 gem 'sidekiq_alive'
 
@@ -151,7 +166,7 @@ gem 'working_hours'
 gem 'pg_search'
 
 # Subscriptions, Billing
-gem 'stripe'
+gem 'stripe', '~> 18.0'
 
 ## - helper gems --##
 ## to populate db with sample data
@@ -167,6 +182,7 @@ gem 'audited', '~> 5.4', '>= 5.4.1'
 
 # need for google auth
 gem 'omniauth', '>= 2.1.2'
+gem 'omniauth-saml'
 gem 'omniauth-google-oauth2', '>= 1.1.3'
 gem 'omniauth-rails_csrf_protection', '~> 1.0', '>= 1.0.2'
 
@@ -179,13 +195,22 @@ gem 'reverse_markdown'
 
 gem 'iso-639'
 gem 'ruby-openai'
-gem 'ai-agents', '>= 0.4.3'
+gem 'ai-agents', '>= 0.10.0'
 
 # TODO: Move this gem as a dependency of ai-agents
+gem 'ruby_llm', '>= 1.14.1'
 gem 'ruby_llm-schema'
 
+gem 'cld3', '~> 3.7'
+
+# OpenTelemetry for LLM observability
+gem 'opentelemetry-sdk'
+gem 'opentelemetry-exporter-otlp'
+
 gem 'shopify_api'
 
+gem 'firecrawl-sdk', '~> 1.0', require: 'firecrawl'
+
 ### Gems required only in specific deployment environments ###
 ##############################################################
 
@@ -198,7 +223,7 @@ group :production do
 end
 
 group :development do
-  gem 'annotate'
+  gem 'annotaterb'
   gem 'bullet'
   gem 'letter_opener'
   gem 'scss_lint', require: false
@@ -212,6 +237,8 @@ group :development do
   gem 'stackprof'
   # Should install the associated chrome extension to view query logs
   gem 'meta_request', '>= 0.8.3'
+
+  gem 'tidewave'
 end
 
 group :test do
@@ -221,6 +248,7 @@ group :test do
   gem 'webmock'
   # test profiling
   gem 'test-prof'
+  gem 'simplecov_json_formatter', require: false
 end
 
 group :development, :test do
@@ -245,7 +273,8 @@ group :development, :test do
   gem 'rubocop-factory_bot', require: false
   gem 'seed_dump'
   gem 'shoulda-matchers'
-  gem 'simplecov', '0.17.1', require: false
+  gem 'simplecov', '>= 0.21', require: false
+  gem 'skooma'
   gem 'spring'
   gem 'spring-watcher-listen'
 end

Gemfile.lock

@@ -108,8 +108,8 @@ GEM
     acts-as-taggable-on (12.0.0)
       activerecord (>= 7.1, < 8.1)
       zeitwerk (>= 2.4, < 3.0)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     administrate (0.20.1)
       actionpack (>= 6.0, < 8.0)
       actionview (>= 6.0, < 8.0)
@@ -126,39 +126,51 @@ GEM
       jbuilder (~> 2)
       rails (>= 4.2, < 7.2)
       selectize-rails (~> 0.6)
-    ai-agents (0.4.3)
-      ruby_llm (~> 1.3)
-    annotate (3.2.0)
-      activerecord (>= 3.2, < 8.0)
-      rake (>= 10.4, < 14.0)
+    ai-agents (0.10.0)
+      ruby_llm (~> 1.14)
+    annotaterb (4.20.0)
+      activerecord (>= 6.0.0)
+      activesupport (>= 6.0.0)
     ast (2.4.3)
     attr_extras (7.1.0)
     audited (5.4.1)
       activerecord (>= 5.0, < 7.7)
       activesupport (>= 5.0, < 7.7)
-    aws-eventstream (1.2.0)
-    aws-partitions (1.760.0)
-    aws-sdk-core (3.171.1)
-      aws-eventstream (~> 1, >= 1.0.2)
-      aws-partitions (~> 1, >= 1.651.0)
-      aws-sigv4 (~> 1.5)
+    auth-sanitizer (0.2.1)
+      version_gem (~> 1.1, >= 1.1.10)
+    aws-actionmailbox-ses (0.1.0)
+      actionmailbox (>= 7.1.0)
+      aws-sdk-s3 (~> 1, >= 1.123.0)
+      aws-sdk-sns (~> 1, >= 1.61.0)
+    aws-eventstream (1.4.0)
+    aws-partitions (1.1198.0)
+    aws-sdk-core (3.240.0)
+      aws-eventstream (~> 1, >= 1.3.0)
+      aws-partitions (~> 1, >= 1.992.0)
+      aws-sigv4 (~> 1.9)
+      base64
+      bigdecimal
       jmespath (~> 1, >= 1.6.1)
-    aws-sdk-kms (1.64.0)
-      aws-sdk-core (~> 3, >= 3.165.0)
-      aws-sigv4 (~> 1.1)
-    aws-sdk-s3 (1.122.0)
-      aws-sdk-core (~> 3, >= 3.165.0)
+      logger
+    aws-sdk-kms (1.118.0)
+      aws-sdk-core (~> 3, >= 3.239.1)
+      aws-sigv4 (~> 1.5)
+    aws-sdk-s3 (1.208.0)
+      aws-sdk-core (~> 3, >= 3.234.0)
       aws-sdk-kms (~> 1)
-      aws-sigv4 (~> 1.4)
-    aws-sigv4 (1.5.2)
+      aws-sigv4 (~> 1.5)
+    aws-sdk-sns (1.70.0)
+      aws-sdk-core (~> 3, >= 3.188.0)
+      aws-sigv4 (~> 1.1)
+    aws-sigv4 (1.12.1)
       aws-eventstream (~> 1, >= 1.0.2)
     barnes (0.0.9)
       multi_json (~> 1)
       statsd-ruby (~> 1.1)
     base64 (0.3.0)
-    bcrypt (3.1.20)
+    bcrypt (3.1.22)
     benchmark (0.4.1)
-    bigdecimal (3.2.2)
+    bigdecimal (4.1.2)
     bindex (0.8.1)
     bootsnap (1.16.0)
       msgpack (~> 1.2)
@@ -174,17 +186,22 @@ GEM
       bundler (>= 1.2.0, < 3)
       thor (~> 1.0)
     byebug (11.1.3)
+    cgi (0.5.1)
     childprocess (5.1.0)
       logger (~> 1.5)
+    cld3 (3.7.0)
     climate_control (1.2.0)
     coderay (1.1.3)
     commonmarker (0.23.10)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
+    concurrent-ruby (1.3.7)
+    connection_pool (2.5.5)
     crack (1.0.0)
       bigdecimal
       rexml
     crass (1.0.6)
+    cronex (0.15.0)
+      tzinfo
+      unicode (>= 0.4.4.5)
     csv (3.3.0)
     csv-safe (3.3.1)
       csv (~> 3.0)
@@ -201,7 +218,7 @@ GEM
       logger
       msgpack
     datadog-ruby_core_source (3.4.1)
-    date (3.4.1)
+    date (3.5.1)
     debug (1.8.0)
       irb (>= 1.5.0)
       reline (>= 0.3.1)
@@ -212,6 +229,11 @@ GEM
       railties (>= 4.1.0)
       responders
       warden (~> 1.2.3)
+    devise-two-factor (6.1.0)
+      activesupport (>= 7.0, < 8.1)
+      devise (~> 4.0)
+      railties (>= 7.0, < 8.1)
+      rotp (~> 6.0)
     devise_token_auth (1.2.5)
       bcrypt (~> 3.0)
       devise (> 3.5.2, < 5)
@@ -219,7 +241,7 @@ GEM
     diff-lcs (1.5.1)
     digest-crc (0.6.5)
       rake (>= 12.0.0, < 14.0.0)
-    docile (1.4.0)
+    docile (1.4.1)
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
     dotenv (3.1.2)
@@ -230,12 +252,42 @@ GEM
       addressable (~> 2.8)
     drb (2.2.3)
     dry-cli (1.1.0)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.14.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.5)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
     ecma-re-validator (0.4.0)
       regexp_parser (~> 2.2)
     elastic-apm (4.6.2)
       concurrent-ruby (~> 1.0)
       http (>= 3.0)
       ruby2_keywords
+    email-provider-info (0.0.1)
     email_reply_trimmer (0.1.13)
     erubi (1.13.0)
     et-orbi (1.2.11)
@@ -252,22 +304,34 @@ GEM
       railties (>= 5.0.0)
     faker (3.2.0)
       i18n (>= 1.8.11, < 2)
-    faraday (2.9.0)
-      faraday-net_http (>= 2.0, < 3.2)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
     faraday-follow_redirects (0.3.0)
       faraday (>= 1, < 3)
-    faraday-mashify (0.1.1)
+    faraday-mashify (1.0.0)
       faraday (~> 2.0)
       hashie
-    faraday-multipart (1.0.4)
-      multipart-post (~> 2)
-    faraday-net_http (3.1.0)
-      net-http
+    faraday-multipart (1.2.0)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
     faraday-net_http_persistent (2.1.0)
       faraday (~> 2.5)
       net-http-persistent (~> 4.0)
-    faraday-retry (2.2.1)
+    faraday-retry (2.4.0)
       faraday (~> 2.0)
+    faraday_middleware-aws-sigv4 (1.0.1)
+      aws-sigv4 (~> 1.0)
+      faraday (>= 2.0, < 3)
+    fast-mcp (1.5.0)
+      addressable (~> 2.8)
+      base64
+      dry-schema (~> 1.14)
+      json (~> 2.0)
+      mime-types (~> 3.4)
+      rack (~> 3.1)
     fcm (1.0.8)
       faraday (>= 1.0.0, < 3.0)
       googleauth (~> 1)
@@ -278,6 +342,7 @@ GEM
     ffi-compiler (1.0.1)
       ffi (>= 1.0.0)
       rake
+    firecrawl-sdk (1.4.1)
     flag_shih_tzu (0.3.23)
     foreman (0.87.2)
     fugit (1.11.1)
@@ -291,6 +356,7 @@ GEM
       googleapis-common-protos-types (>= 1.3.1, < 2.a)
       googleauth (~> 1.0)
       grpc (~> 1.36)
+    gemoji (4.1.0)
     geocoder (1.8.1)
     gli (2.22.2)
       ostruct
@@ -372,7 +438,8 @@ GEM
     hana (1.3.7)
     hash_diff (1.1.1)
     hashdiff (1.1.0)
-    hashie (5.0.0)
+    hashie (5.1.0)
+      logger
     html2text (0.4.0)
       nokogiri (>= 1.0, < 2.0)
     http (5.1.1)
@@ -384,7 +451,8 @@ GEM
     http-cookie (1.0.5)
       domain_name (~> 0.5)
     http-form_data (2.3.0)
-    httparty (0.21.0)
+    httparty (0.24.0)
+      csv
       mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
     httpclient (2.8.3)
@@ -406,7 +474,7 @@ GEM
       rails-dom-testing (>= 1, < 3)
       railties (>= 4.2.0)
       thor (>= 0.14, < 2.0)
-    json (2.12.0)
+    json (2.19.9)
     json_refs (0.1.8)
       hana
     json_schemer (0.2.24)
@@ -414,6 +482,12 @@ GEM
       hana (~> 1.3)
       regexp_parser (~> 2.0)
       uri_template (~> 0.7)
+    json_skooma (0.2.5)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      uri-idna (~> 0.2)
+      zeitwerk (~> 2.6)
     judoscale-rails (1.8.2)
       judoscale-ruby (= 1.8.2)
       railties
@@ -421,7 +495,7 @@ GEM
     judoscale-sidekiq (1.8.2)
       judoscale-ruby (= 1.8.2)
       sidekiq (>= 5.0)
-    jwt (2.8.1)
+    jwt (2.10.3)
       base64
     kaminari (1.2.2)
       activesupport (>= 4.1.0)
@@ -481,11 +555,11 @@ GEM
       net-imap
       net-pop
       net-smtp
-    marcel (1.0.4)
+    marcel (1.1.0)
     maxminddb (0.1.22)
-    meta_request (0.8.3)
+    meta_request (0.8.5)
       rack-contrib (>= 1.1, < 3)
-      railties (>= 3.0.0, < 8)
+      railties (>= 3.0.0, < 9)
     method_source (1.1.0)
     mime-types (3.4.1)
       mime-types-data (~> 3.2015)
@@ -498,16 +572,17 @@ GEM
       ruby2_keywords
     msgpack (1.8.0)
     multi_json (1.15.0)
-    multi_xml (0.6.0)
-    multipart-post (2.3.0)
+    multi_xml (0.9.1)
+      bigdecimal (>= 3.1, < 5)
+    multipart-post (2.4.1)
     mutex_m (0.3.0)
     neighbor (0.2.3)
       activerecord (>= 5.2)
-    net-http (0.4.1)
-      uri
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     net-http-persistent (4.0.2)
       connection_pool (~> 2.2)
-    net-imap (0.4.20)
+    net-imap (0.6.4.1)
       date
       net-protocol
     net-pop (0.1.2)
@@ -522,34 +597,42 @@ GEM
       sidekiq
     newrelic_rpm (9.6.0)
       base64
-    nio4r (2.7.3)
-    nokogiri (1.18.9)
+    nio4r (2.7.5)
+    nokogiri (1.19.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.18.9-arm64-darwin)
+    nokogiri (1.19.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.9-x86_64-darwin)
+    nokogiri (1.19.4-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.9-x86_64-linux-gnu)
+    nokogiri (1.19.4-x86_64-linux-gnu)
       racc (~> 1.4)
-    oauth (1.1.0)
-      oauth-tty (~> 1.0, >= 1.0.1)
-      snaky_hash (~> 2.0)
-      version_gem (~> 1.1)
-    oauth-tty (1.0.5)
-      version_gem (~> 1.1, >= 1.1.1)
-    oauth2 (2.0.9)
-      faraday (>= 0.17.3, < 3.0)
-      jwt (>= 1.0, < 3.0)
+    oauth (1.1.6)
+      auth-sanitizer (~> 0.2, >= 0.2.1)
+      base64 (~> 0.1)
+      cgi
+      oauth-tty (~> 1.0, >= 1.0.8)
+      snaky_hash (~> 2.0, >= 2.0.5)
+      version_gem (~> 1.1, >= 1.1.11)
+    oauth-tty (1.0.8)
+      auth-sanitizer (~> 0.1, >= 0.1.3)
+      cgi
+      version_gem (~> 1.1, >= 1.1.9)
+    oauth2 (2.0.22)
+      auth-sanitizer (~> 0.2, >= 0.2.1)
+      faraday (>= 0.17.3, < 4.0)
+      jwt (>= 1.0, < 4.0)
+      logger (~> 1.2)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 4)
-      snaky_hash (~> 2.0)
-      version_gem (~> 1.1)
-    oj (3.16.10)
+      snaky_hash (~> 2.0, >= 2.0.5)
+      version_gem (~> 1.1, >= 1.1.11)
+    oj (3.17.3)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
-    omniauth (2.1.2)
+    omniauth (2.1.4)
       hashie (>= 3.4.6)
+      logger
       rack (>= 2.2.3)
       rack-protection
     omniauth-google-oauth2 (1.1.3)
@@ -563,10 +646,35 @@ GEM
     omniauth-rails_csrf_protection (1.0.2)
       actionpack (>= 4.2)
       omniauth (~> 2.0)
+    omniauth-saml (2.2.4)
+      omniauth (~> 2.1)
+      ruby-saml (~> 1.18)
+    opensearch-ruby (3.4.0)
+      faraday (>= 1.0, < 3)
+      multi_json (>= 1.0)
     openssl (3.2.0)
+    opentelemetry-api (1.7.0)
+    opentelemetry-common (0.23.0)
+      opentelemetry-api (~> 1.0)
+    opentelemetry-exporter-otlp (0.31.1)
+      google-protobuf (>= 3.18)
+      googleapis-common-protos-types (~> 1.3)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-sdk (~> 1.10)
+      opentelemetry-semantic_conventions
+    opentelemetry-registry (0.4.0)
+      opentelemetry-api (~> 1.1)
+    opentelemetry-sdk (1.10.0)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-registry (~> 0.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-semantic_conventions (1.36.0)
+      opentelemetry-api (~> 1.0)
     orm_adapter (0.5.0)
     os (1.1.4)
-    ostruct (0.6.1)
+    ostruct (0.6.3)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
@@ -584,14 +692,14 @@ GEM
       method_source (~> 1.0)
     pry-rails (0.3.9)
       pry (>= 0.10.4)
-    public_suffix (6.0.2)
-    puma (6.4.3)
+    public_suffix (7.0.5)
+    puma (7.2.1)
       nio4r (~> 2.0)
     pundit (2.3.0)
       activesupport (>= 3.0.0)
     raabro (1.4.0)
     racc (1.8.1)
-    rack (2.2.15)
+    rack (3.2.6)
     rack-attack (6.7.0)
       rack (>= 1.0, < 4)
     rack-contrib (2.5.0)
@@ -600,19 +708,20 @@ GEM
       rack (>= 2.0.0)
     rack-mini-profiler (3.2.0)
       rack (>= 1.2.0)
-    rack-protection (3.2.0)
+    rack-protection (4.2.1)
       base64 (>= 0.1.0)
-      rack (~> 2.2, >= 2.2.4)
+      logger (>= 1.6.0)
+      rack (>= 3.0.0, < 4)
     rack-proxy (0.7.7)
       rack
-    rack-session (1.0.2)
-      rack (< 3)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
     rack-test (2.1.0)
       rack (>= 1.3)
     rack-timeout (0.6.3)
-    rackup (1.0.1)
-      rack (< 3)
-      webrick
+    rackup (2.2.1)
+      rack (>= 3)
     rails (7.1.5.2)
       actioncable (= 7.1.5.2)
       actionmailbox (= 7.1.5.2)
@@ -634,6 +743,9 @@ GEM
     rails-html-sanitizer (1.6.1)
       loofah (~> 2.21)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    rails-i18n (7.0.10)
+      i18n (>= 0.7, < 2)
+      railties (>= 6.0.0, < 8)
     railties (7.1.5.2)
       actionpack (= 7.1.5.2)
       activesupport (= 7.1.5.2)
@@ -649,7 +761,7 @@ GEM
       ffi (~> 1.0)
     redis (5.0.6)
       redis-client (>= 0.9.0)
-    redis-client (0.22.2)
+    redis-client (0.26.4)
       connection_pool
     redis-namespace (1.10.0)
       redis (>= 4)
@@ -673,7 +785,8 @@ GEM
     retriable (3.1.2)
     reverse_markdown (2.1.1)
       nokogiri
-    rexml (3.4.1)
+    rexml (3.4.4)
+    rotp (6.3.0)
     rspec-core (3.13.0)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.2)
@@ -728,22 +841,26 @@ GEM
       faraday (>= 1)
       faraday-multipart (>= 1)
     ruby-progressbar (1.13.0)
+    ruby-saml (1.18.1)
+      nokogiri (>= 1.13.10)
+      rexml
     ruby-vips (2.1.4)
       ffi (~> 1.12)
     ruby2_keywords (0.0.5)
     ruby2ruby (2.5.0)
       ruby_parser (~> 3.1)
       sexp_processor (~> 4.6)
-    ruby_llm (1.5.1)
+    ruby_llm (1.15.0)
       base64
       event_stream_parser (~> 1)
       faraday (>= 1.10.0)
       faraday-multipart (>= 1)
       faraday-net_http (>= 1)
       faraday-retry (>= 1)
-      marcel (~> 1.0)
+      marcel (~> 1)
+      ruby_llm-schema (~> 0)
       zeitwerk (~> 2)
-    ruby_llm-schema (0.1.0)
+    ruby_llm-schema (0.3.0)
     ruby_parser (3.20.0)
       sexp_processor (~> 4.16)
     sass (3.7.4)
@@ -763,6 +880,9 @@ GEM
       parser
     scss_lint (0.60.0)
       sass (~> 3.5, >= 3.5.5)
+    searchkick (5.5.2)
+      activemodel (>= 7.1)
+      hashie
     securerandom (0.4.1)
     seed_dump (3.3.1)
       activerecord (>= 4)
@@ -797,10 +917,11 @@ GEM
       logger
       rack (>= 2.2.4)
       redis-client (>= 0.22.2)
-    sidekiq-cron (1.12.0)
-      fugit (~> 1.8)
+    sidekiq-cron (2.4.0)
+      cronex (>= 0.13.0)
+      fugit (~> 1.8, >= 1.11.1)
       globalid (>= 1.0.1)
-      sidekiq (>= 6)
+      sidekiq (>= 6.5.0)
     sidekiq_alive (2.5.0)
       gserver (~> 0.0.1)
       sidekiq (>= 5, < 9)
@@ -809,21 +930,25 @@ GEM
       faraday (>= 0.17.5, < 3.a)
       jwt (>= 1.5, < 3.0)
       multi_json (~> 1.10)
-    simplecov (0.17.1)
+    simplecov (0.22.0)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    slack-ruby-client (2.5.2)
-      faraday (>= 2.0)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    skooma (0.3.7)
+      json_skooma (~> 0.2.5)
+      zeitwerk (~> 2.6)
+    slack-ruby-client (2.7.0)
+      faraday (>= 2.0.1)
       faraday-mashify
       faraday-multipart
       gli
       hashie
       logger
-    snaky_hash (2.0.1)
-      hashie
-      version_gem (~> 1.1, >= 1.1.1)
+    snaky_hash (2.0.5)
+      hashie (>= 0.1.0, < 6)
+      version_gem (>= 1.1.8, < 3)
     sorbet-runtime (0.5.11934)
     spring (4.1.1)
     spring-watcher-listen (2.1.0)
@@ -837,19 +962,24 @@ GEM
       activesupport (>= 5.2)
       sprockets (>= 3.0.0)
     squasher (0.7.2)
+    ssrf_filter (1.5.0)
     stackprof (0.2.25)
     statsd-ruby (1.5.0)
-    stripe (8.5.0)
+    stripe (18.0.1)
     telephone_number (1.4.20)
     test-prof (1.2.1)
     thor (1.4.0)
+    tidewave (0.2.0)
+      fast-mcp (~> 1.5.0)
+      rack (>= 2.0)
+      rails (>= 7.1.0)
     tilt (2.3.0)
     time_diff (0.3.0)
       activesupport
       i18n
-    timeout (0.4.3)
+    timeout (0.6.1)
     trailblazer-option (0.1.2)
-    twilio-ruby (5.77.0)
+    twilio-ruby (7.6.0)
       faraday (>= 0.9, < 3.0)
       jwt (>= 1.5, < 3.0)
       nokogiri (>= 1.6, < 2.0)
@@ -865,21 +995,25 @@ GEM
     unf (0.1.4)
       unf_ext
     unf_ext (0.0.8.2)
+    unicode (0.4.4.5)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
     uniform_notifier (1.17.0)
-    uri (1.0.3)
+    uri (1.1.1)
+    uri-idna (0.3.1)
     uri_template (0.7.0)
     valid_email2 (5.2.6)
       activemodel (>= 3.2)
       mail (~> 2.5)
-    version_gem (1.1.4)
-    vite_rails (3.0.17)
-      railties (>= 5.1, < 8)
+    version_gem (1.1.11)
+    vite_rails (3.10.0)
+      railties (>= 5.1, < 9)
       vite_ruby (~> 3.0, >= 3.2.2)
-    vite_ruby (3.8.0)
+    vite_ruby (3.10.2)
       dry-cli (>= 0.7, < 2)
+      logger (~> 1.6)
+      mutex_m
       rack-proxy (~> 0.6, >= 0.6.1)
       zeitwerk (~> 2.2)
     warden (1.2.9)
@@ -896,7 +1030,6 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    webrick (1.9.1)
     websocket-driver (0.7.7)
       base64
       websocket-extensions (>= 0.1.0)
@@ -905,7 +1038,7 @@ GEM
     working_hours (1.4.1)
       activesupport (>= 3.2)
       tzinfo
-    zeitwerk (2.6.17)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   arm64-darwin-20
@@ -925,10 +1058,11 @@ DEPENDENCIES
   administrate (>= 0.20.1)
   administrate-field-active_storage (>= 1.0.3)
   administrate-field-belongs_to_search (>= 0.9.0)
-  ai-agents (>= 0.4.3)
-  annotate
+  ai-agents (>= 0.10.0)
+  annotaterb
   attr_extras
   audited (~> 5.4, >= 5.4.1)
+  aws-actionmailbox-ses (~> 0)
   aws-sdk-s3
   azure-storage-blob!
   barnes
@@ -938,6 +1072,7 @@ DEPENDENCIES
   bullet
   bundle-audit
   byebug
+  cld3 (~> 3.7)
   climate_control
   commonmarker
   csv-safe
@@ -946,17 +1081,22 @@ DEPENDENCIES
   debug (~> 1.8)
   devise (>= 4.9.4)
   devise-secure_password!
+  devise-two-factor (>= 5.0.0)
   devise_token_auth (>= 1.2.3)
   dotenv-rails (>= 3.0.0)
   down
   elastic-apm
+  email-provider-info
   email_reply_trimmer
   facebook-messenger
   factory_bot_rails (>= 6.4.3)
   faker
+  faraday_middleware-aws-sigv4
   fcm
+  firecrawl-sdk (~> 1.0)
   flag_shih_tzu
   foreman
+  gemoji
   geocoder
   gmail_xoauth
   google-cloud-dialogflow-v2 (>= 0.24.0)
@@ -975,7 +1115,7 @@ DEPENDENCIES
   json_schemer
   judoscale-rails
   judoscale-sidekiq
-  jwt
+  jwt (~> 2.10, >= 2.10.3)
   kaminari
   koala
   letter_opener
@@ -994,18 +1134,23 @@ DEPENDENCIES
   omniauth-google-oauth2 (>= 1.1.3)
   omniauth-oauth2
   omniauth-rails_csrf_protection (~> 1.0, >= 1.0.2)
+  omniauth-saml
+  opensearch-ruby
+  opentelemetry-exporter-otlp
+  opentelemetry-sdk
   pg
   pg_search
   pgvector
   procore-sift
   pry-rails
-  puma
+  puma (~> 7.2, >= 7.2.1)
   pundit
   rack-attack (>= 6.7.0)
   rack-cors (= 2.0.0)
   rack-mini-profiler (>= 3.2.0)
   rack-timeout
   rails (~> 7.1)
+  rails-i18n (~> 7.0)
   redis
   redis-namespace
   responders (>= 3.1.1)
@@ -1019,29 +1164,35 @@ DEPENDENCIES
   rubocop-rails
   rubocop-rspec
   ruby-openai
+  ruby_llm (>= 1.14.1)
   ruby_llm-schema
   scout_apm
   scss_lint
+  searchkick
   seed_dump
   sentry-rails (>= 5.19.0)
   sentry-ruby
   sentry-sidekiq (>= 5.19.0)
   shopify_api
   shoulda-matchers
-  sidekiq (>= 7.3.1)
-  sidekiq-cron (>= 1.12.0)
+  sidekiq (~> 7.3, >= 7.3.1)
+  sidekiq-cron (>= 2.4.0)
   sidekiq_alive
-  simplecov (= 0.17.1)
-  slack-ruby-client (~> 2.5.2)
+  simplecov (>= 0.21)
+  simplecov_json_formatter
+  skooma
+  slack-ruby-client (~> 2.7.0)
   spring
   spring-watcher-listen
   squasher
+  ssrf_filter (~> 1.5)
   stackprof
-  stripe
+  stripe (~> 18.0)
   telephone_number
   test-prof
+  tidewave
   time_diff
-  twilio-ruby (~> 5.66)
+  twilio-ruby
   twitty (~> 0.1.5)
   tzinfo-data
   uglifier

Makefile

@@ -40,8 +40,12 @@ run:
 	fi
 
 force_run:
-	rm -f ./.overmind.sock
-	rm -f tmp/pids/*.pid
+	@echo "Cleaning up Overmind processes..."
+	@lsof -ti:3036 2>/dev/null | xargs kill -9 2>/dev/null || true
+	@lsof -ti:3000 2>/dev/null | xargs kill -9 2>/dev/null || true
+	@rm -f ./.overmind.sock
+	@rm -f tmp/pids/*.pid
+	@echo "Cleanup complete"
 	overmind start -f Procfile.dev
 
 force_run_tunnel:

README.md

@@ -8,7 +8,6 @@ ___
 The modern customer support platform, an open-source alternative to Intercom, Zendesk, Salesforce Service Cloud etc.
 
 <p>
-  <a href="https://codeclimate.com/github/chatwoot/chatwoot/maintainability"><img src="https://api.codeclimate.com/v1/badges/e6e3f66332c91e5a4c0c/maintainability" alt="Maintainability"></a>
   <img src="https://img.shields.io/circleci/build/github/chatwoot/chatwoot" alt="CircleCI Badge">
     <a href="https://hub.docker.com/r/chatwoot/chatwoot/"><img src="https://img.shields.io/docker/pulls/chatwoot/chatwoot" alt="Docker Pull Badge"></a>
   <a href="https://hub.docker.com/r/chatwoot/chatwoot/"><img src="https://img.shields.io/docker/cloud/build/chatwoot/chatwoot" alt="Docker Build Badge"></a>
@@ -137,4 +136,4 @@ Thanks goes to all these [wonderful people](https://www.chatwoot.com/docs/contri
 <a href="https://github.com/chatwoot/chatwoot/graphs/contributors"><img src="https://opencollective.com/chatwoot/contributors.svg?width=890&button=false" /></a>
 
 
-*Chatwoot* &copy; 2017-2025, Chatwoot Inc - Released under the MIT License.
+*Chatwoot* &copy; 2017-2026, Chatwoot Inc - Released under the MIT License.

Rakefile

@@ -2,5 +2,8 @@
 # for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
 
 require_relative 'config/application'
+# Load Enterprise Edition rake tasks if they exist
+enterprise_tasks_path = Rails.root.join('enterprise/tasks_railtie.rb').to_s
+require enterprise_tasks_path if File.exist?(enterprise_tasks_path)
 
 Rails.application.load_tasks

VERSION_CW

@@ -1 +1 @@
-4.4.0
+4.15.1

VERSION_CWCTL

@@ -1 +1 @@
-3.4.2
+3.5.0

app.json

@@ -36,6 +36,10 @@
     "REDIS_OPENSSL_VERIFY_MODE":{
       "description": "OpenSSL verification mode for Redis connections. ref https://help.heroku.com/HC0F8CUS/redis-connection-issues",
       "value": "none"
+    },
+    "NODE_OPTIONS": {
+      "description": "Increase V8 heap for Vite build to avoid OOM",
+      "value": "--max-old-space-size=4096"
     }
   },
   "formation": {

app/actions/contact_identify_action.rb

@@ -104,7 +104,7 @@ class ContactIdentifyAction
     # 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!
+    @contact.save! if @contact.changed?
     enqueue_avatar_job
   end
 

app/builders/account_builder.rb

@@ -44,7 +44,11 @@ class AccountBuilder
   end
 
   def create_account
-    @account = Account.create!(name: account_name, locale: I18n.locale)
+    @account = Account.create!(
+      name: account_name,
+      locale: I18n.locale,
+      custom_attributes: { 'onboarding_step' => 'account_details' }
+    )
     Current.account = @account
   end
 

app/builders/agent_builder.rb

@@ -29,8 +29,9 @@ class AgentBuilder
     user = User.from_email(email)
     return user if user
 
+    @name = email.split('@').first if @name.blank?
     temp_password = "1!aA#{SecureRandom.alphanumeric(12)}"
-    User.create!(email: email, name: name, password: temp_password, password_confirmation: temp_password)
+    User.create!(email: email, name: @name, password: temp_password, password_confirmation: temp_password)
   end
 
   # Checks if the user needs confirmation.
@@ -52,3 +53,5 @@ class AgentBuilder
     }.compact))
   end
 end
+
+AgentBuilder.prepend_mod_with('AgentBuilder')

app/builders/contact_inbox_builder.rb

@@ -103,3 +103,5 @@ class ContactInboxBuilder
     @inbox.email? || @inbox.sms? || @inbox.twilio? || @inbox.whatsapp?
   end
 end
+
+ContactInboxBuilder.prepend_mod_with('ContactInboxBuilder')

app/builders/contact_inbox_with_contact_builder.rb

@@ -50,7 +50,7 @@ class ContactInboxWithContactBuilder
 
   def create_contact
     account.contacts.create!(
-      name: contact_attributes[:name] || ::Haikunator.haikunate(1000),
+      name: contact_name,
       phone_number: contact_attributes[:phone_number],
       email: contact_attributes[:email],
       identifier: contact_attributes[:identifier],
@@ -59,6 +59,11 @@ class ContactInboxWithContactBuilder
     )
   end
 
+  def contact_name
+    name = contact_attributes[:name] || ::Haikunator.haikunate(1000)
+    name.truncate(ApplicationRecord::MAX_STRING_COLUMN_LENGTH, omission: '')
+  end
+
   def find_contact
     contact = find_contact_by_identifier(contact_attributes[:identifier])
     contact ||= find_contact_by_email(contact_attributes[:email])

app/builders/email/base_builder.rb

@@ -0,0 +1,52 @@
+class Email::BaseBuilder
+  include EmailAddressParseable
+
+  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.sanitized_business_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
+end

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

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

app/builders/messages/facebook/message_builder.rb

@@ -92,10 +92,18 @@ class Messages::Facebook::MessageBuilder < Messages::Messenger::MessageBuilder
   def fallback_params(attachment)
     {
       fallback_title: attachment['title'],
-      external_url: attachment['url']
+      external_url: attachment['url'] || attachment.dig('payload', 'url')
     }
   end
 
+  # Facebook shared posts point to page URLs, not downloadable media URLs.
+  # Keep this Facebook-only so Messenger/Instagram share attachments still use the parent media handling.
+  def normalize_file_type(type)
+    return :fallback if type.to_sym == :share
+
+    super
+  end
+
   def conversation_params
     {
       account_id: @inbox.account_id,
@@ -105,15 +113,19 @@ class Messages::Facebook::MessageBuilder < Messages::Messenger::MessageBuilder
   end
 
   def message_params
+    content_attributes = {
+      in_reply_to_external_id: response.in_reply_to_external_id
+    }
+    content_attributes[:external_echo] = true if @outgoing_echo
+
     {
       account_id: conversation.account_id,
       inbox_id: conversation.inbox_id,
       message_type: @message_type,
+      status: @outgoing_echo ? :delivered : :sent,
       content: response.content,
       source_id: response.identifier,
-      content_attributes: {
-        in_reply_to_external_id: response.in_reply_to_external_id
-      },
+      content_attributes: content_attributes,
       sender: @outgoing_echo ? nil : @contact_inbox.contact
     }
   end

app/builders/messages/instagram/base_message_builder.rb

@@ -112,6 +112,25 @@ class Messages::Instagram::BaseMessageBuilder < Messages::Messenger::MessageBuil
     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
@@ -139,6 +158,7 @@ class Messages::Instagram::BaseMessageBuilder < Messages::Messenger::MessageBuil
       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,
@@ -147,6 +167,7 @@ class Messages::Instagram::BaseMessageBuilder < Messages::Messenger::MessageBuil
       }
     }
 
+    params[:content_attributes][:external_echo] = true if @outgoing_echo
     params[:content_attributes][:is_unsupported] = true if message_is_unsupported?
     params
   end

app/builders/messages/message_builder.rb

@@ -1,5 +1,8 @@
 class Messages::MessageBuilder
   include ::FileTypeHelper
+  include ::EmailHelper
+  include ::DataHelper
+
   attr_reader :message
 
   def initialize(user, conversation, params)
@@ -7,8 +10,10 @@ class Messages::MessageBuilder
     @private = params[:private] || false
     @conversation = conversation
     @user = user
+    @account = conversation.account
     @message_type = params[:message_type] || 'outgoing'
     @attachments = params[:attachments]
+    @is_voice_message = ActiveModel::Type::Boolean.new.cast(params[:is_voice_message])
     @automation_rule = content_attributes&.dig(:automation_rule_id)
     return unless params.instance_of?(ActionController::Parameters)
 
@@ -20,6 +25,9 @@ class Messages::MessageBuilder
     @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
@@ -34,30 +42,12 @@ class Messages::MessageBuilder
     params = convert_to_hash(@params)
     content_attributes = params.fetch(:content_attributes, {})
 
-    return parse_json(content_attributes) if content_attributes.is_a?(String)
+    return safe_parse_json(content_attributes) if content_attributes.is_a?(String)
     return content_attributes if content_attributes.is_a?(Hash)
 
     {}
   end
 
-  # Converts the given object to a hash.
-  # If it's an instance of ActionController::Parameters, converts it to an unsafe hash.
-  # Otherwise, returns the object as-is.
-  def convert_to_hash(obj)
-    return obj.to_unsafe_h if obj.instance_of?(ActionController::Parameters)
-
-    obj
-  end
-
-  # Attempts to parse a string as JSON.
-  # If successful, returns the parsed hash with symbolized names.
-  # If unsuccessful, returns nil.
-  def parse_json(content)
-    JSON.parse(content, symbolize_names: true)
-  rescue JSON::ParserError
-    {}
-  end
-
   def process_attachments
     return if @attachments.blank?
 
@@ -67,16 +57,25 @@ class Messages::MessageBuilder
         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
+      attachment.file_type = attachment_file_type(uploaded_attachment)
+      tag_voice_message(attachment)
     end
   end
 
+  def attachment_file_type(uploaded_attachment)
+    if uploaded_attachment.is_a?(String)
+      file_type_by_signed_id(uploaded_attachment)
+    else
+      file_type(uploaded_attachment&.content_type)
+    end
+  end
+
+  def tag_voice_message(attachment)
+    return unless @is_voice_message && attachment.file_type == 'audio'
+
+    attachment.meta = (attachment.meta || {}).merge('is_voice_message' => true)
+  end
+
   def process_emails
     return unless @conversation.inbox&.inbox_type == 'Email'
 
@@ -92,18 +91,20 @@ class Messages::MessageBuilder
     @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 validate_email_addresses(all_emails)
-    all_emails&.each do |email|
-      raise StandardError, 'Invalid email address' unless email.match?(URI::MailTo::EMAIL_REGEXP)
-    end
-  end
-
   def message_type
     if @conversation.inbox.channel_type != 'Channel::Api' && @message_type == 'incoming'
       raise StandardError, 'Incoming messages are only allowed in Api inboxes'
@@ -147,10 +148,90 @@ class Messages::MessageBuilder
       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')

app/builders/messages/messenger/message_builder.rb

@@ -2,16 +2,32 @@ 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
+    # This check handles very rare case if there are multiple files to attach with only one unsupported file
     return if unsupported_file_type?(attachment['type'])
 
-    attachment_obj = @message.attachments.new(attachment_params(attachment).except(:remote_file_url))
+    params = attachment_params(attachment)
+    # During Meta's sticker webhook transition, a sticker message carries both an `image`
+    # and a `sticker` attachment pointing to the same URL. Skip the redundant sticker so it
+    # isn't attached twice, while still storing legitimate duplicate attachments of other types.
+    return if duplicate_sticker?(attachment, params[:external_url])
+
+    attachment_obj = @message.attachments.new(params.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'
+    if facebook_reel?(attachment)
+      update_facebook_reel_content(attachment)
+    elsif params[:remote_file_url]
+      attach_file(attachment_obj, params[:remote_file_url])
+    end
+    fetch_attachment_links(attachment_obj)
     update_attachment_file_type(attachment_obj)
   end
 
+  def fetch_attachment_links(attachment_obj)
+    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'
+  end
+
   def attach_file(attachment, file_url)
     attachment_file = Down.download(
       file_url
@@ -21,13 +37,17 @@ class Messages::Messenger::MessageBuilder
       filename: attachment_file.original_filename,
       content_type: attachment_file.content_type
     )
+    # The Attachment row is saved before the blob is attached, so the
+    # after_create_commit broadcast bails on `file.attached?`. Re-fire here
+    # for audio so the bubble updates without waiting on transcription.
+    attachment.message&.reload&.send_update_event if attachment.file_type.to_sym == :audio
   end
 
   def attachment_params(attachment)
-    file_type = attachment['type'].to_sym
+    file_type = normalize_file_type(attachment['type'])
     params = { file_type: file_type, account_id: @message.account_id }
 
-    if [:image, :file, :audio, :video, :share, :story_mention, :ig_reel].include? file_type
+    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))
@@ -39,9 +59,17 @@ class Messages::Messenger::MessageBuilder
   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: attachment['payload']['url'],
-      remote_file_url: attachment['payload']['url']
+      external_url: url,
+      remote_file_url: url
     }
   end
 
@@ -68,6 +96,21 @@ class Messages::Messenger::MessageBuilder
     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)
     {}
@@ -75,7 +118,36 @@ class Messages::Messenger::MessageBuilder
 
   private
 
+  # Facebook may send attachment types that don't directly match our file_type enum.
+  # Map known aliases to their canonical enum values.
+  FACEBOOK_FILE_TYPE_MAP = { reel: :ig_reel, sticker: :image }.freeze
+
+  def normalize_file_type(type)
+    sym = type.to_sym
+    FACEBOOK_FILE_TYPE_MAP.fetch(sym, sym)
+  end
+
+  def duplicate_sticker?(attachment, url)
+    return false unless attachment['type'].to_sym == :sticker
+    return false if url.blank?
+
+    @message.attachments.any? { |existing| existing.external_url == url }
+  end
+
+  # Facebook sends reel URLs as webpage links (facebook.com/reel/...) rather than
+  # direct video URLs. Downloading these yields HTML, not video content.
+  def facebook_reel?(attachment)
+    attachment['type'].to_sym == :reel
+  end
+
+  def update_facebook_reel_content(attachment)
+    url = attachment.dig('payload', 'url')
+    return if url.blank?
+
+    @message.update!(content: url) if @message.content.blank?
+  end
+
   def unsupported_file_type?(attachment_type)
-    [:template, :unsupported_type].include? attachment_type.to_sym
+    [:template, :unsupported_type, :ephemeral].include? attachment_type.to_sym
   end
 end

app/builders/notification_builder.rb

@@ -27,6 +27,8 @@ class NotificationBuilder
     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'
+    # respect conversation access (inbox/team membership and custom-role permissions)
+    return unless user_can_access_conversation?
 
     user.notifications.create!(
       notification_type: notification_type,
@@ -36,4 +38,17 @@ class NotificationBuilder
       secondary_actor: secondary_actor || current_user
     )
   end
+
+  def user_can_access_conversation?
+    conversation = primary_actor.is_a?(Conversation) ? primary_actor : primary_actor.try(:conversation)
+    return true if conversation.blank?
+
+    account_user = AccountUser.find_by(account_id: account.id, user_id: user.id)
+    return false if account_user.blank?
+
+    ConversationPolicy.new(
+      { user: user, account: account, account_user: account_user },
+      conversation
+    ).show?
+  end
 end

app/builders/v2/report_builder.rb

@@ -1,6 +1,7 @@
 class V2::ReportBuilder
   include DateRangeHelper
   include ReportHelper
+
   attr_reader :account, :params
 
   DEFAULT_GROUP_BY = 'day'.freeze

app/builders/v2/reports/agent_summary_builder.rb

@@ -11,10 +11,6 @@ class V2::Reports::AgentSummaryBuilder < V2::Reports::BaseSummaryBuilder
   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)

app/builders/v2/reports/base_summary_builder.rb

@@ -9,27 +9,13 @@ class V2::Reports::BaseSummaryBuilder
   private
 
   def load_data
-    @conversations_count = fetch_conversations_count
-    @resolved_count = fetch_resolved_count
-    @avg_resolution_time = fetch_average_time('conversation_resolved')
-    @avg_first_response_time = fetch_average_time('first_response')
-    @avg_reply_time = fetch_average_time('reply_time')
-  end
+    results = data_source.summary
 
-  def reporting_events
-    @reporting_events ||= account.reporting_events.where(created_at: range)
-  end
-
-  def fetch_conversations_count
-    # Override this method
-  end
-
-  def fetch_average_time(event_name)
-    get_grouped_average(reporting_events.where(name: event_name))
-  end
-
-  def fetch_resolved_count
-    reporting_events.where(name: 'conversation_resolved').group(group_by_key).count
+    @conversations_count = results.transform_values { |data| data[:conversations_count] }
+    @resolved_count = results.transform_values { |data| data[:resolved_conversations_count] }
+    @avg_resolution_time = results.transform_values { |data| data[:avg_resolution_time] }
+    @avg_first_response_time = results.transform_values { |data| data[:avg_first_response_time] }
+    @avg_reply_time = results.transform_values { |data| data[:avg_reply_time] }
   end
 
   def group_by_key
@@ -40,11 +26,26 @@ class V2::Reports::BaseSummaryBuilder
     # Override this method
   end
 
-  def get_grouped_average(events)
-    events.group(group_by_key).average(average_value_key)
+  def data_source
+    @data_source ||= Reports::DataSource.for(
+      account: account,
+      metric: nil,
+      dimension_type: summary_dimension_type,
+      dimension_id: nil,
+      scope: nil,
+      range: range,
+      group_by: 'day',
+      timezone_offset: params[:timezone_offset],
+      business_hours: params[:business_hours]
+    )
   end
 
-  def average_value_key
-    ActiveModel::Type::Boolean.new.cast(params[:business_hours]).present? ? :value_in_business_hours : :value
+  def summary_dimension_type
+    {
+      'account_id' => 'account',
+      'user_id' => 'agent',
+      'inbox_id' => 'inbox',
+      'conversations.team_id' => 'team'
+    }.fetch(group_by_key.to_s)
   end
 end

app/builders/v2/reports/bot_metrics_builder.rb

@@ -31,13 +31,24 @@ class V2::Reports::BotMetricsBuilder
   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
+    # Exclude conversations that also had a handoff in the same range — handoff wins
+    account.reporting_events.joins(:conversation).select(:conversation_id)
+           .where(account_id: account.id, name: :conversation_bot_resolved, created_at: range)
+           .where.not(conversation_id: bot_handoff_conversation_ids_subquery)
+           .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
+    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_handoff_conversation_ids_subquery
+    account.reporting_events
+           .where(name: :conversation_bot_handoff, created_at: range)
+           .where.not(conversation_id: nil)
+           .select(:conversation_id)
   end
 
   def bot_resolution_rate

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

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

@@ -3,23 +3,10 @@ class V2::Reports::Conversations::BaseReportBuilder
 
   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
+    return unless Reports::ReportMetricRegistry.supported?(metric)
+
+    V2::Reports::Timeseries::ReportBuilder
   end
 
   def log_invalid_metric

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

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

app/builders/v2/reports/inbox_summary_builder.rb

@@ -11,18 +11,6 @@ class V2::Reports::InboxSummaryBuilder < V2::Reports::BaseSummaryBuilder
   attr_reader :conversations_count, :resolved_count,
               :avg_resolution_time, :avg_first_response_time, :avg_reply_time
 
-  def load_data
-    @conversations_count = fetch_conversations_count
-    @resolved_count = fetch_resolved_count
-    @avg_resolution_time = fetch_average_time('conversation_resolved')
-    @avg_first_response_time = fetch_average_time('first_response')
-    @avg_reply_time = fetch_average_time('reply_time')
-  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)
@@ -43,8 +31,4 @@ class V2::Reports::InboxSummaryBuilder < V2::Reports::BaseSummaryBuilder
   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

app/builders/v2/reports/label_summary_builder.rb

@@ -28,7 +28,7 @@ class V2::Reports::LabelSummaryBuilder < V2::Reports::BaseSummaryBuilder
 
     {
       conversation_counts: fetch_conversation_counts(conversation_filter),
-      resolved_counts: fetch_resolved_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)
@@ -62,10 +62,21 @@ class V2::Reports::LabelSummaryBuilder < V2::Reports::BaseSummaryBuilder
     fetch_counts(conversation_filter)
   end
 
-  def fetch_resolved_counts(conversation_filter)
-    # since the base query is ActsAsTaggableOn,
-    # the status :resolved won't automatically be converted to integer status
-    fetch_counts(conversation_filter.merge(status: Conversation.statuses[:resolved]))
+  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)
@@ -84,9 +95,7 @@ class V2::Reports::LabelSummaryBuilder < V2::Reports::BaseSummaryBuilder
 
   def fetch_metrics(conversation_filter, event_name, use_business_hours)
     ReportingEvent
-      .joins('INNER JOIN conversations ON reporting_events.conversation_id = conversations.id')
-      .joins('INNER JOIN taggings ON taggings.taggable_id = conversations.id')
-      .joins('INNER JOIN tags ON taggings.tag_id = tags.id')
+      .joins(conversation: { taggings: :tag })
       .where(
         conversations: conversation_filter,
         name: event_name,

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

app/builders/v2/reports/team_summary_builder.rb

@@ -6,14 +6,6 @@ class V2::Reports::TeamSummaryBuilder < V2::Reports::BaseSummaryBuilder
   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)

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

@@ -1,48 +0,0 @@
-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

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

@@ -1,12 +1,13 @@
 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
+    case dimension_type.to_sym
     when :account
       account
     when :inbox
@@ -20,6 +21,20 @@ class V2::Reports::Timeseries::BaseTimeseriesBuilder
     end
   end
 
+  def data_source
+    @data_source ||= Reports::DataSource.for(
+      account: account,
+      metric: params[:metric],
+      dimension_type: dimension_type,
+      dimension_id: params[:id],
+      scope: scope,
+      range: range,
+      group_by: group_by,
+      timezone_offset: params[:timezone_offset],
+      business_hours: params[:business_hours]
+    )
+  end
+
   def inbox
     @inbox ||= account.inboxes.find(params[:id])
   end
@@ -43,4 +58,10 @@ class V2::Reports::Timeseries::BaseTimeseriesBuilder
   def timezone
     @timezone ||= timezone_name_from_offset(params[:timezone_offset])
   end
+
+  private
+
+  def dimension_type
+    (params[:type].presence || 'account').to_s
+  end
 end

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

@@ -1,71 +0,0 @@
-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.joins(:conversation).select(:conversation_id).where(
-      name: :conversation_resolved,
-      conversations: { status: :resolved }, created_at: range
-    ).distinct
-  end
-
-  def scope_for_bot_resolutions_count
-    scope.reporting_events.joins(:conversation).select(:conversation_id).where(
-      name: :conversation_bot_resolved,
-      conversations: { status: :resolved }, created_at: range
-    ).distinct
-  end
-
-  def scope_for_bot_handoffs_count
-    scope.reporting_events.joins(:conversation).select(:conversation_id).where(
-      name: :conversation_bot_handoff,
-      created_at: range
-    ).distinct
-  end
-
-  def grouped_count
-    @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

app/builders/v2/reports/timeseries/report_builder.rb

@@ -0,0 +1,9 @@
+class V2::Reports::Timeseries::ReportBuilder < V2::Reports::Timeseries::BaseTimeseriesBuilder
+  def timeseries
+    data_source.timeseries
+  end
+
+  def aggregate_value
+    data_source.aggregate
+  end
+end

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

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

@@ -4,7 +4,7 @@ class Api::V1::Accounts::AgentBotsController < Api::V1::Accounts::BaseController
   before_action :agent_bot, except: [:index, :create]
 
   def index
-    @agent_bots = AgentBot.where(account_id: [nil, Current.account.id])
+    @agent_bots = AgentBot.accessible_to(Current.account)
   end
 
   def show; end
@@ -34,10 +34,14 @@ class Api::V1::Accounts::AgentBotsController < Api::V1::Accounts::BaseController
     @agent_bot.reload
   end
 
+  def reset_secret
+    @agent_bot.reset_secret!
+  end
+
   private
 
   def agent_bot
-    @agent_bot = AgentBot.where(account_id: [nil, Current.account.id]).find(params[:id]) if params[:action] == 'show'
+    @agent_bot = AgentBot.accessible_to(Current.account).find(params[:id]) if params[:action] == 'show'
     @agent_bot ||= Current.account.agent_bots.find(params[:id])
   end
 

app/controllers/api/v1/accounts/articles/bulk_actions_controller.rb

@@ -0,0 +1,59 @@
+class Api::V1::Accounts::Articles::BulkActionsController < Api::V1::Accounts::BaseController
+  before_action :portal
+  before_action :check_authorization
+  before_action :set_articles, only: [:update_status, :update_category, :delete_articles]
+
+  def translate
+    head :not_implemented
+  end
+
+  def update_status
+    return render_could_not_create_error(I18n.t('portals.articles.no_articles_found')) if @articles.none?
+    return render_could_not_create_error(I18n.t('portals.articles.invalid_status')) unless Article.statuses.key?(params[:status])
+
+    ActiveRecord::Base.transaction do
+      @articles.find_each { |article| article.update!(status: params[:status]) }
+    end
+    head :ok
+  rescue ActiveRecord::RecordInvalid => e
+    render_could_not_create_error(e.message)
+  end
+
+  def update_category
+    return render_could_not_create_error(I18n.t('portals.articles.no_articles_found')) if @articles.none?
+    return render_could_not_create_error(I18n.t('portals.articles.category_not_found')) unless category_valid?
+
+    ActiveRecord::Base.transaction do
+      @articles.find_each { |article| article.update!(category_id: params[:category_id]) }
+    end
+    head :ok
+  rescue ActiveRecord::RecordInvalid => e
+    render_could_not_create_error(e.message)
+  end
+
+  def delete_articles
+    return render_could_not_create_error(I18n.t('portals.articles.no_articles_found')) if @articles.none?
+
+    @articles.destroy_all
+    head :ok
+  end
+
+  private
+
+  def portal
+    @portal ||= Current.account.portals.find_by!(slug: params[:portal_id])
+  end
+
+  def check_authorization
+    authorize(Article, :create?)
+  end
+
+  def set_articles
+    @articles = @portal.articles.where(id: params[:ids])
+  end
+
+  def category_valid?
+    @portal.categories.exists?(id: params[:category_id])
+  end
+end
+Api::V1::Accounts::Articles::BulkActionsController.prepend_mod_with('Api::V1::Accounts::Articles::BulkActionsController')

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

@@ -22,9 +22,10 @@ class Api::V1::Accounts::ArticlesController < Api::V1::Accounts::BaseController
   def edit; end
 
   def create
-    @article = @portal.articles.create!(article_params)
+    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])
-    @article.draft!
     render json: { error: @article.errors.messages }, status: :unprocessable_entity and return unless @article.valid?
   end
 
@@ -39,7 +40,7 @@ class Api::V1::Accounts::ArticlesController < Api::V1::Accounts::BaseController
   end
 
   def reorder
-    Article.update_positions(params[:positions_hash])
+    Article.update_positions(portal: @portal, positions_hash: params[:positions_hash])
     head :ok
   end
 

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

@@ -1,4 +1,6 @@
 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]
 
@@ -9,25 +11,32 @@ class Api::V1::Accounts::AutomationRulesController < Api::V1::Accounts::BaseCont
   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 = params[:actions]
+    @automation_rule.actions = actions
     @automation_rule.conditions = params[:conditions]
 
-    render json: { error: @automation_rule.errors.messages }, status: :unprocessable_entity and return unless @automation_rule.valid?
+    return render_could_not_create_error(@automation_rule.errors.messages) unless @automation_rule.valid?
 
     @automation_rule.save!
-    process_attachments
-    @automation_rule
+    blobs.each { |blob| @automation_rule.files.attach(blob) }
   end
 
   def update
-    ActiveRecord::Base.transaction do
-      automation_rule_update
-      process_attachments
+    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 json: { error: @automation_rule.errors.messages }.to_json, status: :unprocessable_entity
+      render_could_not_create_error(@automation_rule.errors.messages)
     end
   end
 
@@ -43,29 +52,11 @@ class Api::V1::Accounts::AutomationRulesController < Api::V1::Accounts::BaseCont
     @automation_rule = new_rule
   end
 
-  def process_attachments
-    actions = @automation_rule.actions.filter_map { |k, _v| k if k['action_name'] == 'send_attachment' }
-    return if actions.blank?
-
-    actions.each do |action|
-      blob_id = action['action_params']
-      blob = ActiveStorage::Blob.find_by(id: blob_id)
-      @automation_rule.files.attach(blob)
-    end
-  end
-
   private
 
-  def automation_rule_update
-    @automation_rule.update!(automation_rules_permit)
-    @automation_rule.actions = params[:actions] if params[:actions]
-    @automation_rule.conditions = params[:conditions] if params[:conditions]
-    @automation_rule.save!
-  end
-
   def automation_rules_permit
     params.permit(
-      :name, :description, :event_name, :account_id, :active,
+      :name, :description, :event_name, :active,
       conditions: [:attribute_key, :filter_operator, :query_operator, :custom_attribute_type, { values: [] }],
       actions: [:action_name, { action_params: [] }]
     )

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

@@ -1,13 +1,12 @@
 class Api::V1::Accounts::BulkActionsController < Api::V1::Accounts::BaseController
-  before_action :type_matches?
-
   def create
-    if type_matches?
-      ::BulkActionsJob.perform_later(
-        account: @current_account,
-        user: current_user,
-        params: permitted_params
-      )
+    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
@@ -16,11 +15,54 @@ class Api::V1::Accounts::BulkActionsController < Api::V1::Accounts::BaseControll
 
   private
 
-  def type_matches?
-    ['Conversation'].include?(params[:type])
+  def normalized_type
+    params[:type].to_s.camelize
   end
 
-  def permitted_params
-    params.permit(:type, :snoozed_until, ids: [], fields: [:status, :assignee_id, :team_id], labels: [add: [], remove: []])
+  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

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

app/controllers/api/v1/accounts/captain/tasks_controller.rb

@@ -0,0 +1,73 @@
+class Api::V1::Accounts::Captain::TasksController < Api::V1::Accounts::BaseController
+  before_action :check_authorization
+
+  def rewrite
+    result = Captain::RewriteService.new(
+      account: Current.account,
+      content: params[:content],
+      operation: params[:operation],
+      conversation_display_id: params[:conversation_display_id]
+    ).perform
+
+    render_result(result)
+  end
+
+  def summarize
+    result = Captain::SummaryService.new(
+      account: Current.account,
+      conversation_display_id: params[:conversation_display_id]
+    ).perform
+
+    render_result(result)
+  end
+
+  def reply_suggestion
+    result = Captain::ReplySuggestionService.new(
+      account: Current.account,
+      conversation_display_id: params[:conversation_display_id],
+      user: Current.user
+    ).perform
+
+    render_result(result)
+  end
+
+  def label_suggestion
+    result = Captain::LabelSuggestionService.new(
+      account: Current.account,
+      conversation_display_id: params[:conversation_display_id]
+    ).perform
+
+    render_result(result)
+  end
+
+  def follow_up
+    result = Captain::FollowUpService.new(
+      account: Current.account,
+      follow_up_context: params[:follow_up_context]&.to_unsafe_h,
+      user_message: params[:message],
+      conversation_display_id: params[:conversation_display_id]
+    ).perform
+
+    render_result(result)
+  end
+
+  private
+
+  def render_result(result)
+    if result.nil?
+      render json: { message: nil }
+    elsif result[:error]
+      render json: { error: result[:error] }, status: :unprocessable_content
+    else
+      response_data = { message: result[:message] }
+      response_data[:follow_up_context] = result[:follow_up_context] if result[:follow_up_context]
+      render json: response_data
+    end
+  end
+
+  def check_authorization
+    authorize(:'captain/tasks')
+  end
+end
+
+Api::V1::Accounts::Captain::TasksController.prepend_mod_with('Api::V1::Accounts::Captain::TasksController')

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

@@ -1,7 +1,7 @@
 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 :fetch_category, except: [:index, :create, :reorder]
   before_action :set_current_page, only: [:index]
 
   def index
@@ -32,6 +32,11 @@ class Api::V1::Accounts::CategoriesController < Api::V1::Accounts::BaseControlle
     head :ok
   end
 
+  def reorder
+    Category.update_positions(portal: @portal, positions_hash: params[:positions_hash])
+    head :ok
+  end
+
   private
 
   def fetch_category
@@ -39,7 +44,7 @@ class Api::V1::Accounts::CategoriesController < Api::V1::Accounts::BaseControlle
   end
 
   def portal
-    @portal ||= Current.account.portals.find_by(slug: params[:portal_id])
+    @portal ||= Current.account.portals.find_by!(slug: params[:portal_id])
   end
 
   def related_categories_records
@@ -48,7 +53,7 @@ class Api::V1::Accounts::CategoriesController < Api::V1::Accounts::BaseControlle
 
   def category_params
     params.require(:category).permit(
-      :name, :description, :position, :slug, :locale, :icon, :parent_category_id, :associated_category_id
+      :name, :description, :position, :slug, :locale, :icon, :icon_color, :parent_category_id, :associated_category_id
     )
   end
 

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

@@ -64,7 +64,7 @@ class Api::V1::Accounts::Channels::TwilioChannelsController < Api::V1::Accounts:
 
   def permitted_params
     params.require(:twilio_channel).permit(
-      :account_id, :messaging_service_sid, :phone_number, :account_sid, :auth_token, :name, :medium, :api_key_sid
+      :messaging_service_sid, :phone_number, :account_sid, :auth_token, :name, :medium, :api_key_sid
     )
   end
 end

app/controllers/api/v1/accounts/concerns/whatsapp_health_management.rb

@@ -0,0 +1,55 @@
+module Api::V1::Accounts::Concerns::WhatsappHealthManagement
+  extend ActiveSupport::Concern
+
+  included do
+    skip_before_action :check_authorization, only: [:health, :register_webhook]
+    before_action :check_admin_authorization?, only: [:register_webhook]
+    before_action :validate_whatsapp_cloud_channel, only: [:health, :register_webhook]
+  end
+
+  def sync_templates
+    return render status: :unprocessable_entity, json: { error: 'Template sync is only available for WhatsApp channels' } unless whatsapp_channel?
+
+    trigger_template_sync
+    render status: :ok, json: { message: 'Template sync initiated successfully' }
+  rescue StandardError => e
+    render status: :internal_server_error, json: { error: e.message }
+  end
+
+  def health
+    health_data = Whatsapp::HealthService.new(@inbox.channel).fetch_health_status
+    render json: health_data
+  rescue StandardError => e
+    Rails.logger.error "[INBOX HEALTH] Error fetching health data: #{e.message}"
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+
+  def register_webhook
+    Whatsapp::WebhookSetupService.new(@inbox.channel).register_callback
+
+    render json: { message: 'Webhook registered successfully' }, status: :ok
+  rescue StandardError => e
+    Rails.logger.error "[INBOX WEBHOOK] Webhook registration failed: #{e.message}"
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+
+  private
+
+  def validate_whatsapp_cloud_channel
+    return if @inbox.channel.is_a?(Channel::Whatsapp) && @inbox.channel.provider == 'whatsapp_cloud'
+
+    render json: { error: 'Health data only available for WhatsApp Cloud API channels' }, status: :bad_request
+  end
+
+  def whatsapp_channel?
+    @inbox.whatsapp? || (@inbox.twilio? && @inbox.channel.whatsapp?)
+  end
+
+  def trigger_template_sync
+    if @inbox.whatsapp?
+      Channels::Whatsapp::TemplatesSyncJob.perform_later(@inbox.channel)
+    elsif @inbox.twilio? && @inbox.channel.whatsapp?
+      Channels::Twilio::TemplatesSyncJob.perform_later(@inbox.channel)
+    end
+  end
+end

app/controllers/api/v1/accounts/contacts/attachments_controller.rb

@@ -0,0 +1,18 @@
+class Api::V1::Accounts::Contacts::AttachmentsController < Api::V1::Accounts::Contacts::BaseController
+  RESULTS_PER_PAGE = 100
+
+  def index
+    conversations = Conversations::PermissionFilterService.new(
+      Current.account.conversations.where(contact_id: @contact.id),
+      Current.user,
+      Current.account
+    ).perform
+
+    @attachments = Attachment.where(message_id: Message.where(conversation_id: conversations).select(:id))
+                             .includes({ file_attachment: :blob }, message: [:conversation, :inbox, { sender: { avatar_attachment: :blob } }])
+                             .order(created_at: :desc)
+                             .page(params[:page])
+                             .per(RESULTS_PER_PAGE)
+    @attachments_count = @attachments.total_count
+  end
+end

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

@@ -5,7 +5,7 @@ class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
   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 :company_name, 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]
 
@@ -17,20 +17,18 @@ class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
   before_action :set_include_contact_inboxes, only: [:index, :active, :search, :filter, :show, :update]
 
   def index
-    @contacts_count = resolved_contacts.count
     @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 = resolved_contacts.where(
-      'name ILIKE :search OR email ILIKE :search OR phone_number ILIKE :search OR contacts.identifier LIKE :search
-        OR contacts.additional_attributes->>\'company_name\' ILIKE :search',
+    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_count = contacts.count
-    @contacts = fetch_contacts(contacts)
+    @contacts = fetch_contacts_with_has_more(contacts)
   end
 
   def import
@@ -55,8 +53,8 @@ class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
   def active
     contacts = Current.account.contacts.where(id: ::OnlineStatusTracker
                   .get_available_contact_ids(Current.account.id))
-    @contacts_count = contacts.count
     @contacts = fetch_contacts(contacts)
+    @contacts_count = @contacts.total_count
   end
 
   def show; end
@@ -133,13 +131,32 @@ class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
   end
 
   def fetch_contacts(contacts)
-    contacts_with_avatar = filtrate(contacts)
-                           .includes([{ avatar_attachment: [:blob] }])
-                           .page(@current_page).per(RESULTS_PER_PAGE)
+    # 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
 
-    return contacts_with_avatar.includes([{ contact_inboxes: [:inbox] }]) if @include_contact_inboxes
+    filtrate(contacts)
+      .includes(includes_hash)
+      .page(@current_page)
+      .per(RESULTS_PER_PAGE)
+  end
 
-    contacts_with_avatar
+  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
@@ -184,7 +201,9 @@ class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
   end
 
   def fetch_contact
-    @contact = Current.account.contacts.includes(contact_inboxes: [:inbox]).find(params[:id])
+    contact_scope = Current.account.contacts
+    contact_scope = contact_scope.includes(contact_inboxes: [:inbox]) if @include_contact_inboxes
+    @contact = contact_scope.find(params[:id])
   end
 
   def process_avatar_from_url
@@ -195,3 +214,5 @@ class Api::V1::Accounts::ContactsController < Api::V1::Accounts::BaseController
     render json: error, status: error_status
   end
 end
+
+Api::V1::Accounts::ContactsController.prepend_mod_with('Api::V1::Accounts::ContactsController')

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

@@ -1,7 +1,7 @@
 class Api::V1::Accounts::Conversations::AssignmentsController < Api::V1::Accounts::Conversations::BaseController
   # assigns agent/team to a conversation
   def create
-    if params.key?(:assignee_id)
+    if params.key?(:assignee_id) || agent_bot_assignment?
       set_agent
     elsif params.key?(:team_id)
       set_team
@@ -13,17 +13,23 @@ class Api::V1::Accounts::Conversations::AssignmentsController < Api::V1::Account
   private
 
   def set_agent
-    @agent = Current.account.users.find_by(id: params[:assignee_id])
-    @conversation.assignee = @agent
-    @conversation.save!
-    render_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
-    if @agent.nil?
-      render json: nil
+  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 partial: 'api/v1/models/agent', formats: [:json], locals: { resource: @agent }
+      render json: nil
     end
   end
 
@@ -32,4 +38,8 @@ class Api::V1::Accounts::Conversations::AssignmentsController < Api::V1::Account
     @conversation.update!(team: @team)
     render json: @team
   end
+
+  def agent_bot_assignment?
+    params[:assignee_type].to_s == 'AgentBot'
+  end
 end

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

@@ -5,6 +5,6 @@ class Api::V1::Accounts::Conversations::BaseController < Api::V1::Accounts::Base
 
   def conversation
     @conversation ||= Current.account.conversations.find_by!(display_id: params[:conversation_id])
-    authorize @conversation.inbox, :show?
+    authorize @conversation, :show?
   end
 end

app/controllers/api/v1/accounts/conversations/unread_counts_controller.rb

@@ -0,0 +1,16 @@
+class Api::V1::Accounts::Conversations::UnreadCountsController < Api::V1::Accounts::BaseController
+  before_action :ensure_unread_counts_enabled
+
+  def index
+    counts = ::Conversations::UnreadCounts::Counter.new(account: Current.account, user: Current.user).perform
+    render json: { payload: counts }
+  end
+
+  private
+
+  def ensure_unread_counts_enabled
+    return if Current.account.feature_enabled?('conversation_unread_counts')
+
+    render json: { error: I18n.t('errors.conversations.unread_counts.feature_not_enabled') }, status: :forbidden
+  end
+end

app/controllers/api/v1/accounts/conversations_controller.rb

@@ -15,7 +15,7 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
   end
 
   def meta
-    result = conversation_finder.perform
+    result = conversation_finder.perform_meta_only
     @conversations_count = result[:count]
   end
 
@@ -28,7 +28,7 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
   def attachments
     @attachments_count = @conversation.attachments.count
     @attachments = @conversation.attachments
-                                .includes(:message)
+                                .includes({ file_attachment: :blob }, message: [:inbox, { sender: { avatar_attachment: :blob } }])
                                 .order(created_at: :desc)
                                 .page(attachment_params[:page])
                                 .per(ATTACHMENT_RESULTS_PER_PAGE)
@@ -70,8 +70,11 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
 
   def transcript
     render json: { error: 'email param missing' }, status: :unprocessable_entity and return if params[:email].blank?
+    return render_payment_required('Email transcript is not available on your plan') unless @conversation.account.email_transcript_enabled?
+    return head :too_many_requests unless @conversation.account.within_email_rate_limit?
 
     ConversationReplyMailer.with(account: @conversation.account).conversation_transcript(@conversation, params[:email])&.deliver_later
+    @conversation.account.increment_email_sent_count
     head :ok
   end
 
@@ -104,12 +107,23 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
   end
 
   def toggle_typing_status
-    typing_status_manager = ::Conversations::TypingStatusManager.new(@conversation, current_user, params)
+    typing_status_manager = ::Conversations::TypingStatusManager.new(@conversation, Current.user, params)
     typing_status_manager.toggle_typing_status
     head :ok
   end
 
   def update_last_seen
+    # High-traffic accounts generate excessive DB writes when agents frequently switch between conversations.
+    # Throttle last_seen updates to once per hour when there are no unread messages to reduce DB load.
+    # Always update immediately if there are unread messages to maintain accurate read/unread state.
+    # Visiting a conversation should clear any unread inbox notifications for this conversation.
+    Notification::MarkConversationReadService.new(user: Current.user, account: Current.account, conversation: @conversation).perform
+    return update_last_seen_on_conversation(DateTime.now.utc, true) if assignee? && @conversation.assignee_unread_messages.any?
+    return update_last_seen_on_conversation(DateTime.now.utc, false) if !assignee? && @conversation.unread_messages.any?
+
+    # No unread messages - apply throttling to limit DB writes
+    return unless should_update_last_seen?
+
     update_last_seen_on_conversation(DateTime.now.utc, assignee?)
   end
 
@@ -126,7 +140,7 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
 
   def destroy
     authorize @conversation, :destroy?
-    ::DeleteObjectJob.perform_later(@conversation, Current.user, request.ip)
+    ::Conversations::DeleteService.new(conversation: @conversation, user: Current.user, ip: request.ip).perform
     head :ok
   end
 
@@ -142,10 +156,25 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
   end
 
   def update_last_seen_on_conversation(last_seen_at, update_assignee)
+    updates = { agent_last_seen_at: last_seen_at }
+    updates[:assignee_last_seen_at] = last_seen_at if update_assignee.present?
+
     # rubocop:disable Rails/SkipsModelValidations
-    @conversation.update_column(:agent_last_seen_at, last_seen_at)
-    @conversation.update_column(:assignee_last_seen_at, last_seen_at) if update_assignee.present?
+    @conversation.update_columns(updates)
     # rubocop:enable Rails/SkipsModelValidations
+
+    ::Conversations::UnreadCounts::Notifier.new(@conversation).perform
+  end
+
+  def should_update_last_seen?
+    # Update if at least one relevant timestamp is older than 1 hour or not set
+    # This prevents redundant DB writes when agents repeatedly view the same conversation
+    agent_needs_update = @conversation.agent_last_seen_at.blank? || @conversation.agent_last_seen_at < 1.hour.ago
+    return agent_needs_update unless assignee?
+
+    # For assignees, check both timestamps - update if either is old
+    assignee_needs_update = @conversation.assignee_last_seen_at.blank? || @conversation.assignee_last_seen_at < 1.hour.ago
+    agent_needs_update || assignee_needs_update
   end
 
   def set_conversation_status
@@ -160,7 +189,7 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
 
   def conversation
     @conversation ||= Current.account.conversations.find_by!(display_id: params[:id])
-    authorize @conversation.inbox, :show?
+    authorize @conversation, :show?
   end
 
   def inbox

app/controllers/api/v1/accounts/csat_survey_responses_controller.rb

@@ -50,3 +50,5 @@ class Api::V1::Accounts::CsatSurveyResponsesController < Api::V1::Accounts::Base
     @current_page = params[:page] || 1
   end
 end
+
+Api::V1::Accounts::CsatSurveyResponsesController.prepend_mod_with('Api::V1::Accounts::CsatSurveyResponsesController')

app/controllers/api/v1/accounts/custom_attribute_definitions_controller.rb

@@ -1,6 +1,7 @@
 class Api::V1::Accounts::CustomAttributeDefinitionsController < Api::V1::Accounts::BaseController
   before_action :fetch_custom_attributes_definitions, except: [:create]
   before_action :fetch_custom_attribute_definition, only: [:show, :update, :destroy]
+  before_action :check_authorization
   DEFAULT_ATTRIBUTE_MODEL = 'conversation_attribute'.freeze
 
   def index; end

app/controllers/api/v1/accounts/inbox_csat_templates_controller.rb

@@ -0,0 +1,135 @@
+class Api::V1::Accounts::InboxCsatTemplatesController < Api::V1::Accounts::BaseController
+  before_action :fetch_inbox
+  before_action :validate_whatsapp_channel
+  before_action :validate_captain_enabled, only: [:analyze]
+
+  def show
+    service = CsatTemplateManagementService.new(@inbox)
+    result = service.template_status
+
+    if result[:service_error]
+      render json: { error: result[:service_error] }, status: :internal_server_error
+    else
+      render json: result
+    end
+  end
+
+  def create
+    template_params = extract_template_params
+    return render_missing_message_error if template_params[:message].blank?
+
+    service = CsatTemplateManagementService.new(@inbox)
+    result = service.create_template(template_params)
+    render_template_creation_result(result)
+  rescue ActionController::ParameterMissing
+    render json: { error: 'Template parameters are required' }, status: :unprocessable_entity
+  end
+
+  def analyze
+    template_params = extract_template_params
+    return render_missing_message_error if template_params[:message].blank?
+
+    result = CsatTemplateUtilityAnalysisService.new(
+      account: Current.account,
+      inbox: @inbox,
+      message: template_params[:message],
+      button_text: template_params[:button_text],
+      language: template_params[:language]
+    ).perform
+
+    render json: result
+  rescue ActionController::ParameterMissing
+    render json: { error: 'Template parameters are required' }, status: :unprocessable_entity
+  end
+
+  private
+
+  def fetch_inbox
+    @inbox = Current.account.inboxes.find(params[:inbox_id])
+    authorize @inbox, :show?
+  end
+
+  def validate_whatsapp_channel
+    return if @inbox.whatsapp? || @inbox.twilio_whatsapp?
+
+    render json: { error: 'CSAT template operations only available for WhatsApp and Twilio WhatsApp channels' },
+           status: :bad_request
+  end
+
+  def extract_template_params
+    params.require(:template).permit(:message, :button_text, :language)
+  end
+
+  def render_missing_message_error
+    render json: { error: 'Message is required' }, status: :unprocessable_entity
+  end
+
+  def validate_captain_enabled
+    return if Current.account.feature_enabled?('captain_integration')
+
+    render json: { error: 'Captain is required for template analysis' }, status: :forbidden
+  end
+
+  def render_template_creation_result(result)
+    if result[:success]
+      render_successful_template_creation(result)
+    elsif result[:service_error]
+      render json: { error: result[:service_error] }, status: :internal_server_error
+    else
+      render_failed_template_creation(result)
+    end
+  end
+
+  def render_successful_template_creation(result)
+    if @inbox.twilio_whatsapp?
+      render json: {
+        template: {
+          friendly_name: result[:friendly_name],
+          content_sid: result[:content_sid],
+          status: result[:status] || 'pending',
+          language: result[:language] || 'en'
+        }
+      }, status: :created
+    else
+      render json: {
+        template: {
+          name: result[:template_name],
+          template_id: result[:template_id],
+          status: 'PENDING',
+          language: result[:language] || 'en'
+        }
+      }, status: :created
+    end
+  end
+
+  def render_failed_template_creation(result)
+    whatsapp_error = parse_whatsapp_error(result[:response_body])
+    error_message = whatsapp_error[:user_message] || result[:error]
+
+    render json: {
+      error: error_message,
+      details: whatsapp_error[:technical_details]
+    }, status: :unprocessable_entity
+  end
+
+  def parse_whatsapp_error(response_body)
+    return { user_message: nil, technical_details: nil } if response_body.blank?
+
+    begin
+      error_data = JSON.parse(response_body)
+      whatsapp_error = error_data['error'] || {}
+
+      user_message = whatsapp_error['error_user_msg'] || whatsapp_error['message']
+      technical_details = {
+        code: whatsapp_error['code'],
+        subcode: whatsapp_error['error_subcode'],
+        type: whatsapp_error['type'],
+        title: whatsapp_error['error_user_title']
+      }.compact
+
+      { user_message: user_message, technical_details: technical_details }
+    rescue JSON::ParserError
+      { user_message: nil, technical_details: response_body }
+    end
+  end
+end

app/controllers/api/v1/accounts/inboxes_controller.rb

@@ -6,8 +6,12 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
   # we are already handling the authorization in fetch inbox
   before_action :check_authorization, except: [:show]
 
+  include Api::V1::Accounts::Concerns::WhatsappHealthManagement
+
   def index
-    @inboxes = policy_scope(Current.account.inboxes.order_by_name.includes(:channel, { avatar_attachment: [:blob] }))
+    @inboxes = policy_scope(Current.account.inboxes)
+               .includes(:channel, :portal, :working_hours, { avatar_attachment: :blob })
+               .order_by_name
   end
 
   def show; end
@@ -17,6 +21,11 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
     @assignable_agents = @inbox.assignable_agents
   end
 
+  def assignable_owners
+    @assignable_agents = @inbox.assignable_agents.select(&:confirmed?)
+    @agent_bots = AgentBot.accessible_to(Current.account)
+  end
+
   def campaigns
     @campaigns = @inbox.campaigns
   end
@@ -64,22 +73,17 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
     head :ok
   end
 
+  def reset_secret
+    return head :not_found unless @inbox.api?
+
+    @inbox.channel.reset_secret!
+  end
+
   def destroy
     ::DeleteObjectJob.perform_later(@inbox, Current.user, request.ip) if @inbox.present?
     render status: :ok, json: { message: I18n.t('messages.inbox_deletetion_response') }
   end
 
-  def sync_templates
-    unless @inbox.channel.is_a?(Channel::Whatsapp)
-      return render status: :unprocessable_entity, json: { error: 'Template sync is only available for WhatsApp channels' }
-    end
-
-    Channels::Whatsapp::TemplatesSyncJob.perform_later(@inbox.channel)
-    render status: :ok, json: { message: 'Template sync initiated successfully' }
-  rescue StandardError => e
-    render status: :internal_server_error, json: { error: e.message }
-  end
-
   private
 
   def fetch_inbox
@@ -88,7 +92,7 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
   end
 
   def fetch_agent_bot
-    @agent_bot = AgentBot.find(params[:agent_bot]) if params[:agent_bot]
+    @agent_bot = AgentBot.accessible_to(Current.account).find(params[:agent_bot]) if params[:agent_bot]
   end
 
   def create_channel
@@ -139,31 +143,37 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
   end
 
   def format_csat_config(config)
-    {
-      display_type: config['display_type'] || 'emoji',
-      message: config['message'] || '',
-      survey_rules: {
-        operator: config.dig('survey_rules', 'operator') || 'contains',
-        values: config.dig('survey_rules', 'values') || []
-      }
+    formatted = {
+      'display_type' => config['display_type'] || 'emoji',
+      'message' => config['message'] || '',
+      :survey_rules => {
+        'operator' => config.dig('survey_rules', 'operator') || 'contains',
+        'values' => config.dig('survey_rules', 'values') || []
+      },
+      'button_text' => config['button_text'] || 'Please rate us',
+      'language' => config['language'] || 'en'
     }
+    format_template_config(config, formatted)
+    formatted
+  end
+
+  def format_template_config(config, formatted)
+    formatted['template'] = config['template'] if config['template'].present?
   end
 
   def inbox_attributes
     [:name, :avatar, :greeting_enabled, :greeting_message, :enable_email_collect, :csat_survey_enabled,
      :enable_auto_assignment, :working_hours_enabled, :out_of_office_message, :timezone, :allow_messages_after_resolved,
      :lock_to_single_conversation, :portal_id, :sender_name_type, :business_name,
-     { csat_config: [:display_type, :message, { survey_rules: [:operator, { values: [] }] }] }]
+     { csat_config: [:display_type, :message, :button_text, :language,
+                     { survey_rules: [:operator, { values: [] }],
+                       template: [:name, :template_id, :friendly_name, :content_sid, :approval_sid, :created_at, :language, :status] }] }]
   end
 
   def permitted_params(channel_attributes = [])
     # We will remove this line after fixing https://linear.app/chatwoot/issue/CW-1567/null-value-passed-as-null-string-to-backend
     params.each { |k, v| params[k] = params[k] == 'null' ? nil : v }
-
-    params.permit(
-      *inbox_attributes,
-      channel: [:type, *channel_attributes]
-    )
+    params.permit(*inbox_attributes, channel: [:type, *channel_attributes])
   end
 
   def channel_type_from_params
@@ -179,11 +189,7 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
   end
 
   def get_channel_attributes(channel_type)
-    if channel_type.constantize.const_defined?(:EDITABLE_ATTRS)
-      channel_type.constantize::EDITABLE_ATTRS.presence
-    else
-      []
-    end
+    channel_type.constantize.const_defined?(:EDITABLE_ATTRS) ? channel_type.constantize::EDITABLE_ATTRS.presence : []
   end
 end
 

app/controllers/api/v1/accounts/instagram/authorizations_controller.rb

@@ -11,7 +11,7 @@ class Api::V1::Accounts::Instagram::AuthorizationsController < Api::V1::Accounts
         enable_fb_login: '0',
         force_authentication: '1',
         response_type: 'code',
-        state: generate_instagram_token(Current.account.id)
+        state: generate_instagram_token(Current.account.id, params[:return_to])
       }
     )
     if redirect_url

app/controllers/api/v1/accounts/integrations/dyte_controller.rb

@@ -22,7 +22,7 @@ class Api::V1::Accounts::Integrations::DyteController < Api::V1::Accounts::BaseC
   private
 
   def authorize_request
-    authorize @conversation.inbox, :show?
+    authorize @conversation, :show?
   end
 
   def render_response(response)

app/controllers/api/v1/accounts/integrations/linear_controller.rb

@@ -126,7 +126,7 @@ class Api::V1::Accounts::Integrations::LinearController < Api::V1::Accounts::Bas
     return unless @hook&.access_token
 
     begin
-      linear_client = Linear.new(@hook.access_token)
+      linear_client = Linear.new(@hook.access_token, refresh_token: @hook.settings&.[]('refresh_token'))
       linear_client.revoke_token
     rescue StandardError => e
       Rails.logger.error "Failed to revoke Linear token: #{e.message}"

app/controllers/api/v1/accounts/labels_controller.rb

@@ -18,7 +18,16 @@ class Api::V1::Accounts::LabelsController < Api::V1::Accounts::BaseController
   end
 
   def destroy
+    label_title = @label.title
+    account_id = Current.account.id
+    label_deleted_at = Time.current
+
     @label.destroy!
+    Labels::RemoveAssociationsJob.perform_later(
+      label_title: label_title,
+      account_id: account_id,
+      label_deleted_at: label_deleted_at
+    )
     head :ok
   end
 

app/controllers/api/v1/accounts/macros_controller.rb

@@ -1,4 +1,6 @@
 class Api::V1::Accounts::MacrosController < Api::V1::Accounts::BaseController
+  include AttachmentConcern
+
   before_action :fetch_macro, only: [:show, :update, :destroy, :execute]
   before_action :check_authorization, only: [:show, :update, :destroy, :execute]
 
@@ -11,26 +13,32 @@ class Api::V1::Accounts::MacrosController < Api::V1::Accounts::BaseController
   end
 
   def create
+    blobs, actions, error = validate_and_prepare_attachments(params[:actions])
+    return render_could_not_create_error(error) if error
+
     @macro = Current.account.macros.new(macros_with_user.merge(created_by_id: current_user.id))
     @macro.set_visibility(current_user, permitted_params)
-    @macro.actions = params[:actions]
+    @macro.actions = actions
 
-    render json: { error: @macro.errors.messages }, status: :unprocessable_entity and return unless @macro.valid?
+    return render_could_not_create_error(@macro.errors.messages) unless @macro.valid?
 
     @macro.save!
-    process_attachments
-    @macro
+    blobs.each { |blob| @macro.files.attach(blob) }
   end
 
   def update
+    blobs, actions, error = validate_and_prepare_attachments(params[:actions], @macro)
+    return render_could_not_create_error(error) if error
+
     ActiveRecord::Base.transaction do
-      @macro.update!(macros_with_user)
+      @macro.assign_attributes(macros_with_user)
       @macro.set_visibility(current_user, permitted_params)
-      process_attachments
+      @macro.actions = actions if params[:actions]
       @macro.save!
+      blobs.each { |blob| @macro.files.attach(blob) }
     rescue StandardError => e
       Rails.logger.error e
-      render json: { error: @macro.errors.messages }.to_json, status: :unprocessable_entity
+      render_could_not_create_error(@macro.errors.messages)
     end
   end
 
@@ -47,20 +55,9 @@ class Api::V1::Accounts::MacrosController < Api::V1::Accounts::BaseController
 
   private
 
-  def process_attachments
-    actions = @macro.actions.filter_map { |k, _v| k if k['action_name'] == 'send_attachment' }
-    return if actions.blank?
-
-    actions.each do |action|
-      blob_id = action['action_params']
-      blob = ActiveStorage::Blob.find_by(id: blob_id)
-      @macro.files.attach(blob)
-    end
-  end
-
   def permitted_params
     params.permit(
-      :name, :account_id, :visibility,
+      :name, :visibility,
       actions: [:action_name, { action_params: [] }]
     )
   end

app/controllers/api/v1/accounts/microsoft/authorizations_controller.rb

@@ -6,8 +6,7 @@ class Api::V1::Accounts::Microsoft::AuthorizationsController < Api::V1::Accounts
       {
         redirect_uri: "#{base_url}/microsoft/callback",
         scope: scope,
-        state: state,
-        prompt: 'consent'
+        state: state
       }
     )
     if redirect_url

app/controllers/api/v1/accounts/notifications_controller.rb

@@ -41,9 +41,9 @@ class Api::V1::Accounts::NotificationsController < Api::V1::Accounts::BaseContro
 
   def destroy_all
     if params[:type] == 'read'
-      ::Notification::DeleteNotificationJob.perform_later(Current.user, type: :read)
+      ::Notification::DeleteNotificationJob.perform_later(Current.user, Current.account, type: :read)
     else
-      ::Notification::DeleteNotificationJob.perform_later(Current.user, type: :all)
+      ::Notification::DeleteNotificationJob.perform_later(Current.user, Current.account, type: :all)
     end
     head :ok
   end
@@ -69,7 +69,7 @@ class Api::V1::Accounts::NotificationsController < Api::V1::Accounts::BaseContro
   end
 
   def fetch_notification
-    @notification = current_user.notifications.find(params[:id])
+    @notification = current_user.notifications.where(account_id: Current.account.id).find(params[:id])
   end
 
   def set_current_page

app/controllers/api/v1/accounts/oauth_authorization_controller.rb

@@ -8,7 +8,15 @@ class Api::V1::Accounts::OauthAuthorizationController < Api::V1::Accounts::BaseC
   end
 
   def state
-    Current.account.to_sgid(expires_in: 15.minutes).to_s
+    # The sgid purpose doubles as a return hint: onboarding tags it so the callback
+    # can route the user back to inbox setup. The purpose is part of the signed
+    # payload (tamper-proof), and a non-onboarding request keeps the default
+    # purpose, leaving callers like Notion byte-identical.
+    Current.account.to_sgid(expires_in: 15.minutes, for: state_purpose).to_s
+  end
+
+  def state_purpose
+    params[:return_to] == 'onboarding' ? 'onboarding' : 'default'
   end
 
   def base_url

app/controllers/api/v1/accounts/onboardings_controller.rb

@@ -0,0 +1,51 @@
+class Api::V1::Accounts::OnboardingsController < Api::V1::Accounts::BaseController
+  before_action :check_admin_authorization?
+
+  def update
+    @account = Current.account
+    finalize = finalizing_account_details?
+
+    @account.assign_attributes(account_params)
+    @account.custom_attributes.merge!(custom_attributes_params)
+    @account.custom_attributes.delete('onboarding_step') if finalize
+    @account.save!
+
+    # TODO: re-enable when the help center generation UI is ready to surface progress
+    # Onboarding::HelpCenterCreationService.new(@account, Current.user).perform if finalize && website.present?
+
+    render 'api/v1/accounts/update', format: :json
+  end
+
+  def help_center_generation
+    render json: help_center_generation_status
+  end
+
+  private
+
+  def finalizing_account_details?
+    @account.custom_attributes['onboarding_step'] == 'account_details'
+  end
+
+  def website
+    custom_attributes_params[:website]
+  end
+
+  def account_params
+    params.permit(:name, :locale)
+  end
+
+  def custom_attributes_params
+    params.permit(:industry, :company_size, :timezone, :referral_source, :user_role, :website)
+  end
+
+  def help_center_generation_status
+    {
+      generation_id: nil,
+      state: nil,
+      articles_count: 0,
+      categories_count: 0
+    }
+  end
+end
+
+Api::V1::Accounts::OnboardingsController.prepend_mod_with('Api::V1::Accounts::OnboardingsController')

app/controllers/api/v1/accounts/portals_controller.rb

@@ -18,7 +18,7 @@ class Api::V1::Accounts::PortalsController < Api::V1::Accounts::BaseController
     @portal = Current.account.portals.build(portal_params.merge(live_chat_widget_params))
     @portal.custom_domain = parsed_custom_domain
     @portal.save!
-    process_attached_logo
+    process_attached_logo if params[:blob_id].present?
   end
 
   def update
@@ -61,9 +61,8 @@ class Api::V1::Accounts::PortalsController < Api::V1::Accounts::BaseController
   end
 
   def process_attached_logo
-    blob_id = params[:blob_id]
-    blob = ActiveStorage::Blob.find_by(id: blob_id)
-    @portal.logo.attach(blob)
+    blob = ActiveStorage::Blob.find_signed(params[:blob_id].to_s)
+    @portal.logo.attach(blob) if blob
   end
 
   private
@@ -78,16 +77,24 @@ class Api::V1::Accounts::PortalsController < Api::V1::Accounts::BaseController
 
   def portal_params
     params.require(:portal).permit(
-      :id, :account_id, :color, :custom_domain, :header_text, :homepage_link,
-      :name, :page_title, :slug, :archived, { config: [:default_locale, { allowed_locales: [] }] }
+      :id, :color, :custom_domain, :header_text, :homepage_link,
+      :name, :page_title, :slug, :archived,
+      { config: [:default_locale, :layout, { allowed_locales: [] }, { draft_locales: [] },
+                 { social_profiles: %i[facebook x instagram linkedin youtube tiktok github whatsapp] },
+                 { locale_translations: locale_translation_keys.index_with { %i[name page_title header_text] } }] }
     )
   end
 
+  def locale_translation_keys
+    params.dig(:portal, :config, :locale_translations)&.keys || []
+  end
+
   def live_chat_widget_params
     permitted_params = params.permit(:inbox_id)
-    return {} if permitted_params[:inbox_id].blank?
+    return {} unless permitted_params.key?(:inbox_id)
+    return { channel_web_widget_id: nil } if permitted_params[:inbox_id].blank?
 
-    inbox = Inbox.find(permitted_params[:inbox_id])
+    inbox = Current.account.inboxes.find(permitted_params[:inbox_id])
     return {} unless inbox.web_widget?
 
     { channel_web_widget_id: inbox.channel.id }
@@ -98,6 +105,8 @@ class Api::V1::Accounts::PortalsController < Api::V1::Accounts::BaseController
   end
 
   def parsed_custom_domain
+    return @portal.custom_domain if @portal.custom_domain.blank?
+
     domain = URI.parse(@portal.custom_domain)
     domain.is_a?(URI::HTTP) ? domain.host : @portal.custom_domain
   end

app/controllers/api/v1/accounts/search_controller.rb

@@ -28,5 +28,7 @@ class Api::V1::Accounts::SearchController < Api::V1::Accounts::BaseController
       search_type: search_type,
       params: params
     ).perform
+  rescue ArgumentError => e
+    render json: { error: e.message }, status: :unprocessable_entity
   end
 end

app/controllers/api/v1/accounts/tiktok/authorizations_controller.rb

@@ -0,0 +1,15 @@
+class Api::V1::Accounts::Tiktok::AuthorizationsController < Api::V1::Accounts::OauthAuthorizationController
+  include Tiktok::IntegrationHelper
+
+  def create
+    redirect_url = Tiktok::AuthClient.authorize_url(
+      state: generate_tiktok_token(Current.account.id, params[:return_to])
+    )
+
+    if redirect_url
+      render json: { success: true, url: redirect_url }
+    else
+      render json: { success: false }, status: :unprocessable_entity
+    end
+  end
+end

app/controllers/api/v1/accounts/upload_controller.rb

@@ -5,7 +5,7 @@ class Api::V1::Accounts::UploadController < Api::V1::Accounts::BaseController
              elsif params[:external_url].present?
                create_from_url
              else
-               render_error('No file or URL provided', :unprocessable_entity)
+               render_error(I18n.t('errors.upload.missing_input'), :unprocessable_entity)
              end
 
     render_success(result) if result.is_a?(ActiveStorage::Blob)
@@ -19,35 +19,21 @@ class Api::V1::Accounts::UploadController < Api::V1::Accounts::BaseController
   end
 
   def create_from_url
-    uri = parse_uri(params[:external_url])
-    return if performed?
-
-    fetch_and_process_file_from_uri(uri)
-  end
-
-  def parse_uri(url)
-    uri = URI.parse(url)
-    validate_uri(uri)
-    uri
-  rescue URI::InvalidURIError, SocketError
-    render_error('Invalid URL provided', :unprocessable_entity)
-    nil
-  end
-
-  def validate_uri(uri)
-    raise URI::InvalidURIError unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
-  end
-
-  def fetch_and_process_file_from_uri(uri)
-    uri.open do |file|
-      create_and_save_blob(file, File.basename(uri.path), file.content_type)
+    SafeFetch.fetch(params[:external_url].to_s) do |result|
+      create_and_save_blob(result.tempfile, result.filename, result.content_type)
     end
-  rescue OpenURI::HTTPError => e
-    render_error("Failed to fetch file from URL: #{e.message}", :unprocessable_entity)
-  rescue SocketError
-    render_error('Invalid URL provided', :unprocessable_entity)
+  rescue SafeFetch::HttpError => e
+    render_error(I18n.t('errors.upload.fetch_failed_with_message', message: e.message), :unprocessable_entity)
+  rescue SafeFetch::FetchError
+    render_error(I18n.t('errors.upload.fetch_failed'), :unprocessable_entity)
+  rescue SafeFetch::FileTooLargeError
+    render_error(I18n.t('errors.upload.file_too_large'), :unprocessable_entity)
+  rescue SafeFetch::UnsupportedContentTypeError
+    render_error(I18n.t('errors.upload.unsupported_content_type'), :unprocessable_entity)
+  rescue SafeFetch::Error
+    render_error(I18n.t('errors.upload.invalid_url'), :unprocessable_entity)
   rescue StandardError
-    render_error('An unexpected error occurred', :internal_server_error)
+    render_error(I18n.t('errors.upload.unexpected'), :internal_server_error)
   end
 
   def create_and_save_blob(io, filename, content_type)
@@ -59,7 +45,7 @@ class Api::V1::Accounts::UploadController < Api::V1::Accounts::BaseController
   end
 
   def render_success(file_blob)
-    render json: { file_url: url_for(file_blob), blob_key: file_blob.key, blob_id: file_blob.id }
+    render json: { file_url: url_for(file_blob), blob_id: file_blob.signed_id }
   end
 
   def render_error(message, status)

app/controllers/api/v1/accounts/webhooks_controller.rb

@@ -23,7 +23,7 @@ class Api::V1::Accounts::WebhooksController < Api::V1::Accounts::BaseController
   private
 
   def webhook_params
-    params.require(:webhook).permit(:inbox_id, :url, subscriptions: [])
+    params.require(:webhook).permit(:inbox_id, :name, :url, subscriptions: [])
   end
 
   def fetch_webhook

app/controllers/api/v1/accounts/whatsapp/authorizations_controller.rb

@@ -1,5 +1,4 @@
 class Api::V1::Accounts::Whatsapp::AuthorizationsController < Api::V1::Accounts::BaseController
-  before_action :validate_feature_enabled!
   before_action :fetch_and_validate_inbox, if: -> { params[:inbox_id].present? }
 
   # POST /api/v1/accounts/:account_id/whatsapp/authorization
@@ -65,15 +64,6 @@ class Api::V1::Accounts::Whatsapp::AuthorizationsController < Api::V1::Accounts:
     }, status: :unprocessable_entity
   end
 
-  def validate_feature_enabled!
-    return if Current.account.feature_whatsapp_embedded_signup?
-
-    render json: {
-      success: false,
-      error: 'WhatsApp embedded signup is not enabled for this account'
-    }, status: :forbidden
-  end
-
   def validate_embedded_signup_params!
     missing_params = []
     missing_params << 'code' if params[:code].blank?

app/controllers/api/v1/accounts/working_hours_controller.rb

@@ -1,18 +0,0 @@
-class Api::V1::Accounts::WorkingHoursController < Api::V1::Accounts::BaseController
-  before_action :check_authorization
-  before_action :fetch_webhook, only: [:update]
-
-  def update
-    @working_hour.update!(working_hour_params)
-  end
-
-  private
-
-  def working_hour_params
-    params.require(:working_hour).permit(:inbox_id, :open_hour, :open_minutes, :close_hour, :close_minutes, :closed_all_day)
-  end
-
-  def fetch_working_hour
-    @working_hour = Current.account.working_hours.find(params[:id])
-  end
-end

app/controllers/api/v1/accounts_controller.rb

@@ -30,9 +30,20 @@ class Api::V1::AccountsController < Api::BaseController
       locale: account_params[:locale],
       user: current_user
     ).perform
+    enqueue_branding_enrichment
     if @user
-      send_auth_headers(@user)
-      render 'api/v1/accounts/create', format: :json, locals: { resource: @user }
+      # Authenticated users (dashboard "add account") and api_only signups
+      # need the full response with account_id. API-only deployments have no
+      # frontend to handle the email confirmation flow, so they need auth
+      # tokens to proceed.
+      # Unauthenticated web signup returns only the email — no session is
+      # created until the user confirms via the email link.
+      if current_user || api_only_signup?
+        send_auth_headers(@user)
+        render 'api/v1/accounts/create', format: :json, locals: { resource: @user }
+      else
+        render json: { email: @user.email }
+      end
     else
       render_error_response(CustomExceptions::Account::SignupFailed.new({}))
     end
@@ -59,6 +70,17 @@ class Api::V1::AccountsController < Api::BaseController
 
   private
 
+  def enqueue_branding_enrichment
+    email = account_params[:email].presence || @user&.email
+    return if email.blank?
+
+    Account::BrandingEnrichmentJob.perform_later(@account.id, email)
+    Redis::Alfred.set(format(Redis::Alfred::ACCOUNT_ONBOARDING_ENRICHMENT, account_id: @account.id), '1', ex: 30)
+  rescue StandardError => e
+    # Enrichment is optional — never let queue/Redis failures abort signup
+    ChatwootExceptionTracker.new(e).capture_exception
+  end
+
   def ensure_account_name
     # ensure that account_name and user_full_name is present
     # this is becuase the account builder and the models validations are not triggered
@@ -88,15 +110,28 @@ class Api::V1::AccountsController < Api::BaseController
   end
 
   def custom_attributes_params
-    params.permit(:industry, :company_size, :timezone)
+    params.permit(:industry, :company_size, :timezone, :referral_source, :user_role, :website)
   end
 
   def settings_params
-    params.permit(:auto_resolve_after, :auto_resolve_message, :auto_resolve_ignore_waiting, :audio_transcriptions, :auto_resolve_label)
+    params.permit(*permitted_settings_attributes)
+  end
+
+  def permitted_settings_attributes
+    [:auto_resolve_after, :auto_resolve_message, :auto_resolve_ignore_waiting, :audio_transcriptions, :auto_resolve_label]
   end
 
   def check_signup_enabled
-    raise ActionController::RoutingError, 'Not Found' if GlobalConfigService.load('ENABLE_ACCOUNT_SIGNUP', 'false') == 'false'
+    raise ActionController::RoutingError, 'Not Found' unless GlobalConfigService.account_signup_enabled?
+  end
+
+  def api_only_signup?
+    # CW_API_ONLY_SERVER is the canonical flag for API-only deployments.
+    # ENABLE_ACCOUNT_SIGNUP='api_only' is a legacy sentinel for the same purpose.
+    # Read ENABLE_ACCOUNT_SIGNUP raw from InstallationConfig because GlobalConfig.get
+    # typecasts it to boolean, coercing 'api_only' to true.
+    ActiveModel::Type::Boolean.new.cast(ENV.fetch('CW_API_ONLY_SERVER', false)) ||
+      InstallationConfig.find_by(name: 'ENABLE_ACCOUNT_SIGNUP')&.value.to_s == 'api_only'
   end
 
   def validate_captcha
@@ -111,3 +146,5 @@ class Api::V1::AccountsController < Api::BaseController
     }
   end
 end
+
+Api::V1::AccountsController.prepend_mod_with('Api::V1::AccountsSettings')

app/controllers/api/v1/notification_subscriptions_controller.rb

@@ -8,7 +8,8 @@ class Api::V1::NotificationSubscriptionsController < Api::BaseController
   end
 
   def destroy
-    notification_subscription = NotificationSubscription.where(["subscription_attributes->>'push_token' = ?", params[:push_token]]).first
+    notification_subscription = current_user.notification_subscriptions
+                                            .where(["subscription_attributes->>'push_token' = ?", params[:push_token]]).first
     notification_subscription.destroy! if notification_subscription.present?
     head :ok
   end