From 397ac2e18a2a9eb34fbfd8c2b56fb1c59cf5b564 Mon Sep 17 00:00:00 2001
From: Muhsin Keloth <muhsinkeramam@gmail.com>
Date: Tue, 7 Jul 2026 12:18:17 +0400
Subject: [PATCH 01/17] chore(inbox): temporarily disable Instagram and
 WhatsApp embedded signup inbox creation (#14943)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This temporarily turns off inbox creation for channels that rely on
Meta's embedded signup — the WhatsApp Cloud signup popup, Instagram
(OAuth-only), and WhatsApp Call. WhatsApp Cloud inbox creation now falls
back to the manual API-key form, while the Instagram and WhatsApp Call
tiles appear disabled. Both channels are also hidden from the
new-account onboarding flow. Existing inboxes are not affected.

---------

Co-authored-by: Muhsin <12408980+muhsin-k@users.noreply.github.com>
---
 .../dashboard/components/widgets/ChannelItem.vue           | 7 ++++++-
 app/javascript/dashboard/constants/globals.js              | 5 +++++
 .../dashboard/onboarding/inbox-setup/useChannelConfig.js   | 6 +++++-
 .../specs/inbox-setup/useDetectedChannels.spec.js          | 7 +++++++
 .../routes/dashboard/settings/inbox/channels/Whatsapp.vue  | 2 ++
 5 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/app/javascript/dashboard/components/widgets/ChannelItem.vue b/app/javascript/dashboard/components/widgets/ChannelItem.vue
index 2429ebe7b..2652b582b 100644
--- a/app/javascript/dashboard/components/widgets/ChannelItem.vue
+++ b/app/javascript/dashboard/components/widgets/ChannelItem.vue
@@ -1,6 +1,7 @@
 <script setup>
 import { computed } from 'vue';
 import ChannelSelector from '../ChannelSelector.vue';
+import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 const props = defineProps({
   channel: {
@@ -20,7 +21,10 @@ const hasFbConfigured = computed(() => {
 });
 
 const hasInstagramConfigured = computed(() => {
-  return window.chatwootConfig?.instagramAppId;
+  return (
+    !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+    window.chatwootConfig?.instagramAppId
+  );
 });
 
 const hasTiktokConfigured = computed(() => {
@@ -58,6 +62,7 @@ const isActive = computed(() => {
 
   if (key === 'whatsapp_call') {
     return (
+      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
       props.enabledFeatures.channel_voice &&
       !!window.chatwootConfig?.whatsappAppId &&
       window.chatwootConfig.whatsappAppId !== 'none'
diff --git a/app/javascript/dashboard/constants/globals.js b/app/javascript/dashboard/constants/globals.js
index 24c0f07b1..717e5104f 100644
--- a/app/javascript/dashboard/constants/globals.js
+++ b/app/javascript/dashboard/constants/globals.js
@@ -78,3 +78,8 @@ export default {
   },
 };
 export const DEFAULT_REDIRECT_URL = '/app/';
+
+// Temporarily disables Instagram and WhatsApp inbox creation
+// (WhatsApp embedded signup popup, Instagram OAuth, WhatsApp Call).
+// Flip to false when the channels are brought back.
+export const IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED = true;
diff --git a/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js b/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
index ba2d6f0dc..9618c5e44 100644
--- a/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
+++ b/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
@@ -1,4 +1,5 @@
 import { useMapGetter } from 'dashboard/composables/store';
+import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 // OAuth/SDK channels need installation-level app credentials to be usable. When
 // the credential is missing the channel is "not configured" and is hidden from
@@ -13,11 +14,14 @@ export function useChannelConfig() {
     // WhatsApp is onboarded only via Meta embedded signup, which needs both the
     // app id (not the 'none' sentinel) and the signup configuration id.
     whatsapp: () =>
+      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
       Boolean(installationConfig.whatsappAppId) &&
       installationConfig.whatsappAppId !== 'none' &&
       Boolean(installationConfig.whatsappConfigurationId),
     facebook: () => Boolean(installationConfig.fbAppId),
-    instagram: () => Boolean(installationConfig.instagramAppId),
+    instagram: () =>
+      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+      Boolean(installationConfig.instagramAppId),
     tiktok: () => Boolean(installationConfig.tiktokAppId),
     gmail: () => Boolean(installationConfig.googleOAuthClientId),
     outlook: () => Boolean(globalConfig.value.azureAppId),
diff --git a/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js b/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
index 1134d4494..875bfaf0d 100644
--- a/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
+++ b/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
@@ -6,6 +6,13 @@ import { useDetectedChannels } from '../../inbox-setup/useDetectedChannels';
 
 vi.mock('vue-router');
 
+// Neutralize the temporary Instagram/WhatsApp kill switch so these specs keep
+// covering the credential-based gating it currently short-circuits.
+vi.mock('dashboard/constants/globals', async importOriginal => ({
+  ...(await importOriginal()),
+  IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED: false,
+}));
+
 // Mounts the composable against a real store and the real useAccount (only
 // useRoute and the underlying getters are faked), so a change to how useAccount
 // resolves the current account is exercised here too. The real ./constants are
diff --git a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
index b8b8126c7..98cc90fee 100644
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
@@ -7,6 +7,7 @@ import ThreeSixtyDialogWhatsapp from './360DialogWhatsapp.vue';
 import CloudWhatsapp from './CloudWhatsapp.vue';
 import WhatsappEmbeddedSignup from './WhatsappEmbeddedSignup.vue';
 import ChannelSelector from 'dashboard/components/ChannelSelector.vue';
+import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 const route = useRoute();
 const router = useRouter();
@@ -23,6 +24,7 @@ const PROVIDER_TYPES = {
 
 const hasWhatsappAppId = computed(() => {
   return (
+    !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
     window.chatwootConfig?.whatsappAppId &&
     window.chatwootConfig.whatsappAppId !== 'none'
   );

From b823764199fb2b0b5462b4ffab249dcf21923160 Mon Sep 17 00:00:00 2001
From: Sojan Jose <sojan@pepalo.com>
Date: Tue, 7 Jul 2026 01:55:54 -0700
Subject: [PATCH 02/17] refactor: optimize agent bot assignment dropdown
 (#14866)

---
 .../accounts/assignable_agents_controller.rb  |  3 ++
 .../dashboard/api/assignableAgents.js         |  7 +++-
 .../dashboard/api/inbox/conversation.js       |  3 +-
 .../api/specs/assignableAgents.spec.js        | 10 +++++
 .../api/specs/inbox/conversation.spec.js      |  7 +++-
 .../widgets/conversation/ConversationBox.vue  |  5 ++-
 .../widgets/conversation/ConversationCard.vue | 16 ++++++--
 .../conversation/EmailTranscriptModal.vue     |  8 +++-
 .../conversation/contextMenu/menuItem.vue     | 11 ++++-
 .../composables/spec/useAgentsList.spec.js    | 21 +++++++++-
 .../dashboard/composables/useAgentsList.js    | 11 ++++-
 .../dashboard/helper/agentHelper.js           |  2 +-
 .../conversation/ConversationAction.vue       | 24 +++++++++--
 .../store/modules/conversations/actions.js    | 14 +++++--
 .../store/modules/conversations/index.js      |  3 +-
 .../store/modules/inboxAssignableAgents.js    | 37 +++++++++++++----
 .../specs/conversations/actions.spec.js       |  4 +-
 .../specs/conversations/mutations.spec.js     |  2 +
 .../inboxAssignableMembers/actions.spec.js    | 39 ++++++++++++++++--
 .../inboxAssignableMembers/getters.spec.js    | 23 ++++++++++-
 .../components/ui/MultiselectDropdown.vue     | 25 +++++++++--
 .../ui/MultiselectDropdownItems.vue           | 41 ++++++++++++++++---
 .../assignable_agents/index.json.jbuilder     | 15 ++++++-
 .../assignable_agents_controller_spec.rb      | 18 ++++++++
 24 files changed, 302 insertions(+), 47 deletions(-)

diff --git a/app/controllers/api/v1/accounts/assignable_agents_controller.rb b/app/controllers/api/v1/accounts/assignable_agents_controller.rb
index a712342dd..29dcb62b2 100644
--- a/app/controllers/api/v1/accounts/assignable_agents_controller.rb
+++ b/app/controllers/api/v1/accounts/assignable_agents_controller.rb
@@ -2,6 +2,8 @@ class Api::V1::Accounts::AssignableAgentsController < Api::V1::Accounts::BaseCon
   before_action :fetch_inboxes
 
   def index
+    # TODO: Remove this opt-in once mobile clients support AgentBot assignees in this payload.
+    @include_agent_bots = params[:include_agent_bots].present?
     agent_ids = @inboxes.map do |inbox|
       authorize inbox, :show?
       member_ids = inbox.members.pluck(:user_id)
@@ -10,6 +12,7 @@ class Api::V1::Accounts::AssignableAgentsController < Api::V1::Accounts::BaseCon
     agent_ids = agent_ids.inject(:&)
     agents = Current.account.users.where(id: agent_ids)
     @assignable_agents = (agents + Current.account.administrators).uniq
+    @agent_bots = @include_agent_bots ? AgentBot.accessible_to(Current.account) : []
   end
 
   private
diff --git a/app/javascript/dashboard/api/assignableAgents.js b/app/javascript/dashboard/api/assignableAgents.js
index 5b999facf..febb05ff9 100644
--- a/app/javascript/dashboard/api/assignableAgents.js
+++ b/app/javascript/dashboard/api/assignableAgents.js
@@ -6,9 +6,12 @@ class AssignableAgents extends ApiClient {
     super('assignable_agents', { accountScoped: true });
   }
 
-  get(inboxIds) {
+  get(inboxIds, { includeAgentBots = false } = {}) {
     return axios.get(this.url, {
-      params: { inbox_ids: inboxIds },
+      params: {
+        inbox_ids: inboxIds,
+        ...(includeAgentBots ? { include_agent_bots: true } : {}),
+      },
     });
   }
 }
diff --git a/app/javascript/dashboard/api/inbox/conversation.js b/app/javascript/dashboard/api/inbox/conversation.js
index f94fca452..08820aac9 100644
--- a/app/javascript/dashboard/api/inbox/conversation.js
+++ b/app/javascript/dashboard/api/inbox/conversation.js
@@ -62,9 +62,10 @@ class ConversationApi extends ApiClient {
     });
   }
 
-  assignAgent({ conversationId, agentId }) {
+  assignAgent({ conversationId, agentId, assigneeType }) {
     return axios.post(`${this.url}/${conversationId}/assignments`, {
       assignee_id: agentId,
+      assignee_type: assigneeType,
     });
   }
 
diff --git a/app/javascript/dashboard/api/specs/assignableAgents.spec.js b/app/javascript/dashboard/api/specs/assignableAgents.spec.js
index d553d55cb..be00cf07f 100644
--- a/app/javascript/dashboard/api/specs/assignableAgents.spec.js
+++ b/app/javascript/dashboard/api/specs/assignableAgents.spec.js
@@ -26,5 +26,15 @@ describe('#AssignableAgentsAPI', () => {
         },
       });
     });
+
+    it('#getAssignableAgents with agent bots', () => {
+      assignableAgentsAPI.get([1], { includeAgentBots: true });
+      expect(axiosMock.get).toHaveBeenCalledWith('/api/v1/assignable_agents', {
+        params: {
+          inbox_ids: [1],
+          include_agent_bots: true,
+        },
+      });
+    });
   });
 });
diff --git a/app/javascript/dashboard/api/specs/inbox/conversation.spec.js b/app/javascript/dashboard/api/specs/inbox/conversation.spec.js
index de0d7a7d0..ea0ef3e75 100644
--- a/app/javascript/dashboard/api/specs/inbox/conversation.spec.js
+++ b/app/javascript/dashboard/api/specs/inbox/conversation.spec.js
@@ -90,11 +90,16 @@ describe('#ConversationAPI', () => {
     });
 
     it('#assignAgent', () => {
-      conversationAPI.assignAgent({ conversationId: 12, agentId: 34 });
+      conversationAPI.assignAgent({
+        conversationId: 12,
+        agentId: 34,
+        assigneeType: 'AgentBot',
+      });
       expect(axiosMock.post).toHaveBeenCalledWith(
         `/api/v1/conversations/12/assignments`,
         {
           assignee_id: 34,
+          assignee_type: 'AgentBot',
         }
       );
     });
diff --git a/app/javascript/dashboard/components/widgets/conversation/ConversationBox.vue b/app/javascript/dashboard/components/widgets/conversation/ConversationBox.vue
index 7d04470ed..a9304eaba 100644
--- a/app/javascript/dashboard/components/widgets/conversation/ConversationBox.vue
+++ b/app/javascript/dashboard/components/widgets/conversation/ConversationBox.vue
@@ -62,7 +62,10 @@ export default {
       immediate: true,
       handler(inboxId) {
         if (inboxId) {
-          this.$store.dispatch('inboxAssignableAgents/fetch', [inboxId]);
+          this.$store.dispatch('inboxAssignableAgents/fetch', {
+            inboxIds: [inboxId],
+            includeAgentBots: true,
+          });
         }
       },
     },
diff --git a/app/javascript/dashboard/components/widgets/conversation/ConversationCard.vue b/app/javascript/dashboard/components/widgets/conversation/ConversationCard.vue
index a5dec806d..ca0d5fdf4 100644
--- a/app/javascript/dashboard/components/widgets/conversation/ConversationCard.vue
+++ b/app/javascript/dashboard/components/widgets/conversation/ConversationCard.vue
@@ -2,6 +2,7 @@
 import { computed, ref, watch } from 'vue';
 import { getLastMessage } from 'dashboard/helper/conversationHelper';
 import Avatar from 'next/avatar/Avatar.vue';
+import Icon from 'dashboard/components-next/icon/Icon.vue';
 import MessagePreview from './MessagePreview.vue';
 import InboxName from '../InboxName.vue';
 import TimeAgo from 'dashboard/components/ui/TimeAgo.vue';
@@ -57,6 +58,10 @@ const showMetaSection = computed(() => {
   );
 });
 
+const isAgentBotAssignee = computed(
+  () => props.chat?.meta?.assignee_type === 'AgentBot'
+);
+
 const hasSlaPolicyId = computed(
   () => props.chat?.applied_sla?.id && !props.currentContact?.blocked
 );
@@ -159,10 +164,15 @@ watch(
         >
           <span
             v-if="showAssignee && assignee.name"
-            class="text-n-slate-11 text-xs font-medium leading-3 py-0.5 px-0 inline-flex items-center truncate"
+            class="text-n-slate-11 text-xs font-medium leading-3 py-0.5 px-0 inline-flex items-center gap-px truncate"
           >
-            <fluent-icon icon="person" size="12" class="text-n-slate-11" />
-            {{ assignee.name }}
+            <Icon
+              :icon="
+                isAgentBotAssignee ? 'i-lucide-bot' : 'i-lucide-user-round'
+              "
+              class="size-3 text-n-slate-11 flex-shrink-0"
+            />
+            <span class="truncate">{{ assignee.name }}</span>
           </span>
           <CardPriorityIcon
             :priority="chat.priority"
diff --git a/app/javascript/dashboard/components/widgets/conversation/EmailTranscriptModal.vue b/app/javascript/dashboard/components/widgets/conversation/EmailTranscriptModal.vue
index bd0f645cf..4a9fb11f3 100644
--- a/app/javascript/dashboard/components/widgets/conversation/EmailTranscriptModal.vue
+++ b/app/javascript/dashboard/components/widgets/conversation/EmailTranscriptModal.vue
@@ -123,7 +123,13 @@ export default {
               $t('EMAIL_TRANSCRIPT.FORM.SEND_TO_CONTACT')
             }}</label>
           </div>
-          <div v-if="currentChat.meta.assignee" class="flex items-center gap-2">
+          <div
+            v-if="
+              currentChat.meta.assignee &&
+              currentChat.meta.assignee_type !== 'AgentBot'
+            "
+            class="flex items-center gap-2"
+          >
             <input
               id="assignee"
               v-model="selectedType"
diff --git a/app/javascript/dashboard/components/widgets/conversation/contextMenu/menuItem.vue b/app/javascript/dashboard/components/widgets/conversation/contextMenu/menuItem.vue
index ace2433ed..76e90de20 100644
--- a/app/javascript/dashboard/components/widgets/conversation/contextMenu/menuItem.vue
+++ b/app/javascript/dashboard/components/widgets/conversation/contextMenu/menuItem.vue
@@ -33,10 +33,19 @@ defineProps({
       v-if="variant === 'agent'"
       :name="option.label"
       :src="option.thumbnail"
+      :icon-name="option.iconName"
       :status="option.status === 'online' ? option.status : null"
       :size="20"
       class="flex-shrink-0"
-    />
+    >
+      <template v-if="option.iconName && option.thumbnail" #badge>
+        <div
+          class="absolute z-20 flex items-center justify-center rounded-full outline outline-1 outline-n-weak bg-n-solid-1 -bottom-0.5 ltr:-right-0.5 rtl:-left-0.5 size-3"
+        >
+          <Icon icon="i-lucide-bot" class="text-n-slate-11 size-2" />
+        </div>
+      </template>
+    </Avatar>
     <p class="menu-label truncate min-w-0 flex-1">
       {{ option.label }}
     </p>
diff --git a/app/javascript/dashboard/composables/spec/useAgentsList.spec.js b/app/javascript/dashboard/composables/spec/useAgentsList.spec.js
index 7f6d8e757..3a39a6be9 100644
--- a/app/javascript/dashboard/composables/spec/useAgentsList.spec.js
+++ b/app/javascript/dashboard/composables/spec/useAgentsList.spec.js
@@ -26,11 +26,12 @@ const mockNoneAgent = {
 };
 
 const mockUseMapGetter = (overrides = {}) => {
+  const getAssignableAgents = vi.fn(() => allAgentsData);
   const defaultGetters = {
     getCurrentUser: ref(allAgentsData[0]),
     getSelectedChat: ref({ inbox_id: 1, meta: { assignee: true } }),
     getCurrentAccountId: ref(1),
-    'inboxAssignableAgents/getAssignableAgents': ref(() => allAgentsData),
+    'inboxAssignableAgents/getAssignableAgents': ref(getAssignableAgents),
   };
 
   const mergedGetters = { ...defaultGetters, ...overrides };
@@ -53,6 +54,24 @@ describe('useAgentsList', () => {
     const { agentsList, assignableAgents } = useAgentsList();
 
     expect(assignableAgents.value).toEqual(allAgentsData);
+    expect(
+      useMapGetter('inboxAssignableAgents/getAssignableAgents').value
+    ).toHaveBeenCalledWith(1, { includeAgentBots: false });
+    expect(agentsList.value[0]).toEqual(mockNoneAgent);
+    expect(agentsList.value.length).toBe(
+      formattedAgentsData.slice(1).length + 1
+    );
+  });
+
+  it('requests agent bots when explicitly included', () => {
+    const { agentsList, assignableAgents } = useAgentsList(true, {
+      includeAgentBots: true,
+    });
+
+    expect(assignableAgents.value).toEqual(allAgentsData);
+    expect(
+      useMapGetter('inboxAssignableAgents/getAssignableAgents').value
+    ).toHaveBeenCalledWith(1, { includeAgentBots: true });
     expect(agentsList.value[0]).toEqual(mockNoneAgent);
     expect(agentsList.value.length).toBe(
       formattedAgentsData.slice(1).length + 1
diff --git a/app/javascript/dashboard/composables/useAgentsList.js b/app/javascript/dashboard/composables/useAgentsList.js
index 47e843be6..8e8ee5568 100644
--- a/app/javascript/dashboard/composables/useAgentsList.js
+++ b/app/javascript/dashboard/composables/useAgentsList.js
@@ -10,9 +10,14 @@ import {
  * A composable function that provides a list of agents for assignment.
  *
  * @param {boolean} [includeNoneAgent=true] - Whether to include a 'None' agent option.
+ * @param {Object} [options] - Options for the assignable agents list.
+ * @param {boolean} [options.includeAgentBots=false] - Whether to include AgentBot assignees. Only pass this from surfaces that thread `assignee_type` through the assignment request.
  * @returns {Object} An object containing the agents list and assignable agents.
  */
-export function useAgentsList(includeNoneAgent = true) {
+export function useAgentsList(
+  includeNoneAgent = true,
+  { includeAgentBots = false } = {}
+) {
   const { t } = useI18n();
   const currentUser = useMapGetter('getCurrentUser');
   const currentChat = useMapGetter('getSelectedChat');
@@ -39,7 +44,9 @@ export function useAgentsList(includeNoneAgent = true) {
    * @type {import('vue').ComputedRef<Array>}
    */
   const assignableAgents = computed(() => {
-    return inboxId.value ? assignable.value(inboxId.value) : [];
+    return inboxId.value
+      ? assignable.value(inboxId.value, { includeAgentBots })
+      : [];
   });
 
   /**
diff --git a/app/javascript/dashboard/helper/agentHelper.js b/app/javascript/dashboard/helper/agentHelper.js
index d521e7241..ff1123f66 100644
--- a/app/javascript/dashboard/helper/agentHelper.js
+++ b/app/javascript/dashboard/helper/agentHelper.js
@@ -38,7 +38,7 @@ export const getAgentsByUpdatedPresence = (
   currentAccountId
 ) => {
   const agentsWithDynamicPresenceUpdate = agents.map(item =>
-    item.id === currentUser.id
+    item.id === currentUser.id && (item.assignee_type || 'User') === 'User'
       ? {
           ...item,
           availability_status: currentUser.accounts.find(
diff --git a/app/javascript/dashboard/routes/dashboard/conversation/ConversationAction.vue b/app/javascript/dashboard/routes/dashboard/conversation/ConversationAction.vue
index fede6e3cb..1e33a192b 100644
--- a/app/javascript/dashboard/routes/dashboard/conversation/ConversationAction.vue
+++ b/app/javascript/dashboard/routes/dashboard/conversation/ConversationAction.vue
@@ -25,7 +25,7 @@ export default {
     },
   },
   setup() {
-    const { agentsList } = useAgentsList();
+    const { agentsList } = useAgentsList(true, { includeAgentBots: true });
     return {
       agentsList,
     };
@@ -81,18 +81,27 @@ export default {
     },
     assignedAgent: {
       get() {
-        return this.currentChat.meta.assignee;
+        const assignee = this.currentChat.meta.assignee;
+        return (
+          assignee && {
+            ...assignee,
+            assignee_type: this.currentChat.meta.assignee_type || 'User',
+          }
+        );
       },
       set(agent) {
         const agentId = agent ? agent.id : null;
+        const assigneeType = agent ? agent.assignee_type || 'User' : null;
         this.$store.dispatch('setCurrentChatAssignee', {
           conversationId: this.currentChat.id,
           assignee: agent,
+          assigneeType,
         });
         this.$store
           .dispatch('assignAgent', {
             conversationId: this.currentChat.id,
             agentId,
+            assigneeType,
           })
           .then(() => {
             useAlert(this.$t('CONVERSATION.CHANGE_AGENT'));
@@ -152,7 +161,10 @@ export default {
       if (!this.assignedAgent) {
         return true;
       }
-      if (this.assignedAgent.id !== this.currentUser.id) {
+      if (
+        this.assignedAgent.id !== this.currentUser.id ||
+        (this.assignedAgent.assignee_type || 'User') !== 'User'
+      ) {
         return true;
       }
       return false;
@@ -183,7 +195,11 @@ export default {
       this.assignedAgent = selfAssign;
     },
     onClickAssignAgent(selectedItem) {
-      if (this.assignedAgent && this.assignedAgent.id === selectedItem.id) {
+      if (
+        this.assignedAgent?.id === selectedItem.id &&
+        (this.assignedAgent?.assignee_type || 'User') ===
+          (selectedItem.assignee_type || 'User')
+      ) {
         this.assignedAgent = null;
       } else {
         this.assignedAgent = selectedItem;
diff --git a/app/javascript/dashboard/store/modules/conversations/actions.js b/app/javascript/dashboard/store/modules/conversations/actions.js
index 72ab8fa5e..f8fdecc36 100644
--- a/app/javascript/dashboard/store/modules/conversations/actions.js
+++ b/app/javascript/dashboard/store/modules/conversations/actions.js
@@ -208,23 +208,31 @@ const actions = {
     }
   },
 
-  assignAgent: async ({ dispatch }, { conversationId, agentId }) => {
+  assignAgent: async (
+    { dispatch },
+    { conversationId, agentId, assigneeType }
+  ) => {
     try {
       const response = await ConversationApi.assignAgent({
         conversationId,
         agentId,
+        assigneeType,
       });
       dispatch('setCurrentChatAssignee', {
         conversationId,
         assignee: response.data,
+        assigneeType,
       });
     } catch (error) {
       // Handle error
     }
   },
 
-  setCurrentChatAssignee({ commit }, { conversationId, assignee }) {
-    commit(types.ASSIGN_AGENT, { conversationId, assignee });
+  setCurrentChatAssignee(
+    { commit },
+    { conversationId, assignee, assigneeType }
+  ) {
+    commit(types.ASSIGN_AGENT, { conversationId, assignee, assigneeType });
   },
 
   assignTeam: async ({ dispatch }, { conversationId, teamId }) => {
diff --git a/app/javascript/dashboard/store/modules/conversations/index.js b/app/javascript/dashboard/store/modules/conversations/index.js
index 8a13940c0..4f539e22d 100644
--- a/app/javascript/dashboard/store/modules/conversations/index.js
+++ b/app/javascript/dashboard/store/modules/conversations/index.js
@@ -108,10 +108,11 @@ export const mutations = {
     }
   },
 
-  [types.ASSIGN_AGENT](_state, { conversationId, assignee }) {
+  [types.ASSIGN_AGENT](_state, { conversationId, assignee, assigneeType }) {
     const chat = getConversationById(_state)(conversationId);
     if (chat) {
       chat.meta.assignee = assignee;
+      chat.meta.assignee_type = assigneeType;
     }
   },
 
diff --git a/app/javascript/dashboard/store/modules/inboxAssignableAgents.js b/app/javascript/dashboard/store/modules/inboxAssignableAgents.js
index 1b129e3ef..6dbee9ea8 100644
--- a/app/javascript/dashboard/store/modules/inboxAssignableAgents.js
+++ b/app/javascript/dashboard/store/modules/inboxAssignableAgents.js
@@ -7,31 +7,52 @@ const state = {
   },
 };
 
+const recordKey = (inboxId, { includeAgentBots = false } = {}) =>
+  includeAgentBots ? `${inboxId}:with_agent_bots` : inboxId;
+
 export const types = {
   SET_INBOX_ASSIGNABLE_AGENTS_UI_FLAG: 'SET_INBOX_ASSIGNABLE_AGENTS_UI_FLAG',
   SET_INBOX_ASSIGNABLE_AGENTS: 'SET_INBOX_ASSIGNABLE_AGENTS',
 };
 
 export const getters = {
-  getAssignableAgents: $state => inboxId => {
-    const allAgents = $state.records[inboxId] || [];
-    const verifiedAgents = allAgents.filter(record => record.confirmed);
-    return verifiedAgents;
-  },
+  getAssignableAgents:
+    $state =>
+    (inboxId, options = {}) => {
+      const includeAgentBots = options.includeAgentBots || false;
+      const allAgents = $state.records[recordKey(inboxId, options)] || [];
+      const verifiedAgents = allAgents.filter(
+        record =>
+          record.confirmed ||
+          (includeAgentBots && record.assignee_type === 'AgentBot')
+      );
+      return verifiedAgents;
+    },
   getUIFlags($state) {
     return $state.uiFlags;
   },
 };
 
 export const actions = {
-  async fetch({ commit }, inboxIds) {
+  async fetch({ commit }, actionPayload) {
+    const inboxIds = Array.isArray(actionPayload)
+      ? actionPayload
+      : actionPayload.inboxIds;
+    const includeAgentBots =
+      !Array.isArray(actionPayload) && actionPayload.includeAgentBots;
     commit(types.SET_INBOX_ASSIGNABLE_AGENTS_UI_FLAG, { isFetching: true });
     try {
       const {
         data: { payload },
-      } = await AssignableAgentsAPI.get(inboxIds);
+      } = await AssignableAgentsAPI.get(inboxIds, { includeAgentBots });
+      if (includeAgentBots) {
+        commit(types.SET_INBOX_ASSIGNABLE_AGENTS, {
+          inboxId: inboxIds.join(','),
+          members: payload,
+        });
+      }
       commit(types.SET_INBOX_ASSIGNABLE_AGENTS, {
-        inboxId: inboxIds.join(','),
+        inboxId: recordKey(inboxIds.join(','), { includeAgentBots }),
         members: payload,
       });
     } catch (error) {
diff --git a/app/javascript/dashboard/store/modules/specs/conversations/actions.spec.js b/app/javascript/dashboard/store/modules/specs/conversations/actions.spec.js
index fa052ec1b..5014b63ca 100644
--- a/app/javascript/dashboard/store/modules/specs/conversations/actions.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/conversations/actions.spec.js
@@ -357,11 +357,12 @@ describe('#actions', () => {
       });
       await actions.assignAgent(
         { dispatch },
-        { conversationId: 1, agentId: 1 }
+        { conversationId: 1, agentId: 1, assigneeType: 'AgentBot' }
       );
       expect(dispatch).toHaveBeenCalledWith('setCurrentChatAssignee', {
         conversationId: 1,
         assignee: { id: 1, name: 'User' },
+        assigneeType: 'AgentBot',
       });
     });
   });
@@ -371,6 +372,7 @@ describe('#actions', () => {
       const payload = {
         conversationId: 1,
         assignee: { id: 1, name: 'User' },
+        assigneeType: 'AgentBot',
       };
       await actions.setCurrentChatAssignee({ commit }, payload);
       expect(commit).toHaveBeenCalledTimes(1);
diff --git a/app/javascript/dashboard/store/modules/specs/conversations/mutations.spec.js b/app/javascript/dashboard/store/modules/specs/conversations/mutations.spec.js
index fc1c61b35..a97bdad53 100644
--- a/app/javascript/dashboard/store/modules/specs/conversations/mutations.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/conversations/mutations.spec.js
@@ -712,8 +712,10 @@ describe('#mutations', () => {
       mutations[types.ASSIGN_AGENT](state, {
         conversationId: 1,
         assignee,
+        assigneeType: 'AgentBot',
       });
       expect(state.allConversations[0].meta.assignee).toEqual(assignee);
+      expect(state.allConversations[0].meta.assignee_type).toEqual('AgentBot');
       expect(state.allConversations[1].meta.assignee).toBeUndefined();
     });
   });
diff --git a/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/actions.spec.js b/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/actions.spec.js
index eac8e7d08..bda8f1c6e 100644
--- a/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/actions.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/actions.spec.js
@@ -7,12 +7,21 @@ global.axios = axios;
 vi.mock('axios');
 
 describe('#actions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
   describe('#fetch', () => {
     it('sends correct actions if API is success', async () => {
       axios.get.mockResolvedValue({
         data: { payload: agentsData },
       });
       await actions.fetch({ commit }, [1]);
+      expect(axios.get).toHaveBeenCalledWith('/api/v1/assignable_agents', {
+        params: {
+          inbox_ids: [1],
+        },
+      });
       expect(commit.mock.calls).toEqual([
         [types.SET_INBOX_ASSIGNABLE_AGENTS_UI_FLAG, { isFetching: true }],
         [
@@ -24,13 +33,37 @@ describe('#actions', () => {
     });
     it('sends correct actions if API is error', async () => {
       axios.get.mockRejectedValue({ message: 'Incorrect header' });
-      await expect(actions.fetch({ commit }, { inboxId: 1 })).rejects.toThrow(
-        Error
-      );
+      await expect(actions.fetch({ commit }, [1])).rejects.toThrow(Error);
       expect(commit.mock.calls).toEqual([
         [types.SET_INBOX_ASSIGNABLE_AGENTS_UI_FLAG, { isFetching: true }],
         [types.SET_INBOX_ASSIGNABLE_AGENTS_UI_FLAG, { isFetching: false }],
       ]);
     });
+
+    it('requests agent bots only when opted in', async () => {
+      axios.get.mockResolvedValue({
+        data: { payload: agentsData },
+      });
+
+      await actions.fetch(
+        { commit },
+        { inboxIds: [1], includeAgentBots: true }
+      );
+
+      expect(axios.get).toHaveBeenCalledWith('/api/v1/assignable_agents', {
+        params: {
+          inbox_ids: [1],
+          include_agent_bots: true,
+        },
+      });
+      expect(commit).toHaveBeenCalledWith(types.SET_INBOX_ASSIGNABLE_AGENTS, {
+        inboxId: '1',
+        members: agentsData,
+      });
+      expect(commit).toHaveBeenCalledWith(types.SET_INBOX_ASSIGNABLE_AGENTS, {
+        inboxId: '1:with_agent_bots',
+        members: agentsData,
+      });
+    });
   });
 });
diff --git a/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/getters.spec.js b/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/getters.spec.js
index ac287e2b2..744bcbccf 100644
--- a/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/getters.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/inboxAssignableMembers/getters.spec.js
@@ -1,4 +1,4 @@
-import { getters } from '../../teamMembers';
+import { getters } from '../../inboxAssignableAgents';
 import agentsData from './fixtures';
 
 describe('#getters', () => {
@@ -8,7 +8,26 @@ describe('#getters', () => {
         1: [agentsData[0]],
       },
     };
-    expect(getters.getTeamMembers(state)(1)).toEqual([agentsData[0]]);
+    expect(getters.getAssignableAgents(state)(1)).toEqual([agentsData[0]]);
+  });
+
+  it('keeps agent bots scoped to bot-inclusive lists', () => {
+    const agentBot = {
+      id: 1,
+      name: 'Captain',
+      assignee_type: 'AgentBot',
+    };
+    const state = {
+      records: {
+        1: [agentBot, agentsData[0]],
+        '1:with_agent_bots': [agentBot, agentsData[0]],
+      },
+    };
+
+    expect(getters.getAssignableAgents(state)(1)).toEqual([agentsData[0]]);
+    expect(
+      getters.getAssignableAgents(state)(1, { includeAgentBots: true })
+    ).toEqual([agentBot, agentsData[0]]);
   });
 
   it('getUIFlags', () => {
diff --git a/app/javascript/shared/components/ui/MultiselectDropdown.vue b/app/javascript/shared/components/ui/MultiselectDropdown.vue
index 898f89db4..0f775c679 100644
--- a/app/javascript/shared/components/ui/MultiselectDropdown.vue
+++ b/app/javascript/shared/components/ui/MultiselectDropdown.vue
@@ -63,6 +63,14 @@ const hasValue = computed(() => {
 const hasIcon = computed(() => {
   return props.selectedItem?.icon || false;
 });
+
+const isAgentBot = computed(
+  () => props.selectedItem?.assignee_type === 'AgentBot'
+);
+
+const selectedThumbnail = computed(
+  () => props.selectedItem?.thumbnail || props.selectedItem?.avatar_url
+);
 </script>
 
 <template>
@@ -93,16 +101,25 @@ const hasIcon = computed(() => {
           </h4>
         </div>
         <Avatar
-          v-if="hasValue && hasThumbnail && !hasIcon"
-          :src="selectedItem.thumbnail"
+          v-if="hasValue && hasThumbnail && (isAgentBot || !hasIcon)"
+          :src="selectedThumbnail"
           :status="selectedItem.availability_status"
           :name="selectedItem.name"
+          :icon-name="isAgentBot ? 'i-lucide-bot' : undefined"
           :size="24"
           hide-offline-status
           rounded-full
-        />
+        >
+          <template v-if="isAgentBot && selectedThumbnail" #badge>
+            <div
+              class="absolute z-20 flex items-center justify-center rounded-full outline outline-1 outline-n-weak bg-n-solid-1 -bottom-0.5 ltr:-right-0.5 rtl:-left-0.5 size-3.5"
+            >
+              <Icon icon="i-lucide-bot" class="text-n-slate-11 size-2.5" />
+            </div>
+          </template>
+        </Avatar>
         <div
-          v-if="hasValue && hasIcon && showEmojiIcon"
+          v-else-if="hasValue && hasIcon && showEmojiIcon"
           class="flex items-center justify-center flex-shrink-0 text-sm rounded-full size-6 outline outline-1 -outline-offset-1 outline-n-weak"
         >
           <EmojiIcon
diff --git a/app/javascript/shared/components/ui/MultiselectDropdownItems.vue b/app/javascript/shared/components/ui/MultiselectDropdownItems.vue
index 4fdb9cdb3..36554aadb 100644
--- a/app/javascript/shared/components/ui/MultiselectDropdownItems.vue
+++ b/app/javascript/shared/components/ui/MultiselectDropdownItems.vue
@@ -73,7 +73,13 @@ export default {
       this.$refs.searchbar.focus();
     },
     isActive(option) {
-      return this.selectedItems.some(item => item && option.id === item.id);
+      return this.selectedItems.some(item => {
+        if (!item || option.id !== item.id) return false;
+
+        return (
+          (option.assignee_type || 'User') === (item.assignee_type || 'User')
+        );
+      });
     },
   },
 };
@@ -94,7 +100,10 @@ export default {
     <div class="flex items-start justify-start flex-auto overflow-auto mt-2">
       <div class="w-full max-h-[10rem]">
         <WootDropdownMenu>
-          <WootDropdownItem v-for="option in filteredOptions" :key="option.id">
+          <WootDropdownItem
+            v-for="option in filteredOptions"
+            :key="`${option.assignee_type || 'User'}-${option.id}`"
+          >
             <NextButton
               slate
               :variant="isActive(option) ? 'faded' : 'ghost'"
@@ -114,16 +123,38 @@ export default {
                 </span>
               </div>
               <Avatar
-                v-if="hasThumbnail && !option.icon"
+                v-if="
+                  hasThumbnail &&
+                  (!option.icon || option.assignee_type === 'AgentBot')
+                "
                 :src="option.thumbnail"
                 :name="option.name"
                 :status="option.availability_status"
+                :icon-name="
+                  option.assignee_type === 'AgentBot'
+                    ? 'i-lucide-bot'
+                    : undefined
+                "
                 :size="24"
                 hide-offline-status
                 rounded-full
-              />
+              >
+                <template
+                  v-if="option.assignee_type === 'AgentBot' && option.thumbnail"
+                  #badge
+                >
+                  <div
+                    class="absolute z-20 flex items-center justify-center rounded-full outline outline-1 outline-n-weak bg-n-solid-1 -bottom-0.5 ltr:-right-0.5 rtl:-left-0.5 size-3.5"
+                  >
+                    <Icon
+                      icon="i-lucide-bot"
+                      class="text-n-slate-11 size-2.5"
+                    />
+                  </div>
+                </template>
+              </Avatar>
               <div
-                v-if="option.icon && showEmojiIcon"
+                v-else-if="option.icon && showEmojiIcon"
                 class="flex items-center justify-center flex-shrink-0 text-sm rounded-full size-6 outline outline-1 -outline-offset-1 outline-n-weak"
               >
                 <EmojiIcon
diff --git a/app/views/api/v1/accounts/assignable_agents/index.json.jbuilder b/app/views/api/v1/accounts/assignable_agents/index.json.jbuilder
index 295c5cef9..1a00c7122 100644
--- a/app/views/api/v1/accounts/assignable_agents/index.json.jbuilder
+++ b/app/views/api/v1/accounts/assignable_agents/index.json.jbuilder
@@ -1,5 +1,16 @@
 json.payload do
-  json.array! @assignable_agents do |agent|
-    json.partial! 'api/v1/models/agent', formats: [:json], resource: agent
+  owners = @assignable_agents.map { |agent| { type: 'User', resource: agent } }
+  owners += @agent_bots.map { |agent_bot| { type: 'AgentBot', resource: agent_bot } }
+
+  json.array! owners do |owner|
+    if owner[:type] == 'User'
+      json.partial! 'api/v1/models/agent', formats: [:json], resource: owner[:resource]
+      json.assignee_type 'User' if @include_agent_bots
+    else
+      json.partial! 'api/v1/models/agent_bot_slim', formats: [:json], resource: owner[:resource]
+      json.assignee_type 'AgentBot'
+      json.icon 'i-lucide-bot'
+      json.availability_status 'offline'
+    end
   end
 end
diff --git a/spec/controllers/api/v1/accounts/assignable_agents_controller_spec.rb b/spec/controllers/api/v1/accounts/assignable_agents_controller_spec.rb
index 6f1a068ee..3b6ff2393 100644
--- a/spec/controllers/api/v1/accounts/assignable_agents_controller_spec.rb
+++ b/spec/controllers/api/v1/accounts/assignable_agents_controller_spec.rb
@@ -62,6 +62,24 @@ RSpec.describe 'Assignable Agents API', type: :request do
         expect(response_data.size).to eq(2)
         expect(response_data.pluck(:role)).to include('agent', 'administrator')
       end
+
+      context 'with Agent Bots' do
+        let!(:account_bot) { create(:agent_bot, account: account, name: 'Account bot') }
+        let!(:global_bot) { create(:agent_bot, account: nil, name: 'Global bot') }
+
+        it 'returns assignable agents and accessible agent bots' do
+          get "/api/v1/accounts/#{account.id}/assignable_agents",
+              params: { inbox_ids: [inbox1.id, inbox2.id], include_agent_bots: true },
+              headers: agent1.create_new_auth_token,
+              as: :json
+
+          expect(response).to have_http_status(:success)
+
+          response_data = response.parsed_body['payload']
+          expect(response_data.pluck('assignee_type')).to include('User', 'AgentBot')
+          expect(response_data.pluck('name')).to include(agent1.name, admin.name, account_bot.name, global_bot.name)
+        end
+      end
     end
   end
 end

From eab859cd047502a0820c13761b3a6b50cf549b69 Mon Sep 17 00:00:00 2001
From: Sony Mathew <sony@chatwoot.com>
Date: Tue, 7 Jul 2026 16:20:52 +0530
Subject: [PATCH 03/17] fix: Sanitize query canceled API errors (#14933)

# Pull Request Template

## Description

Message creation API failures caused by PostgreSQL query cancellations
now return a generic retryable error instead of exposing raw database
internals such as `PG::QueryCanceled`, tuple identifiers, or relation
names to customers. Existing validation failures continue to return
their specific validation messages.

Closes
[CW-7538](https://linear.app/chatwoot/issue/CW-7538/do-not-expose-pgquerycanceled-details-in-messages-api-errors)

## Type of change

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality not to work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Reproduced the messages API path by raising
`ActiveRecord::QueryCanceled` from `Messages::MessageBuilder` and
verified the response contains the customer-safe localized error without
`PG::QueryCanceled` details.

Validation run locally:

- `bundle exec rspec
spec/controllers/api/v1/accounts/conversations/messages_controller_spec.rb`
- `bundle exec rubocop
app/controllers/concerns/request_exception_handler.rb
spec/controllers/api/v1/accounts/conversations/messages_controller_spec.rb`
- `git diff --check`

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules
---
 .../concerns/request_exception_handler.rb     | 26 ++++++++++++++++++-
 config/locales/en.yml                         |  2 ++
 .../conversations/messages_controller_spec.rb | 16 ++++++++++++
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/app/controllers/concerns/request_exception_handler.rb b/app/controllers/concerns/request_exception_handler.rb
index ccab0090a..7f4e313b1 100644
--- a/app/controllers/concerns/request_exception_handler.rb
+++ b/app/controllers/concerns/request_exception_handler.rb
@@ -1,6 +1,12 @@
 module RequestExceptionHandler
   extend ActiveSupport::Concern
 
+  QUERY_CANCELED_ERROR_MESSAGE_PATTERNS = [
+    'ActiveRecord::QueryCanceled',
+    'PG::QueryCanceled',
+    'canceling statement due to statement timeout'
+  ].freeze
+
   included do
     rescue_from ActiveRecord::RecordInvalid, with: :render_record_invalid
   end
@@ -18,6 +24,9 @@ module RequestExceptionHandler
   rescue ActionController::ParameterMissing => e
     log_handled_error(e)
     render_could_not_create_error(e.message)
+  rescue ActiveRecord::QueryCanceled => e
+    log_handled_error(e)
+    render_could_not_create_error(database_query_canceled_message)
   ensure
     # to address the thread variable leak issues in Puma/Thin webserver
     Current.reset
@@ -32,7 +41,7 @@ module RequestExceptionHandler
   end
 
   def render_could_not_create_error(message)
-    render json: { error: message }, status: :unprocessable_entity
+    render json: { error: sanitized_error_message(message) }, status: :unprocessable_entity
   end
 
   def render_payment_required(message)
@@ -59,4 +68,19 @@ module RequestExceptionHandler
   def log_handled_error(exception)
     logger.info("Handled error: #{exception.inspect}")
   end
+
+  def sanitized_error_message(message)
+    return database_query_canceled_message if database_query_canceled_message?(message)
+
+    message
+  end
+
+  def database_query_canceled_message?(message)
+    error_message = message.to_s
+    QUERY_CANCELED_ERROR_MESSAGE_PATTERNS.any? { |pattern| error_message.include?(pattern) }
+  end
+
+  def database_query_canceled_message
+    I18n.t('errors.database.query_canceled')
+  end
 end
diff --git a/config/locales/en.yml b/config/locales/en.yml
index 7aafbef0a..42758ad1f 100644
--- a/config/locales/en.yml
+++ b/config/locales/en.yml
@@ -82,6 +82,8 @@ en:
       file_too_large: 'File exceeds the maximum allowed size'
       unsupported_content_type: 'File type not supported (only images and videos are allowed)'
       unexpected: 'An unexpected error occurred'
+    database:
+      query_canceled: 'The request took too long to complete. Please try again.'
     saml:
       feature_not_enabled: SAML feature not enabled for this account
       sso_not_enabled: SAML SSO is not enabled for this installation
diff --git a/spec/controllers/api/v1/accounts/conversations/messages_controller_spec.rb b/spec/controllers/api/v1/accounts/conversations/messages_controller_spec.rb
index 9ab8d7316..766fd3b6b 100644
--- a/spec/controllers/api/v1/accounts/conversations/messages_controller_spec.rb
+++ b/spec/controllers/api/v1/accounts/conversations/messages_controller_spec.rb
@@ -51,6 +51,22 @@ RSpec.describe 'Conversation Messages API', type: :request do
         expect(json_response['error']).to eq('Validation failed: Content is too long (maximum is 150000 characters)')
       end
 
+      it 'returns a customer-safe error when the database query is canceled' do
+        message_builder = instance_double(Messages::MessageBuilder)
+        allow(Messages::MessageBuilder).to receive(:new).and_return(message_builder)
+        allow(message_builder).to receive(:perform)
+          .and_raise(ActiveRecord::QueryCanceled, 'PG::QueryCanceled: ERROR: canceling statement due to statement timeout')
+
+        post api_v1_account_conversation_messages_url(account_id: account.id, conversation_id: conversation.display_id),
+             params: { content: 'test-message', private: true },
+             headers: agent.create_new_auth_token,
+             as: :json
+
+        expect(response).to have_http_status(:unprocessable_entity)
+        expect(response.parsed_body['error']).to eq(I18n.t('errors.database.query_canceled'))
+        expect(response.parsed_body['error']).not_to include('PG::QueryCanceled')
+      end
+
       it 'creates an outgoing text message with a specific bot sender' do
         agent_bot = create(:agent_bot)
         time_stamp = Time.now.utc.to_s

From 83dda621c580e8531ff1a666a1a1a48d2992bad8 Mon Sep 17 00:00:00 2001
From: Aakash Bakhle <48802744+aakashb95@users.noreply.github.com>
Date: Tue, 7 Jul 2026 16:21:51 +0530
Subject: [PATCH 04/17] feat: default new accounts to captain v2 (#14917)

# Pull Request Template

## Description

defaults new accounts to captain v2

## Type of change

- [x] New feature (non-breaking change which adds functionality)

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. Please also list any relevant details
for your test configuration.

locally and specs

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream
modules
---
 .../captain/preferences_controller.rb         |  7 +++
 .../fields/captain_model_overrides_field.rb   |  2 +
 enterprise/app/models/concerns/agentable.rb   |  2 +-
 enterprise/app/models/enterprise/account.rb   | 14 ++++++
 .../reconcile_plan_features_service.rb        |  6 +++
 .../app/services/llm/base_ai_service.rb       |  6 ++-
 enterprise/config/premium_features.yml        |  1 +
 lib/llm/feature_router.rb                     | 10 +++++
 .../captain/preferences_controller_spec.rb    | 44 +++++++++++++++++++
 .../super_admin/accounts_controller_spec.rb   | 18 +++++++-
 spec/enterprise/models/account_spec.rb        | 31 +++++++++++++
 .../models/concerns/agentable_spec.rb         |  8 ++++
 .../handle_stripe_event_service_spec.rb       | 25 +++++++++++
 .../reconcile_plan_config_service_spec.rb     | 20 +++++----
 .../services/llm/base_ai_service_spec.rb      |  8 ++++
 spec/lib/llm/feature_router_spec.rb           | 26 +++++++++++
 spec/models/account_spec.rb                   | 26 +++++++++++
 .../concerns/captain_featurable_spec.rb       |  9 ----
 18 files changed, 243 insertions(+), 20 deletions(-)

diff --git a/app/controllers/api/v1/accounts/captain/preferences_controller.rb b/app/controllers/api/v1/accounts/captain/preferences_controller.rb
index 04eeff92b..482b001d6 100644
--- a/app/controllers/api/v1/accounts/captain/preferences_controller.rb
+++ b/app/controllers/api/v1/accounts/captain/preferences_controller.rb
@@ -66,6 +66,7 @@ class Api::V1::Accounts::Captain::PreferencesController < Api::V1::Accounts::Bas
       config = Llm::Models.feature_config(feature_key)
       route = Llm::FeatureRouter.resolve(feature: feature_key, account: Current.account)
       config.merge(
+        default: default_model_for(feature_key),
         enabled: account_features[feature_key] == true,
         model: route[:model],
         selected: route[:model],
@@ -74,4 +75,10 @@ class Api::V1::Accounts::Captain::PreferencesController < Api::V1::Accounts::Bas
       )
     end
   end
+
+  def default_model_for(feature_key)
+    return Llm::FeatureRouter::CAPTAIN_V2_ASSISTANT_MODEL if feature_key == 'assistant' && Current.account.feature_enabled?('captain_integration_v2')
+
+    Llm::Models.default_model_for(feature_key)
+  end
 end
diff --git a/enterprise/app/fields/captain_model_overrides_field.rb b/enterprise/app/fields/captain_model_overrides_field.rb
index a8f3fe399..c361d511a 100644
--- a/enterprise/app/fields/captain_model_overrides_field.rb
+++ b/enterprise/app/fields/captain_model_overrides_field.rb
@@ -29,6 +29,8 @@ class CaptainModelOverridesField < Administrate::Field::Base
   end
 
   def default_model_id(feature_key)
+    return Llm::FeatureRouter::CAPTAIN_V2_ASSISTANT_MODEL if feature_key == 'assistant' && resource.feature_enabled?('captain_integration_v2')
+
     Llm::Models.default_model_for(feature_key)
   end
 
diff --git a/enterprise/app/models/concerns/agentable.rb b/enterprise/app/models/concerns/agentable.rb
index b5a6cd1b9..086deedc1 100644
--- a/enterprise/app/models/concerns/agentable.rb
+++ b/enterprise/app/models/concerns/agentable.rb
@@ -47,7 +47,7 @@ module Concerns::Agentable
 
   def agent_model
     route = Llm::FeatureRouter.resolve(feature: 'assistant', account: account)
-    return route[:model] if route[:source] == :account_override
+    return route[:model] if route[:source] == :account_override || account&.feature_enabled?('captain_integration_v2')
 
     installation_model.presence || route[:model]
   end
diff --git a/enterprise/app/models/enterprise/account.rb b/enterprise/app/models/enterprise/account.rb
index fcfe90777..62898803a 100644
--- a/enterprise/app/models/enterprise/account.rb
+++ b/enterprise/app/models/enterprise/account.rb
@@ -1,4 +1,9 @@
 module Enterprise::Account
+  # Transitional marker for the Captain V1 to V2 rollout. New cloud accounts get
+  # this marker so plan reconciliation can enable V2 for them without upgrading
+  # existing paid accounts. Remove once every account is migrated to V2.
+  CAPTAIN_V2_DEFAULT_ELIGIBLE = 'captain_v2_default_eligible'.freeze
+
   class << self
     def captain_document_sync_intervals
       parse_captain_document_sync_intervals(InstallationConfig.find_by(name: 'CAPTAIN_DOCUMENT_AUTO_SYNC_INTERVALS')&.value)
@@ -94,6 +99,15 @@ module Enterprise::Account
 
   private
 
+  def enable_default_features
+    super
+    if ChatwootApp.self_hosted_enterprise?
+      enable_features('captain_integration', 'captain_integration_v2')
+    elsif ChatwootApp.chatwoot_cloud?
+      internal_attributes[CAPTAIN_V2_DEFAULT_ELIGIBLE] = true
+    end
+  end
+
   def sync_assignment_features
     if feature_enabled?('assignment_v2')
       # Enable advanced_assignment for Business/Enterprise plans
diff --git a/enterprise/app/services/enterprise/billing/reconcile_plan_features_service.rb b/enterprise/app/services/enterprise/billing/reconcile_plan_features_service.rb
index fea5b7664..205bc348e 100644
--- a/enterprise/app/services/enterprise/billing/reconcile_plan_features_service.rb
+++ b/enterprise/app/services/enterprise/billing/reconcile_plan_features_service.rb
@@ -36,7 +36,9 @@ class Enterprise::Billing::ReconcilePlanFeaturesService
 
   def perform
     account.disable_features(*PREMIUM_PLAN_FEATURES)
+    account.disable_features('captain_integration_v2') if default_plan?
     account.enable_features(*current_plan_features)
+    account.enable_features('captain_integration_v2') if captain_v2_default_eligible?
     account.enable_features(*manually_managed_features)
     account.save!
   end
@@ -69,4 +71,8 @@ class Enterprise::Billing::ReconcilePlanFeaturesService
   def manually_managed_features
     @manually_managed_features ||= Internal::Accounts::InternalAttributesService.new(account).manually_managed_features
   end
+
+  def captain_v2_default_eligible?
+    !default_plan? && account.internal_attributes[Enterprise::Account::CAPTAIN_V2_DEFAULT_ELIGIBLE] == true
+  end
 end
diff --git a/enterprise/app/services/llm/base_ai_service.rb b/enterprise/app/services/llm/base_ai_service.rb
index bec3b5cb9..a84060775 100644
--- a/enterprise/app/services/llm/base_ai_service.rb
+++ b/enterprise/app/services/llm/base_ai_service.rb
@@ -34,7 +34,7 @@ class Llm::BaseAiService
 
   def setup_model
     route = feature_route
-    return @model = route[:model] if account_override_route?(route)
+    return @model = route[:model] if account_override_route?(route) || captain_v2_assistant?
 
     @model = @fallback_model.presence || installation_model.presence || route&.dig(:model) || DEFAULT_MODEL
   end
@@ -49,6 +49,10 @@ class Llm::BaseAiService
     route&.dig(:source) == :account_override
   end
 
+  def captain_v2_assistant?
+    @llm_feature.to_s == 'assistant' && @llm_account&.feature_enabled?('captain_integration_v2')
+  end
+
   def installation_model
     InstallationConfig.find_by(name: 'CAPTAIN_OPEN_AI_MODEL')&.value
   end
diff --git a/enterprise/config/premium_features.yml b/enterprise/config/premium_features.yml
index 282319fe7..260de1356 100644
--- a/enterprise/config/premium_features.yml
+++ b/enterprise/config/premium_features.yml
@@ -4,6 +4,7 @@
 - sla
 - custom_roles
 - captain_integration
+- captain_integration_v2
 - captain_document_auto_sync
 - csat_review_notes
 - conversation_required_attributes
diff --git a/lib/llm/feature_router.rb b/lib/llm/feature_router.rb
index da0aa56e9..d75b06dca 100644
--- a/lib/llm/feature_router.rb
+++ b/lib/llm/feature_router.rb
@@ -1,6 +1,8 @@
 module Llm::FeatureRouter
   class UnknownFeatureError < StandardError; end
 
+  CAPTAIN_V2_ASSISTANT_MODEL = 'gpt-5.2'.freeze
+
   class << self
     def resolve(feature:, account: nil)
       feature_key = feature.to_s
@@ -8,6 +10,7 @@ module Llm::FeatureRouter
 
       model = account_model_override(account, feature_key)
       source = model.present? ? :account_override : :default
+      model ||= captain_v2_assistant_model(account, feature_key)
       model ||= Llm::Models.default_model_for(feature_key)
 
       {
@@ -25,5 +28,12 @@ module Llm::FeatureRouter
       return unless model
       return model if Llm::Models.valid_model_for?(feature_key, model)
     end
+
+    def captain_v2_assistant_model(account, feature_key)
+      return unless feature_key == 'assistant'
+      return unless account&.feature_enabled?('captain_integration_v2')
+
+      CAPTAIN_V2_ASSISTANT_MODEL
+    end
   end
 end
diff --git a/spec/controllers/api/v1/accounts/captain/preferences_controller_spec.rb b/spec/controllers/api/v1/accounts/captain/preferences_controller_spec.rb
index dfc2e4ff0..db7ca93a5 100644
--- a/spec/controllers/api/v1/accounts/captain/preferences_controller_spec.rb
+++ b/spec/controllers/api/v1/accounts/captain/preferences_controller_spec.rb
@@ -67,6 +67,50 @@ RSpec.describe 'Api::V1::Accounts::Captain::Preferences', type: :request do
           source: 'default'
         )
       end
+
+      it 'returns the assistant YAML default for V1 accounts' do
+        get "/api/v1/accounts/#{account.id}/captain/preferences",
+            headers: admin.create_new_auth_token,
+            as: :json
+
+        expect(response).to have_http_status(:success)
+        expect(json_response.dig(:features, :assistant)).to include(
+          default: Llm::Models.default_model_for('assistant'),
+          selected: Llm::Models.default_model_for('assistant'),
+          source: 'default'
+        )
+      end
+
+      it 'returns GPT-5.2 as the assistant default for V2 accounts' do
+        account.enable_features!('captain_integration_v2')
+
+        get "/api/v1/accounts/#{account.id}/captain/preferences",
+            headers: admin.create_new_auth_token,
+            as: :json
+
+        expect(response).to have_http_status(:success)
+        expect(json_response.dig(:features, :assistant)).to include(
+          default: Llm::FeatureRouter::CAPTAIN_V2_ASSISTANT_MODEL,
+          selected: Llm::FeatureRouter::CAPTAIN_V2_ASSISTANT_MODEL,
+          source: 'default'
+        )
+      end
+
+      it 'keeps the V2 assistant default when an account override is selected' do
+        account.enable_features!('captain_integration_v2')
+        account.update!(captain_models: { 'assistant' => 'gpt-5.1' })
+
+        get "/api/v1/accounts/#{account.id}/captain/preferences",
+            headers: admin.create_new_auth_token,
+            as: :json
+
+        expect(response).to have_http_status(:success)
+        expect(json_response.dig(:features, :assistant)).to include(
+          default: Llm::FeatureRouter::CAPTAIN_V2_ASSISTANT_MODEL,
+          selected: 'gpt-5.1',
+          source: 'account_override'
+        )
+      end
     end
   end
 
diff --git a/spec/controllers/super_admin/accounts_controller_spec.rb b/spec/controllers/super_admin/accounts_controller_spec.rb
index b2f4ff405..366e178cd 100644
--- a/spec/controllers/super_admin/accounts_controller_spec.rb
+++ b/spec/controllers/super_admin/accounts_controller_spec.rb
@@ -65,6 +65,21 @@ RSpec.describe 'Super Admin accounts API', type: :request do
 
         expect(editor_select.at_css('option[value=""]').text.squish).to eq("Use default: #{default_model} (#{default_model_id})")
       end
+
+      it 'shows the Captain V2 assistant default in the model selector', if: ChatwootApp.enterprise? do
+        account.enable_features!('captain_integration_v2')
+        sign_in(super_admin, scope: :super_admin)
+
+        get "/super_admin/accounts/#{account.id}/edit"
+
+        document = Nokogiri::HTML(response.body)
+        assistant_select = document.at_css('select[name="account[captain_models][assistant]"]')
+        default_model_id = Llm::FeatureRouter::CAPTAIN_V2_ASSISTANT_MODEL
+        default_model = Llm::Models.model_config(default_model_id)['display_name']
+
+        expect(response).to have_http_status(:success)
+        expect(assistant_select.at_css('option[value=""]').text.squish).to eq("Use default: #{default_model} (#{default_model_id})")
+      end
     end
   end
 
@@ -97,6 +112,7 @@ RSpec.describe 'Super Admin accounts API', type: :request do
 
       it 'rejects invalid Captain model overrides' do
         sign_in(super_admin, scope: :super_admin)
+        existing_captain_models = account.captain_models
 
         patch "/super_admin/accounts/#{account.id}",
               params: {
@@ -112,7 +128,7 @@ RSpec.describe 'Super Admin accounts API', type: :request do
 
         expect(response).to have_http_status(:unprocessable_entity)
         expect(response.body).to include('not a valid model for label_suggestion')
-        expect(account.reload.captain_models).to be_nil
+        expect(account.reload.captain_models).to eq(existing_captain_models)
       end
     end
   end
diff --git a/spec/enterprise/models/account_spec.rb b/spec/enterprise/models/account_spec.rb
index c69a83256..03f3b8d37 100644
--- a/spec/enterprise/models/account_spec.rb
+++ b/spec/enterprise/models/account_spec.rb
@@ -222,6 +222,37 @@ RSpec.describe Account, type: :model do
     end
   end
 
+  describe 'default features' do
+    before do
+      InstallationConfig.find_or_initialize_by(name: 'ACCOUNT_LEVEL_FEATURE_DEFAULTS').update!(
+        value: Featurable::FEATURE_LIST,
+        locked: true
+      )
+    end
+
+    it 'enables Captain V2 for new self-hosted enterprise accounts' do
+      allow(ChatwootApp).to receive(:self_hosted_enterprise?).and_return(true)
+
+      account = create(:account)
+
+      expect(account).to be_feature_enabled('captain_integration')
+      expect(account).to be_feature_enabled('captain_integration_v2')
+      expect(account.captain_preferences[:models]['assistant']).to eq('gpt-5.2')
+      expect(account.captain_models).to be_nil
+    end
+
+    it 'marks new cloud accounts as eligible for the Captain V2 paid-plan default' do
+      allow(ChatwootApp).to receive(:self_hosted_enterprise?).and_return(false)
+      allow(ChatwootApp).to receive(:chatwoot_cloud?).and_return(true)
+
+      account = create(:account)
+
+      expect(account.internal_attributes[Enterprise::Account::CAPTAIN_V2_DEFAULT_ELIGIBLE]).to be true
+      expect(account).not_to be_feature_enabled('captain_integration')
+      expect(account).not_to be_feature_enabled('captain_integration_v2')
+    end
+  end
+
   describe 'captain document sync cadence' do
     let(:account) { create(:account) }
 
diff --git a/spec/enterprise/models/concerns/agentable_spec.rb b/spec/enterprise/models/concerns/agentable_spec.rb
index d179393c9..f2145ff85 100644
--- a/spec/enterprise/models/concerns/agentable_spec.rb
+++ b/spec/enterprise/models/concerns/agentable_spec.rb
@@ -179,6 +179,14 @@ RSpec.describe Concerns::Agentable do
       expect(dummy_instance.send(:agent_model)).to eq('gpt-4.1-nano')
     end
 
+    it 'returns the Captain V2 default when Captain V2 is enabled' do
+      create(:installation_config, name: 'CAPTAIN_OPEN_AI_MODEL', value: 'gpt-4.1-nano')
+      account.enable_features!('captain_integration_v2')
+
+      expect(dummy_instance.send(:agent_model)).to eq('gpt-5.2')
+      expect(account.reload.captain_models).to be_nil
+    end
+
     it 'returns the assistant feature default model when account is nil' do
       agent = dummy_class.new(account: nil)
 
diff --git a/spec/enterprise/services/enterprise/billing/handle_stripe_event_service_spec.rb b/spec/enterprise/services/enterprise/billing/handle_stripe_event_service_spec.rb
index 3223efa86..5116e1ec3 100644
--- a/spec/enterprise/services/enterprise/billing/handle_stripe_event_service_spec.rb
+++ b/spec/enterprise/services/enterprise/billing/handle_stripe_event_service_spec.rb
@@ -175,6 +175,7 @@ describe Enterprise::Billing::HandleStripeEventService do
         described_class::STARTUP_PLAN_FEATURES.each do |feature|
           account.enable_features(feature)
         end
+        account.enable_features('captain_integration_v2')
         account.enable_features(*described_class::BUSINESS_PLAN_FEATURES)
         account.enable_features(*described_class::ENTERPRISE_PLAN_FEATURES)
         account.save!
@@ -193,6 +194,7 @@ describe Enterprise::Billing::HandleStripeEventService do
         all_features.each do |feature|
           expect(account).not_to be_feature_enabled(feature)
         end
+        expect(account).not_to be_feature_enabled('captain_integration_v2')
       end
     end
 
@@ -218,6 +220,29 @@ describe Enterprise::Billing::HandleStripeEventService do
           expect(account).not_to be_feature_enabled(feature)
         end
       end
+
+      it 'does not enable Captain V2 for existing paid accounts during reconciliation' do
+        allow(subscription).to receive(:[]).with('plan')
+                                           .and_return({ 'id' => 'test', 'product' => 'plan_id_startups', 'name' => 'Startups' })
+
+        stripe_event_service.new.perform(event: event)
+
+        expect(account.reload).not_to be_feature_enabled('captain_integration_v2')
+      end
+
+      it 'enables Captain V2 for new cloud accounts marked as default eligible' do
+        account.update!(
+          internal_attributes: account.internal_attributes.merge(
+            Enterprise::Account::CAPTAIN_V2_DEFAULT_ELIGIBLE => true
+          )
+        )
+        allow(subscription).to receive(:[]).with('plan')
+                                           .and_return({ 'id' => 'test', 'product' => 'plan_id_startups', 'name' => 'Startups' })
+
+        stripe_event_service.new.perform(event: event)
+
+        expect(account.reload).to be_feature_enabled('captain_integration_v2')
+      end
     end
 
     context 'with Business plan' do
diff --git a/spec/enterprise/services/internal/reconcile_plan_config_service_spec.rb b/spec/enterprise/services/internal/reconcile_plan_config_service_spec.rb
index 63a318415..76e9e3602 100644
--- a/spec/enterprise/services/internal/reconcile_plan_config_service_spec.rb
+++ b/spec/enterprise/services/internal/reconcile_plan_config_service_spec.rb
@@ -11,14 +11,16 @@ RSpec.describe Internal::ReconcilePlanConfigService do
 
       it 'disables the premium features for accounts' do
         account = create(:account)
-        account.enable_features!('disable_branding', 'audit_logs', 'captain_integration')
+        account.enable_features!('disable_branding', 'audit_logs', 'captain_integration', 'captain_integration_v2')
         account_with_captain = create(:account)
-        account_with_captain.enable_features!('captain_integration')
+        account_with_captain.enable_features!('captain_integration', 'captain_integration_v2')
         disable_branding_account = create(:account)
         disable_branding_account.enable_features!('disable_branding')
         service.perform
-        expect(account.reload.enabled_features.keys).not_to include('captain_integration', 'disable_branding', 'audit_logs')
-        expect(account_with_captain.reload.enabled_features.keys).not_to include('captain_integration')
+        expect(account.reload.enabled_features.keys).not_to include(
+          'captain_integration', 'captain_integration_v2', 'disable_branding', 'audit_logs'
+        )
+        expect(account_with_captain.reload.enabled_features.keys).not_to include('captain_integration', 'captain_integration_v2')
         expect(disable_branding_account.reload.enabled_features.keys).not_to include('disable_branding')
       end
 
@@ -56,14 +58,16 @@ RSpec.describe Internal::ReconcilePlanConfigService do
 
       it 'does not disable the premium features for accounts' do
         account = create(:account)
-        account.enable_features!('disable_branding', 'audit_logs', 'captain_integration')
+        account.enable_features!('disable_branding', 'audit_logs', 'captain_integration', 'captain_integration_v2')
         account_with_captain = create(:account)
-        account_with_captain.enable_features!('captain_integration')
+        account_with_captain.enable_features!('captain_integration', 'captain_integration_v2')
         disable_branding_account = create(:account)
         disable_branding_account.enable_features!('disable_branding')
         service.perform
-        expect(account.reload.enabled_features.keys).to include('captain_integration', 'disable_branding', 'audit_logs')
-        expect(account_with_captain.reload.enabled_features.keys).to include('captain_integration')
+        expect(account.reload.enabled_features.keys).to include(
+          'captain_integration', 'captain_integration_v2', 'disable_branding', 'audit_logs'
+        )
+        expect(account_with_captain.reload.enabled_features.keys).to include('captain_integration', 'captain_integration_v2')
         expect(disable_branding_account.reload.enabled_features.keys).to include('disable_branding')
       end
 
diff --git a/spec/enterprise/services/llm/base_ai_service_spec.rb b/spec/enterprise/services/llm/base_ai_service_spec.rb
index f18752485..d4c07d336 100644
--- a/spec/enterprise/services/llm/base_ai_service_spec.rb
+++ b/spec/enterprise/services/llm/base_ai_service_spec.rb
@@ -30,6 +30,14 @@ RSpec.describe Llm::BaseAiService do
       expect(described_class.new(feature: 'assistant', account: account).model).to eq('gpt-4.1-nano')
     end
 
+    it 'uses the Captain V2 assistant default ahead of the installation model' do
+      create(:installation_config, name: 'CAPTAIN_OPEN_AI_MODEL', value: 'gpt-4.1-nano')
+      account.enable_features!('captain_integration_v2')
+
+      expect(described_class.new(feature: 'assistant', account: account).model).to eq('gpt-5.2')
+      expect(account.reload.captain_models).to be_nil
+    end
+
     it 'uses the feature default when feature context has no account override or installation model' do
       expect(described_class.new(feature: 'assistant', account: account).model).to eq(Llm::Models.default_model_for('assistant'))
     end
diff --git a/spec/lib/llm/feature_router_spec.rb b/spec/lib/llm/feature_router_spec.rb
index e0eb4afa0..ea2b9f91f 100644
--- a/spec/lib/llm/feature_router_spec.rb
+++ b/spec/lib/llm/feature_router_spec.rb
@@ -30,6 +30,32 @@ RSpec.describe Llm::FeatureRouter do
       )
     end
 
+    it 'resolves GPT-5.2 as the assistant default when Captain V2 is enabled without storing an account override' do
+      account.enable_features!('captain_integration_v2')
+
+      resolved = described_class.resolve(feature: 'assistant', account: account)
+
+      expect(resolved).to include(
+        feature: 'assistant',
+        provider: 'openai',
+        model: 'gpt-5.2',
+        source: :default
+      )
+      expect(account.reload.captain_models).to be_nil
+    end
+
+    it 'keeps account model overrides ahead of the Captain V2 default' do
+      account.enable_features!('captain_integration_v2')
+      account.update!(captain_models: { 'assistant' => 'gpt-5.1' })
+
+      resolved = described_class.resolve(feature: 'assistant', account: account)
+
+      expect(resolved).to include(
+        model: 'gpt-5.1',
+        source: :account_override
+      )
+    end
+
     it 'falls back to the feature default when the account override is invalid' do
       account.captain_models = { 'editor' => 'invalid-model' }
 
diff --git a/spec/models/account_spec.rb b/spec/models/account_spec.rb
index 56bd41f7c..e3bc636d1 100644
--- a/spec/models/account_spec.rb
+++ b/spec/models/account_spec.rb
@@ -50,6 +50,21 @@ RSpec.describe Account do
     end
   end
 
+  describe 'captain defaults for new accounts' do
+    it 'does not store Captain model overrides or enable premium Captain features' do
+      InstallationConfig.find_or_initialize_by(name: 'ACCOUNT_LEVEL_FEATURE_DEFAULTS').update!(
+        value: Featurable::FEATURE_LIST,
+        locked: true
+      )
+
+      account = create(:account)
+
+      expect(account).not_to be_feature_enabled('captain_integration')
+      expect(account).not_to be_feature_enabled('captain_integration_v2')
+      expect(account.captain_models).to be_nil
+    end
+  end
+
   describe 'conversation unread counts feature flag' do
     let(:account) { create(:account) }
     let(:inbox) { create(:inbox, account: account) }
@@ -337,6 +352,10 @@ RSpec.describe Account do
     let(:account) { create(:account) }
 
     describe 'with no saved preferences' do
+      before do
+        account.update!(captain_models: nil)
+      end
+
       it 'returns defaults from llm.yml' do
         prefs = account.captain_preferences
 
@@ -346,6 +365,13 @@ RSpec.describe Account do
           expect(prefs[:models][feature]).to eq(Llm::Models.default_model_for(feature))
         end
       end
+
+      it 'returns GPT-5.2 for assistant when Captain V2 is enabled' do
+        account.enable_features!('captain_integration_v2')
+
+        expect(account.captain_preferences[:models]['assistant']).to eq('gpt-5.2')
+        expect(account.reload.captain_models).to be_nil
+      end
     end
 
     describe 'with saved model preferences' do
diff --git a/spec/models/concerns/captain_featurable_spec.rb b/spec/models/concerns/captain_featurable_spec.rb
index 7221ad055..0fb145142 100644
--- a/spec/models/concerns/captain_featurable_spec.rb
+++ b/spec/models/concerns/captain_featurable_spec.rb
@@ -58,15 +58,6 @@ RSpec.describe CaptainFeaturable do
   end
 
   describe 'model accessor methods' do
-    context 'when no models are explicitly configured' do
-      it 'returns default models for all features' do
-        Llm::Models.feature_keys.each do |feature_key|
-          expected_default = Llm::Models.default_model_for(feature_key)
-          expect(account.send("captain_#{feature_key}_model")).to eq(expected_default)
-        end
-      end
-    end
-
     context 'when models are explicitly configured' do
       before do
         account.update!(captain_models: {

From c8bfbadae2afe5f758ffe98883ee5691d5d15370 Mon Sep 17 00:00:00 2001
From: Vishnu Narayanan <iamwishnu@gmail.com>
Date: Tue, 7 Jul 2026 16:40:19 +0530
Subject: [PATCH 05/17] fix: validate identifier hash on widget contact update
 (#14884)

## Description

The widget contact update endpoint (`PATCH /api/v1/widget/contact`)
applied updates that set an `identifier` without validating the
`identifier_hash`, unlike `set_user`, which already does. This change
runs the same validation on the update path whenever an `identifier` is
supplied, keeping identity validation consistent across the widget
contact endpoints.

Anonymous updates that don't pass an identifier (prechat
name/email/phone and custom attributes) keep working unchanged,
including on inboxes with mandatory identity validation.

Fixes https://linear.app/chatwoot/issue/CW-7118


---------

Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>
Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
---
 .../api/v1/widget/contacts_controller.rb      | 11 +++
 .../api/v1/widget/contacts_controller_spec.rb | 72 +++++++++++++++++++
 2 files changed, 83 insertions(+)

diff --git a/app/controllers/api/v1/widget/contacts_controller.rb b/app/controllers/api/v1/widget/contacts_controller.rb
index 6c595ab59..4094ceb24 100644
--- a/app/controllers/api/v1/widget/contacts_controller.rb
+++ b/app/controllers/api/v1/widget/contacts_controller.rb
@@ -2,6 +2,7 @@ class Api::V1::Widget::ContactsController < Api::V1::Widget::BaseController
   include WidgetHelper
 
   before_action :validate_hmac, only: [:set_user]
+  before_action :validate_hmac_for_identified_update, only: [:update]
 
   def show; end
 
@@ -46,6 +47,16 @@ class Api::V1::Widget::ContactsController < Api::V1::Widget::BaseController
     @contact.identifier.present? && @contact.identifier != permitted_params[:identifier]
   end
 
+  # The plain update endpoint is also used for anonymous prechat updates
+  # (name/email/phone/custom_attributes with no identifier), which must keep
+  # working on hmac_mandatory inboxes. Only the identity-binding path, where an
+  # identifier is supplied and the contact can be rebound, requires HMAC.
+  def validate_hmac_for_identified_update
+    return if params[:identifier].blank?
+
+    validate_hmac
+  end
+
   def validate_hmac
     return unless should_verify_hmac?
 
diff --git a/spec/controllers/api/v1/widget/contacts_controller_spec.rb b/spec/controllers/api/v1/widget/contacts_controller_spec.rb
index 7abbcf22e..1d1616d2e 100644
--- a/spec/controllers/api/v1/widget/contacts_controller_spec.rb
+++ b/spec/controllers/api/v1/widget/contacts_controller_spec.rb
@@ -116,6 +116,78 @@ RSpec.describe '/api/v1/widget/contacts', type: :request do
     end
   end
 
+  describe 'PATCH /api/v1/widget/contact with HMAC enforcement' do
+    let(:web_widget) { create(:channel_widget, account: account, hmac_mandatory: true) }
+    let!(:victim) { create(:contact, account: account, identifier: 'victim-identifier', name: 'Victim') }
+    let(:correct_identifier_hash) { OpenSSL::HMAC.hexdigest('sha256', web_widget.hmac_token, 'victim-identifier') }
+
+    context 'when an identifier is supplied on a mandatory-hmac inbox' do
+      it 'rejects when identifier_hash is omitted' do
+        patch '/api/v1/widget/contact',
+              params: { website_token: web_widget.website_token, identifier: 'victim-identifier', name: 'Attacker' },
+              headers: { 'X-Auth-Token' => token },
+              as: :json
+
+        expect(response).to have_http_status(:unauthorized)
+        expect(victim.reload.name).to eq('Victim')
+      end
+
+      it 'rejects when identifier_hash is blank' do
+        patch '/api/v1/widget/contact',
+              params: { website_token: web_widget.website_token, identifier: 'victim-identifier', identifier_hash: '', name: 'Attacker' },
+              headers: { 'X-Auth-Token' => token },
+              as: :json
+
+        expect(response).to have_http_status(:unauthorized)
+        expect(victim.reload.name).to eq('Victim')
+      end
+
+      it 'rejects when identifier_hash is null' do
+        patch '/api/v1/widget/contact',
+              params: { website_token: web_widget.website_token, identifier: 'victim-identifier', identifier_hash: nil, name: 'Attacker' },
+              headers: { 'X-Auth-Token' => token },
+              as: :json
+
+        expect(response).to have_http_status(:unauthorized)
+        expect(victim.reload.name).to eq('Victim')
+      end
+
+      it 'rejects when identifier_hash is invalid' do
+        patch '/api/v1/widget/contact',
+              params: { website_token: web_widget.website_token, identifier: 'victim-identifier',
+                        identifier_hash: 'DEFINITELY_INVALID_AAAAA_NOT_A_REAL_HMAC', name: 'Attacker' },
+              headers: { 'X-Auth-Token' => token },
+              as: :json
+
+        expect(response).to have_http_status(:unauthorized)
+        expect(victim.reload.name).to eq('Victim')
+      end
+
+      it 'succeeds when a valid identifier_hash is provided' do
+        patch '/api/v1/widget/contact',
+              params: { website_token: web_widget.website_token, identifier: 'victim-identifier',
+                        identifier_hash: correct_identifier_hash, name: 'Legit' },
+              headers: { 'X-Auth-Token' => token },
+              as: :json
+
+        expect(response).to have_http_status(:success)
+      end
+    end
+
+    context 'when no identifier is supplied (anonymous prechat update)' do
+      it 'allows updating name/email without an identifier_hash' do
+        patch '/api/v1/widget/contact',
+              params: { website_token: web_widget.website_token, email: 'prechat@test.com', name: 'Prechat User' },
+              headers: { 'X-Auth-Token' => token },
+              as: :json
+
+        expect(victim.reload.email).to be_nil
+        expect(Contact.from_email('prechat@test.com')).to be_present
+        expect(response).to have_http_status(:success)
+      end
+    end
+  end
+
   describe 'PATCH /api/v1/widget/contact/set_user' do
     let(:params) { { website_token: web_widget.website_token, identifier: 'test' } }
     let(:web_widget) { create(:channel_widget, account: account, hmac_mandatory: true) }

From 1e7218d43923814e9f096b99542fc0865d9fc4ce Mon Sep 17 00:00:00 2001
From: Vishnu Narayanan <iamwishnu@gmail.com>
Date: Tue, 7 Jul 2026 17:37:22 +0530
Subject: [PATCH 06/17] fix: compare HMAC identity hashes securely (#14945)

This switches widget and public inbox HMAC identity checks from direct
string equality to constant-time comparison with a length guard.

Fixes
[https://linear.app/chatwoot/issue/CW-6937](https://linear.app/chatwoot/issue/CW-6937)
Fixes
[https://linear.app/chatwoot/issue/CW-7464](https://linear.app/chatwoot/issue/CW-7464)
Fixes
[https://linear.app/chatwoot/issue/CW-7227](https://linear.app/chatwoot/issue/CW-7227)
---
 app/controllers/api/v1/widget/contacts_controller.rb        | 6 +++++-
 .../public/api/v1/inboxes/contacts_controller.rb            | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/app/controllers/api/v1/widget/contacts_controller.rb b/app/controllers/api/v1/widget/contacts_controller.rb
index 4094ceb24..9a7d5193a 100644
--- a/app/controllers/api/v1/widget/contacts_controller.rb
+++ b/app/controllers/api/v1/widget/contacts_controller.rb
@@ -73,11 +73,15 @@ class Api::V1::Widget::ContactsController < Api::V1::Widget::BaseController
   end
 
   def valid_hmac?
-    params[:identifier_hash] == OpenSSL::HMAC.hexdigest(
+    expected_hash = OpenSSL::HMAC.hexdigest(
       'sha256',
       @web_widget.hmac_token,
       params[:identifier].to_s
     )
+    identifier_hash = params[:identifier_hash].to_s
+    return false unless identifier_hash.bytesize == expected_hash.bytesize
+
+    ActiveSupport::SecurityUtils.secure_compare(identifier_hash, expected_hash)
   end
 
   def permitted_params
diff --git a/app/controllers/public/api/v1/inboxes/contacts_controller.rb b/app/controllers/public/api/v1/inboxes/contacts_controller.rb
index 835c2596b..838b10951 100644
--- a/app/controllers/public/api/v1/inboxes/contacts_controller.rb
+++ b/app/controllers/public/api/v1/inboxes/contacts_controller.rb
@@ -35,11 +35,15 @@ class Public::Api::V1::Inboxes::ContactsController < Public::Api::V1::InboxesCon
   end
 
   def valid_hmac?
-    params[:identifier_hash] == OpenSSL::HMAC.hexdigest(
+    expected_hash = OpenSSL::HMAC.hexdigest(
       'sha256',
       @inbox_channel.hmac_token,
       params[:identifier].to_s
     )
+    identifier_hash = params[:identifier_hash].to_s
+    return false unless identifier_hash.bytesize == expected_hash.bytesize
+
+    ActiveSupport::SecurityUtils.secure_compare(identifier_hash, expected_hash)
   end
 
   def permitted_params

From a5fcecb3f672851fc383cbb5b1995d0e325cc7b0 Mon Sep 17 00:00:00 2001
From: Shivam Mishra <scm.mymail@gmail.com>
Date: Tue, 7 Jul 2026 17:54:13 +0530
Subject: [PATCH 07/17] feat: assistant overview page [CW-7408] (#14889)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR adds a Captain Assistant **Overview** page to show some KPI
metrics (conversations handled, auto-resolution, handoff, hours saved,
reopen-after-resolve, conversation depth) with trend deltas vs the
previous window, a real knowledge card, and a lazily-loaded, cached LLM
welcome summary.

### Highlights

- **Two contextual banners** on the overview:
- **Inbox banner** — prompts the user to connect an inbox when the
assistant has none, so it can actually do work.
- **Coverage banner** — warns when FAQ coverage is below 85% with more
than 100 responses pending review, linking straight to the pending
queue. Dismissal persists per-assistant for 24h via localStorage.
- **Batched stats builder** (`Captain::AssistantStatsBuilder`) computes
both windows in single FILTER-aggregated scans to cut round trips,
behind new `stats`/`summary` endpoints.
- **Cards included but intentionally left dummy / not rendered yet:**
`ResponseQualityCard` (flagged responses) and `CreditUsageCard` (credit
usage + daily chart). Credits are an account-wide counter with no
per-assistant or daily history, so there is no real data to back them
yet; they ship in the codebase but are not wired into the page.

### Index migration

- Replaces `index_messages_on_sender_type_and_sender_id` with
`index_messages_on_sender_and_created` `(sender_type, sender_id,
created_at)`.
- **Why it helps:** the per-assistant windowed lookups filter `sender_*`
*and* a `created_at` range. The old 2-column index matched every
lifetime row for the assistant and filtered the time slice at the heap
(~89% of rows discarded); adding `created_at` as a range column lets
Postgres scan only the window, and fixes the row-count estimate so the
planner picks a hash join over a nested loop on `reporting_events`.
- **Why dropping the old index is safe:** the new index is a left-prefix
superset `(sender_type, sender_id, ...)`, so every query the old one
served is still served. No code references it by name, and dropping it
keeps write amplification on `messages` neutral. Built/dropped with
`CONCURRENTLY` and `if_not_exists`/`if_exists` guards.


## Preview

<img width="2572" height="1754" alt="CleanShot 2026-06-29 at 22 38
51@2x"
src="https://github.com/user-attachments/assets/3798d09e-7850-48e4-b2cd-508533f15cea"
/>

## Banners

#### Inbox connect alert

<img width="2178" height="612" alt="CleanShot 2026-06-30 at 14 26 55@2x"
src="https://github.com/user-attachments/assets/373c371c-bb7d-4291-a0f9-620673078302"
/>

#### Coverage alert
<img width="2178" height="612" alt="CleanShot 2026-06-30 at 14 25 41@2x"
src="https://github.com/user-attachments/assets/e12d6308-11b6-4ba2-88a2-8a3077dd3e8f"
/>

---------

Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
---
 .../dashboard/api/captain/assistant.js        |  16 ++
 .../components-next/captain/PageLayout.vue    |   3 +-
 .../overview/CoverageBanner.vue               |  96 +++++++
 .../pageComponents/overview/InboxBanner.vue   |  73 +++++
 .../pageComponents/overview/KnowledgeCard.vue |  87 ++++++
 .../pageComponents/overview/MetricCard.vue    |  40 +++
 .../pageComponents/overview/QuickLinks.vue    |  81 ++++++
 .../pageComponents/overview/RangeSelector.vue |  78 +++++
 .../pageComponents/overview/WelcomeCard.vue   |  75 +++++
 .../switcher/AssistantSwitcher.vue            |   2 +-
 .../components-next/sidebar/Sidebar.vue       |   8 +
 .../dashboard/helper/featureHelper.js         |   1 +
 .../i18n/locale/en/integrations.json          |  87 ++++++
 .../dashboard/i18n/locale/en/settings.json    |   1 +
 .../captain/assistants/overview/Index.vue     | 151 ++++++++++
 .../dashboard/captain/captain.routes.js       |   9 +-
 .../captain/pages/AssistantsIndexPage.vue     |   3 +-
 app/models/message.rb                         |   2 +-
 config/routes.rb                              |   3 +
 ...00_add_sender_created_index_to_messages.rb |  21 ++
 db/schema.rb                                  |   3 +-
 .../captain/assistant_drilldown_builder.rb    | 162 +++++++++++
 .../captain/assistant_stats_builder.rb        | 224 +++++++++++++++
 .../captain/assistant_stats_window.rb         |  78 +++++
 .../accounts/captain/assistants_controller.rb |  47 ++-
 .../app/policies/captain/assistant_policy.rb  |   8 +
 lib/captain/overview_summary_service.rb       |  83 ++++++
 .../captain_overview_summary.liquid           |  38 +++
 .../reports/assistant_conversation_creator.rb | 203 +++++++++++++
 lib/seeders/reports/report_data_seeder.rb     | 102 ++++++-
 .../captain/assistant_stats_builder_spec.rb   | 271 ++++++++++++++++++
 .../captain/assistants_controller_spec.rb     |  42 +++
 .../policies/captain/assistant_policy_spec.rb |   2 +-
 33 files changed, 2090 insertions(+), 10 deletions(-)
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/CoverageBanner.vue
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/InboxBanner.vue
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/KnowledgeCard.vue
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/MetricCard.vue
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/QuickLinks.vue
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/RangeSelector.vue
 create mode 100644 app/javascript/dashboard/components-next/captain/pageComponents/overview/WelcomeCard.vue
 create mode 100644 app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue
 create mode 100644 db/migrate/20260630000000_add_sender_created_index_to_messages.rb
 create mode 100644 enterprise/app/builders/captain/assistant_drilldown_builder.rb
 create mode 100644 enterprise/app/builders/captain/assistant_stats_builder.rb
 create mode 100644 enterprise/app/builders/captain/assistant_stats_window.rb
 create mode 100644 lib/captain/overview_summary_service.rb
 create mode 100644 lib/integrations/openai/openai_prompts/captain_overview_summary.liquid
 create mode 100644 lib/seeders/reports/assistant_conversation_creator.rb
 create mode 100644 spec/enterprise/builders/captain/assistant_stats_builder_spec.rb

diff --git a/app/javascript/dashboard/api/captain/assistant.js b/app/javascript/dashboard/api/captain/assistant.js
index 157eba74e..dcd92f735 100644
--- a/app/javascript/dashboard/api/captain/assistant.js
+++ b/app/javascript/dashboard/api/captain/assistant.js
@@ -1,6 +1,10 @@
 /* global axios */
 import ApiClient from '../ApiClient';
 
+// Viewer's UTC offset in hours, matching the reports API convention so the
+// backend can anchor calendar ranges to the viewer's day.
+const getTimezoneOffset = () => -new Date().getTimezoneOffset() / 60;
+
 class CaptainAssistant extends ApiClient {
   constructor() {
     super('captain/assistants', { accountScoped: true });
@@ -21,6 +25,18 @@ class CaptainAssistant extends ApiClient {
       message_history: messageHistory,
     });
   }
+
+  getStats({ assistantId, range }) {
+    return axios.get(`${this.url}/${assistantId}/stats`, {
+      params: { range, timezone_offset: getTimezoneOffset() },
+    });
+  }
+
+  getSummary({ assistantId, range }) {
+    return axios.get(`${this.url}/${assistantId}/summary`, {
+      params: { range, timezone_offset: getTimezoneOffset() },
+    });
+  }
 }
 
 export default new CaptainAssistant();
diff --git a/app/javascript/dashboard/components-next/captain/PageLayout.vue b/app/javascript/dashboard/components-next/captain/PageLayout.vue
index 817608f62..6c0d37d15 100644
--- a/app/javascript/dashboard/components-next/captain/PageLayout.vue
+++ b/app/javascript/dashboard/components-next/captain/PageLayout.vue
@@ -182,7 +182,8 @@ const handleCreateAssistant = () => {
             </div>
           </div>
 
-          <div class="flex gap-2">
+          <div class="flex items-center gap-2">
+            <slot name="headerActions" />
             <slot name="search" />
             <div
               v-if="!showPaywall && buttonLabel"
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/CoverageBanner.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/CoverageBanner.vue
new file mode 100644
index 000000000..e832bc0b1
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/CoverageBanner.vue
@@ -0,0 +1,96 @@
+<script setup>
+import { computed, ref, watch } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { LocalStorage } from 'shared/helpers/localStorage';
+
+const props = defineProps({
+  knowledge: {
+    type: Object,
+    default: () => ({ approved: 0, pending: 0, documents: 0, coverage: 0 }),
+  },
+});
+
+const route = useRoute();
+const router = useRouter();
+
+// Dismissal is remembered per assistant for 24 hours (setFlag's default expiry).
+const DISMISS_STORE = 'captain_overview_coverage_banner';
+
+const accountId = computed(() => route.params.accountId);
+const assistantId = computed(() => route.params.assistantId);
+
+// Re-read the stored flag whenever the assistant changes, otherwise the banner
+// would keep the first assistant's dismissed state after switching.
+const dismissed = ref(false);
+
+watch(
+  [accountId, assistantId],
+  ([account, assistant]) => {
+    dismissed.value = LocalStorage.getFlag(DISMISS_STORE, account, assistant);
+  },
+  { immediate: true }
+);
+
+// Thin coverage paired with a large review backlog: approving the pending FAQs
+// is the quickest lever to lift auto-resolution, so nudge the team to act.
+const COVERAGE_THRESHOLD = 85;
+const PENDING_THRESHOLD = 100;
+
+const showBanner = computed(
+  () =>
+    !dismissed.value &&
+    (props.knowledge?.coverage ?? 0) < COVERAGE_THRESHOLD &&
+    (props.knowledge?.pending ?? 0) > PENDING_THRESHOLD
+);
+
+const dismiss = () => {
+  LocalStorage.setFlag(DISMISS_STORE, accountId.value, assistantId.value);
+  dismissed.value = true;
+};
+
+const goToPending = () => {
+  router.push({
+    name: 'captain_assistants_responses_pending',
+    params: {
+      accountId: route.params.accountId,
+      assistantId: route.params.assistantId,
+    },
+  });
+};
+</script>
+
+<template>
+  <div
+    v-if="showBanner"
+    class="flex items-center justify-between gap-3 px-3 py-2 text-sm border rounded-xl bg-n-amber-3 border-n-amber-4 text-n-amber-11"
+  >
+    <div class="flex items-center gap-2 min-w-0">
+      <span class="shrink-0 i-lucide-triangle-alert size-4" />
+      <span class="truncate">
+        {{
+          $t('CAPTAIN.OVERVIEW.COVERAGE_BANNER.TEXT', {
+            count: knowledge.pending,
+            coverage: knowledge.coverage,
+          })
+        }}
+      </span>
+    </div>
+    <div class="flex items-center gap-1 shrink-0">
+      <button
+        type="button"
+        class="px-3 py-1 rounded-lg bg-n-amber-4 hover:bg-n-amber-5"
+        @click="goToPending"
+      >
+        {{ $t('CAPTAIN.OVERVIEW.COVERAGE_BANNER.ACTION') }}
+      </button>
+      <button
+        type="button"
+        class="grid rounded-lg size-7 place-content-center hover:bg-n-amber-4"
+        :aria-label="$t('CAPTAIN.OVERVIEW.COVERAGE_BANNER.DISMISS')"
+        @click="dismiss"
+      >
+        <span class="i-lucide-x size-4" />
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/InboxBanner.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/InboxBanner.vue
new file mode 100644
index 000000000..45952fa11
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/InboxBanner.vue
@@ -0,0 +1,73 @@
+<script setup>
+import { computed, ref, watch } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { useStore, useMapGetter } from 'dashboard/composables/store';
+
+const route = useRoute();
+const router = useRouter();
+const store = useStore();
+
+const dismissed = ref(false);
+
+const assistantId = computed(() => route.params.assistantId);
+const inboxes = useMapGetter('captainInboxes/getRecords');
+const uiFlags = useMapGetter('captainInboxes/getUIFlags');
+
+// Only surface once we know the assistant has no connected inboxes.
+const showBanner = computed(
+  () =>
+    !dismissed.value &&
+    !uiFlags.value.fetchingList &&
+    inboxes.value.length === 0
+);
+
+watch(
+  assistantId,
+  id => {
+    dismissed.value = false;
+    if (id) store.dispatch('captainInboxes/get', { assistantId: id });
+  },
+  { immediate: true }
+);
+
+const goToInboxes = () => {
+  router.push({
+    name: 'captain_assistants_inboxes_index',
+    params: {
+      accountId: route.params.accountId,
+      assistantId: assistantId.value,
+    },
+  });
+};
+</script>
+
+<template>
+  <div
+    v-if="showBanner"
+    class="flex items-center justify-between gap-3 px-3 py-2 text-sm border rounded-xl bg-n-amber-3 border-n-amber-4 text-n-amber-11"
+  >
+    <div class="flex items-center gap-2 min-w-0">
+      <span class="shrink-0 i-lucide-triangle-alert size-4" />
+      <span class="truncate">
+        {{ $t('CAPTAIN.OVERVIEW.INBOX_BANNER.TEXT') }}
+      </span>
+    </div>
+    <div class="flex items-center gap-1 shrink-0">
+      <button
+        type="button"
+        class="px-3 py-1 rounded-lg bg-n-amber-4 hover:bg-n-amber-5"
+        @click="goToInboxes"
+      >
+        {{ $t('CAPTAIN.OVERVIEW.INBOX_BANNER.ACTION') }}
+      </button>
+      <button
+        type="button"
+        class="grid rounded-lg size-7 place-content-center hover:bg-n-amber-4"
+        :aria-label="$t('CAPTAIN.OVERVIEW.INBOX_BANNER.DISMISS')"
+        @click="dismissed = true"
+      >
+        <span class="i-lucide-x size-4" />
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/KnowledgeCard.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/KnowledgeCard.vue
new file mode 100644
index 000000000..80c7ae69d
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/KnowledgeCard.vue
@@ -0,0 +1,87 @@
+<script setup>
+import { computed } from 'vue';
+import { useRoute } from 'vue-router';
+import { useI18n } from 'vue-i18n';
+
+const props = defineProps({
+  knowledge: {
+    type: Object,
+    default: () => ({ approved: 0, pending: 0, documents: 0, coverage: 0 }),
+  },
+});
+
+const { t } = useI18n();
+const route = useRoute();
+
+const approvedPct = computed(() => props.knowledge.coverage ?? 0);
+
+const linkTo = routeName => ({
+  name: routeName,
+  params: {
+    accountId: route.params.accountId,
+    assistantId: route.params.assistantId,
+  },
+});
+
+const stats = computed(() => [
+  {
+    key: 'approved',
+    value: props.knowledge.approved,
+    label: t('CAPTAIN.OVERVIEW.KNOWLEDGE.APPROVED'),
+    to: linkTo('captain_assistants_responses_index'),
+  },
+  {
+    key: 'pending',
+    value: props.knowledge.pending,
+    label: t('CAPTAIN.OVERVIEW.KNOWLEDGE.PENDING'),
+    to: linkTo('captain_assistants_responses_pending'),
+  },
+  {
+    key: 'documents',
+    value: props.knowledge.documents,
+    label: t('CAPTAIN.OVERVIEW.KNOWLEDGE.DOCUMENTS'),
+    to: linkTo('captain_assistants_documents_index'),
+  },
+]);
+</script>
+
+<template>
+  <div
+    class="flex flex-col gap-4 p-5 border rounded-xl bg-n-solid-1 border-n-weak"
+  >
+    <div class="flex items-center justify-between">
+      <span class="text-sm font-medium text-n-slate-12">
+        {{ $t('CAPTAIN.OVERVIEW.KNOWLEDGE.TITLE') }}
+      </span>
+      <span class="text-sm tabular-nums text-n-slate-11">
+        {{ $t('CAPTAIN.OVERVIEW.KNOWLEDGE.COVERAGE', { pct: approvedPct }) }}
+      </span>
+    </div>
+    <div class="w-full h-2 overflow-hidden rounded-full bg-n-alpha-2">
+      <div
+        class="h-full rounded-full bg-n-brand"
+        :style="{ width: `${approvedPct}%` }"
+      />
+    </div>
+    <div class="grid grid-cols-3 gap-3">
+      <RouterLink
+        v-for="stat in stats"
+        :key="stat.key"
+        :to="stat.to"
+        class="flex flex-col gap-1 group/stat"
+      >
+        <span class="text-xl font-semibold tabular-nums text-n-slate-12">
+          {{ stat.value }}
+        </span>
+        <span
+          class="inline-flex items-center gap-1 text-xs transition-colors text-n-slate-11 group-hover/stat:text-n-slate-12"
+        >
+          {{ stat.label }}
+          <span
+            class="transition-opacity opacity-0 i-lucide-arrow-up-right size-3 group-hover/stat:opacity-100"
+          />
+        </span>
+      </RouterLink>
+    </div>
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/MetricCard.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/MetricCard.vue
new file mode 100644
index 000000000..9f8a76f43
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/MetricCard.vue
@@ -0,0 +1,40 @@
+<script setup>
+import { computed } from 'vue';
+
+const props = defineProps({
+  label: { type: String, required: true },
+  value: { type: String, required: true },
+  trend: { type: String, default: '' },
+  hint: { type: String, default: '' },
+  // null = neutral, true = good direction, false = bad direction
+  trendGood: { type: Boolean, default: null },
+});
+
+const trendClass = computed(() => {
+  if (props.trendGood === null) return 'text-n-slate-11';
+  return props.trendGood ? 'text-n-teal-11' : 'text-n-ruby-11';
+});
+</script>
+
+<template>
+  <div class="flex flex-col gap-3 p-5 group bg-n-solid-1">
+    <div class="flex items-center gap-1.5">
+      <span class="text-sm font-medium text-n-slate-11">{{ label }}</span>
+      <span
+        v-if="hint"
+        v-tooltip="hint"
+        class="transition-opacity opacity-0 cursor-help i-lucide-info size-3.5 text-n-slate-10 group-hover:opacity-100"
+      />
+    </div>
+    <div class="flex items-end justify-between gap-2">
+      <span
+        class="text-3xl font-semibold tracking-tight tabular-nums text-n-slate-12"
+      >
+        {{ value }}
+      </span>
+      <span class="text-sm font-medium tabular-nums" :class="trendClass">
+        {{ trend }}
+      </span>
+    </div>
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/QuickLinks.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/QuickLinks.vue
new file mode 100644
index 000000000..e9fb45a07
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/QuickLinks.vue
@@ -0,0 +1,81 @@
+<script setup>
+import { computed } from 'vue';
+import { useRoute, RouterLink } from 'vue-router';
+import { useI18n } from 'vue-i18n';
+import { useAccount } from 'dashboard/composables/useAccount';
+import { getHelpUrlForFeature } from 'dashboard/helper/featureHelper';
+
+const { t } = useI18n();
+const route = useRoute();
+const { isOnChatwootCloud } = useAccount();
+
+const assistantParams = computed(() => ({
+  accountId: route.params.accountId,
+  assistantId: route.params.assistantId,
+}));
+
+const links = computed(() => [
+  {
+    key: 'docs',
+    title: t('CAPTAIN.OVERVIEW.LINKS.DOCS.TITLE'),
+    description: t('CAPTAIN.OVERVIEW.LINKS.DOCS.DESCRIPTION'),
+    icon: 'i-lucide-book-open',
+    href: getHelpUrlForFeature('captain'),
+  },
+  {
+    key: 'playground',
+    title: t('CAPTAIN.OVERVIEW.LINKS.PLAYGROUND.TITLE'),
+    description: t('CAPTAIN.OVERVIEW.LINKS.PLAYGROUND.DESCRIPTION'),
+    icon: 'i-lucide-flask-conical',
+    to: {
+      name: 'captain_assistants_playground_index',
+      params: assistantParams.value,
+    },
+  },
+  {
+    key: 'billing',
+    title: t('CAPTAIN.OVERVIEW.LINKS.BILLING.TITLE'),
+    description: t('CAPTAIN.OVERVIEW.LINKS.BILLING.DESCRIPTION'),
+    icon: 'i-lucide-credit-card',
+    to: {
+      name: 'billing_settings_index',
+      params: { accountId: route.params.accountId },
+    },
+  },
+]);
+</script>
+
+<template>
+  <div v-if="isOnChatwootCloud" class="grid grid-cols-1 gap-4 sm:grid-cols-3">
+    <component
+      :is="link.href ? 'a' : RouterLink"
+      v-for="link in links"
+      :key="link.key"
+      :href="link.href"
+      :to="link.to"
+      :target="link.href ? '_blank' : undefined"
+      :rel="link.href ? 'noopener noreferrer' : undefined"
+      class="flex items-center gap-3 p-4 transition-colors border rounded-xl bg-n-solid-1 border-n-weak hover:bg-n-alpha-1 group/link"
+    >
+      <span
+        class="grid rounded-lg size-9 shrink-0 place-content-center bg-n-alpha-2 text-n-slate-11"
+      >
+        <span :class="link.icon" class="size-4" />
+      </span>
+      <div class="flex flex-col min-w-0">
+        <span class="text-sm font-medium text-n-slate-12">
+          {{ link.title }}
+        </span>
+        <span class="text-xs truncate text-n-slate-11">
+          {{ link.description }}
+        </span>
+      </div>
+      <span
+        :class="
+          link.href ? 'i-lucide-arrow-up-right' : 'i-lucide-chevron-right'
+        "
+        class="ml-auto transition-opacity opacity-0 size-4 text-n-slate-10 group-hover/link:opacity-100"
+      />
+    </component>
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/RangeSelector.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/RangeSelector.vue
new file mode 100644
index 000000000..d003480dd
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/RangeSelector.vue
@@ -0,0 +1,78 @@
+<script setup>
+import { computed } from 'vue';
+import { useToggle } from '@vueuse/core';
+import { useI18n } from 'vue-i18n';
+import { vOnClickOutside } from '@vueuse/components';
+import Button from 'dashboard/components-next/button/Button.vue';
+import DropdownMenu from 'dashboard/components-next/dropdown-menu/DropdownMenu.vue';
+
+const modelValue = defineModel({ type: String, default: '30' });
+
+const { t } = useI18n();
+const [showDropdown, toggleDropdown] = useToggle();
+
+const DAY_RANGES = ['7', '30', '90'];
+
+const decorate = item => ({
+  ...item,
+  action: 'select',
+  isSelected: item.value === modelValue.value,
+});
+
+const menuSections = computed(() => {
+  const dayItems = DAY_RANGES.map(value =>
+    decorate({
+      value,
+      label: t('CAPTAIN.OVERVIEW.RANGES.LAST_DAYS', { count: value }),
+    })
+  );
+  const monthItems = [
+    decorate({
+      value: 'this_month',
+      label: t('CAPTAIN.OVERVIEW.RANGES.THIS_MONTH'),
+    }),
+    decorate({
+      value: 'last_month',
+      label: t('CAPTAIN.OVERVIEW.RANGES.LAST_MONTH'),
+    }),
+  ];
+  return [{ items: dayItems }, { items: monthItems }];
+});
+
+const menuItems = computed(() =>
+  menuSections.value.flatMap(section => section.items)
+);
+
+const selectedLabel = computed(
+  () => menuItems.value.find(item => item.isSelected)?.label || ''
+);
+
+const handleAction = ({ value }) => {
+  toggleDropdown(false);
+  modelValue.value = value;
+};
+</script>
+
+<template>
+  <div
+    v-on-click-outside="() => toggleDropdown(false)"
+    class="relative flex items-center group"
+  >
+    <Button
+      sm
+      slate
+      faded
+      trailing-icon
+      icon="i-lucide-chevron-down"
+      :label="selectedLabel"
+      class="rounded-md group-hover:bg-n-alpha-2"
+      @click="toggleDropdown()"
+    />
+    <DropdownMenu
+      v-if="showDropdown"
+      :menu-sections="menuSections"
+      class="mt-1 ltr:right-0 rtl:left-0 top-full"
+      @action="handleAction($event)"
+    />
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/overview/WelcomeCard.vue b/app/javascript/dashboard/components-next/captain/pageComponents/overview/WelcomeCard.vue
new file mode 100644
index 000000000..df336a7e4
--- /dev/null
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/overview/WelcomeCard.vue
@@ -0,0 +1,75 @@
+<script setup>
+import { computed, ref, watch } from 'vue';
+import { useRoute } from 'vue-router';
+import CaptainAssistant from 'dashboard/api/captain/assistant';
+import MessageFormatter from 'shared/helpers/MessageFormatter.js';
+
+const props = defineProps({
+  range: {
+    type: String,
+    default: '30',
+  },
+});
+
+const route = useRoute();
+const assistantId = computed(() => route.params.assistantId);
+
+// Markdown summary generated by the model from the assistant's stats (served by
+// the captain/assistants/:id/summary endpoint). Numbers are emphasised with
+// **bold** so we can highlight them (see prose-strong styling below).
+const welcomeMarkdown = ref('');
+const isLoading = ref(false);
+
+const fetchSummary = async () => {
+  isLoading.value = true;
+  try {
+    const { data } = await CaptainAssistant.getSummary({
+      assistantId: assistantId.value,
+      range: props.range,
+    });
+    welcomeMarkdown.value = data.message ?? '';
+  } catch {
+    welcomeMarkdown.value = '';
+  } finally {
+    isLoading.value = false;
+  }
+};
+
+watch([() => props.range, assistantId], fetchSummary, { immediate: true });
+
+// Render through the shared markdown formatter (html disabled, so it is safe)
+// used everywhere else for Captain output, instead of a bespoke parser. It
+// handles paragraphs, line breaks, links, lists and emphasis consistently.
+const formattedSummary = computed(
+  () => new MessageFormatter(welcomeMarkdown.value).formattedMessage
+);
+</script>
+
+<!-- eslint-disable-next-line vue/no-root-v-if -->
+<template>
+  <div v-if="isLoading || welcomeMarkdown" class="flex flex-col gap-3">
+    <div class="flex items-center gap-1.5 text-n-slate-10">
+      <span class="i-lucide-sparkles size-3.5" />
+      <span class="text-xs">
+        {{ $t('CAPTAIN.OVERVIEW.WELCOME.LABEL') }}
+      </span>
+    </div>
+    <div
+      v-if="isLoading"
+      class="flex flex-col gap-5"
+      :aria-label="$t('CAPTAIN.OVERVIEW.WELCOME.LOADING')"
+    >
+      <div class="flex flex-col gap-2.5">
+        <div class="w-full h-5 rounded bg-n-slate-3 animate-pulse" />
+        <div class="w-11/12 h-5 rounded bg-n-slate-3 animate-pulse" />
+        <div class="w-4/6 h-5 rounded bg-n-slate-3 animate-pulse" />
+      </div>
+      <div class="w-5/6 h-5 rounded bg-n-slate-3 animate-pulse" />
+    </div>
+    <div
+      v-else
+      v-dompurify-html="formattedSummary"
+      class="max-w-none prose prose-p:text-lg prose-p:leading-relaxed prose-p:mt-0 prose-p:mb-3 last:prose-p:mb-0 prose-strong:font-bold prose-strong:tabular-nums prose-strong:text-n-brand text-n-slate-12"
+    />
+  </div>
+</template>
diff --git a/app/javascript/dashboard/components-next/captain/pageComponents/switcher/AssistantSwitcher.vue b/app/javascript/dashboard/components-next/captain/pageComponents/switcher/AssistantSwitcher.vue
index a67d685f5..c78842241 100644
--- a/app/javascript/dashboard/components-next/captain/pageComponents/switcher/AssistantSwitcher.vue
+++ b/app/javascript/dashboard/components-next/captain/pageComponents/switcher/AssistantSwitcher.vue
@@ -65,7 +65,7 @@ const handleAssistantChange = async assistant => {
 
   const currentRouteName = route.name;
   const targetRouteName =
-    currentRouteName || 'captain_assistants_responses_index';
+    currentRouteName || 'captain_assistants_overview_index';
 
   await fetchDataForRoute(targetRouteName, assistant.id);
 
diff --git a/app/javascript/dashboard/components-next/sidebar/Sidebar.vue b/app/javascript/dashboard/components-next/sidebar/Sidebar.vue
index 15a007a74..0e6b3468b 100644
--- a/app/javascript/dashboard/components-next/sidebar/Sidebar.vue
+++ b/app/javascript/dashboard/components-next/sidebar/Sidebar.vue
@@ -440,6 +440,14 @@ const menuItems = computed(() => {
       label: t('SIDEBAR.CAPTAIN'),
       activeOn: ['captain_assistants_create_index'],
       children: [
+        {
+          name: 'Overview',
+          label: t('SIDEBAR.CAPTAIN_OVERVIEW'),
+          activeOn: ['captain_assistants_overview_index'],
+          to: accountScopedRoute('captain_assistants_index', {
+            navigationPath: 'captain_assistants_overview_index',
+          }),
+        },
         {
           name: 'FAQs',
           label: t('SIDEBAR.CAPTAIN_RESPONSES'),
diff --git a/app/javascript/dashboard/helper/featureHelper.js b/app/javascript/dashboard/helper/featureHelper.js
index c90ec15db..a8e5fd2b7 100644
--- a/app/javascript/dashboard/helper/featureHelper.js
+++ b/app/javascript/dashboard/helper/featureHelper.js
@@ -19,6 +19,7 @@ const FEATURE_HELP_URLS = {
   webhook: 'https://chwt.app/hc/webhooks',
   billing: 'https://chwt.app/pricing',
   saml: 'https://chwt.app/hc/saml',
+  captain: 'https://chwt.app/captain-docs',
   captain_billing: 'https://chwt.app/hc/captain_billing',
 };
 
diff --git a/app/javascript/dashboard/i18n/locale/en/integrations.json b/app/javascript/dashboard/i18n/locale/en/integrations.json
index 3c13f0d51..a39165268 100644
--- a/app/javascript/dashboard/i18n/locale/en/integrations.json
+++ b/app/javascript/dashboard/i18n/locale/en/integrations.json
@@ -392,6 +392,93 @@
   "CAPTAIN": {
     "NAME": "Captain",
     "HEADER_KNOW_MORE": "Know more",
+    "OVERVIEW": {
+      "HEADER": "Overview",
+      "WELCOME": {
+        "LABEL": "Captain summary",
+        "LOADING": "Generating summary…"
+      },
+      "INBOX_BANNER": {
+        "TEXT": "This assistant isn't connected to any inbox yet, so it won't respond to conversations.",
+        "ACTION": "Connect inbox",
+        "DISMISS": "Dismiss"
+      },
+      "COVERAGE_BANNER": {
+        "TEXT": "{count} FAQs are pending review, keeping coverage at {coverage}%. Approve them so your assistant can resolve more on its own.",
+        "ACTION": "Review FAQs",
+        "DISMISS": "Dismiss"
+      },
+      "RANGES": {
+        "LAST_DAYS": "Last {count} days",
+        "THIS_MONTH": "This month",
+        "LAST_MONTH": "Last month"
+      },
+      "METRICS": {
+        "HANDLED": {
+          "LABEL": "Conversations handled",
+          "HINT": "Distinct conversations this assistant replied in."
+        },
+        "AUTO_RESOLUTION": {
+          "LABEL": "Auto-resolution rate",
+          "HINT": "Share of handled conversations closed without a human reply."
+        },
+        "HANDOFF": {
+          "LABEL": "Handoff rate",
+          "HINT": "Share of handled conversations escalated to a human agent."
+        },
+        "HOURS_SAVED": {
+          "LABEL": "Hours saved",
+          "HINT": "Estimate: Captain replies times the team's average response time. Directional, not measured labor."
+        },
+        "REOPEN": {
+          "LABEL": "Reopen rate",
+          "HINT": "Auto-resolved conversations that were reopened afterwards."
+        },
+        "DEPTH": {
+          "LABEL": "Messages / conversation",
+          "HINT": "Average replies the assistant sends per conversation."
+        }
+      },
+      "KNOWLEDGE": {
+        "TITLE": "Knowledge coverage",
+        "COVERAGE": "{pct}% approved",
+        "APPROVED": "Approved FAQs",
+        "PENDING": "Pending FAQs",
+        "DOCUMENTS": "Documents"
+      },
+      "FLAGGED": {
+        "TITLE": "Response quality",
+        "TOTAL": "{count} flagged · {rate}"
+      },
+      "CREDITS": {
+        "TITLE": "Credit usage",
+        "UNIT": "credits",
+        "LEGEND": "Daily credits used",
+        "AXIS_START": "{count}d ago",
+        "AXIS_END": "Today"
+      },
+      "LINKS": {
+        "DOCS": {
+          "TITLE": "Captain docs",
+          "DESCRIPTION": "Guides and how-tos for Captain"
+        },
+        "PLAYGROUND": {
+          "TITLE": "Playground",
+          "DESCRIPTION": "Test this assistant's replies"
+        },
+        "BILLING": {
+          "TITLE": "Billing",
+          "DESCRIPTION": "Manage credits and plan"
+        }
+      },
+      "FLAG_REASONS": {
+        "INCORRECT": "Incorrect info",
+        "INCOMPLETE": "Incomplete",
+        "OUTDATED": "Outdated",
+        "INAPPROPRIATE": "Inappropriate",
+        "OTHER": "Other"
+      }
+    },
     "ASSISTANT_SWITCHER": {
       "ASSISTANTS": "Assistants",
       "SWITCH_ASSISTANT": "Switch between assistants",
diff --git a/app/javascript/dashboard/i18n/locale/en/settings.json b/app/javascript/dashboard/i18n/locale/en/settings.json
index 4caca05fb..23058d739 100644
--- a/app/javascript/dashboard/i18n/locale/en/settings.json
+++ b/app/javascript/dashboard/i18n/locale/en/settings.json
@@ -324,6 +324,7 @@
     "ALL_COMPANIES": "All Companies",
     "CAPTAIN": "Captain",
     "CAPTAIN_ASSISTANTS": "Assistants",
+    "CAPTAIN_OVERVIEW": "Overview",
     "CAPTAIN_DOCUMENTS": "Documents",
     "CAPTAIN_RESPONSES": "FAQs",
     "CAPTAIN_TOOLS": "Tools",
diff --git a/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue b/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue
new file mode 100644
index 000000000..687e97286
--- /dev/null
+++ b/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue
@@ -0,0 +1,151 @@
+<script setup>
+import { computed, ref, watch } from 'vue';
+import { useI18n } from 'vue-i18n';
+import { useRoute } from 'vue-router';
+import { FEATURE_FLAGS } from 'dashboard/featureFlags';
+import CaptainAssistant from 'dashboard/api/captain/assistant';
+
+import PageLayout from 'dashboard/components-next/captain/PageLayout.vue';
+import CaptainPaywall from 'dashboard/components-next/captain/pageComponents/Paywall.vue';
+import RangeSelector from 'dashboard/components-next/captain/pageComponents/overview/RangeSelector.vue';
+import WelcomeCard from 'dashboard/components-next/captain/pageComponents/overview/WelcomeCard.vue';
+import MetricCard from 'dashboard/components-next/captain/pageComponents/overview/MetricCard.vue';
+import KnowledgeCard from 'dashboard/components-next/captain/pageComponents/overview/KnowledgeCard.vue';
+import QuickLinks from 'dashboard/components-next/captain/pageComponents/overview/QuickLinks.vue';
+import InboxBanner from 'dashboard/components-next/captain/pageComponents/overview/InboxBanner.vue';
+import CoverageBanner from 'dashboard/components-next/captain/pageComponents/overview/CoverageBanner.vue';
+
+const { t } = useI18n();
+const route = useRoute();
+
+const selectedRange = ref('this_month');
+
+const assistantId = computed(() => route.params.assistantId);
+const stats = ref(null);
+
+const fetchStats = async () => {
+  try {
+    const { data } = await CaptainAssistant.getStats({
+      assistantId: assistantId.value,
+      range: selectedRange.value,
+    });
+    stats.value = data;
+  } catch {
+    stats.value = null;
+  }
+};
+
+watch([selectedRange, assistantId], fetchStats, { immediate: true });
+
+// `direction` says whether a rising trend is good ('up'), bad ('down'), or
+// neutral, so we can colour the delta independently of its sign.
+const resolveTrendGood = (trendValue, direction) => {
+  if (direction === 'neutral' || trendValue === 0) return null;
+  return direction === 'up' ? trendValue > 0 : trendValue < 0;
+};
+
+// Trend units mirror the backend pack mode: a relative percent change ('%') for
+// :percent metrics, a percentage-point delta (' pts') for rate metrics packed as
+// :point, and a plain number for :absolute counts like conversation depth.
+const TREND_SUFFIX = { percent: '%', point: ' pts', absolute: '' };
+
+const metricFor = (statKey, formatValue, direction, trendKind = 'percent') => {
+  const data = stats.value?.[statKey];
+  if (!data) return { value: '—', trend: '', trendGood: null };
+
+  const sign = data.trend > 0 ? '+' : '';
+  return {
+    value: formatValue(data.current),
+    trend: `${sign}${data.trend}${TREND_SUFFIX[trendKind]}`,
+    trendGood: resolveTrendGood(data.trend, direction),
+  };
+};
+
+const metrics = computed(() => [
+  {
+    key: 'handled',
+    label: t('CAPTAIN.OVERVIEW.METRICS.HANDLED.LABEL'),
+    hint: t('CAPTAIN.OVERVIEW.METRICS.HANDLED.HINT'),
+    ...metricFor('conversations_handled', v => v.toLocaleString(), 'up'),
+  },
+  {
+    key: 'autoResolution',
+    label: t('CAPTAIN.OVERVIEW.METRICS.AUTO_RESOLUTION.LABEL'),
+    hint: t('CAPTAIN.OVERVIEW.METRICS.AUTO_RESOLUTION.HINT'),
+    ...metricFor('auto_resolution_rate', v => `${v}%`, 'up', 'point'),
+  },
+  {
+    key: 'handoff',
+    label: t('CAPTAIN.OVERVIEW.METRICS.HANDOFF.LABEL'),
+    hint: t('CAPTAIN.OVERVIEW.METRICS.HANDOFF.HINT'),
+    ...metricFor('handoff_rate', v => `${v}%`, 'down', 'point'),
+  },
+  {
+    key: 'hoursSaved',
+    label: t('CAPTAIN.OVERVIEW.METRICS.HOURS_SAVED.LABEL'),
+    hint: t('CAPTAIN.OVERVIEW.METRICS.HOURS_SAVED.HINT'),
+    ...metricFor('hours_saved', v => `${v}h`, 'up'),
+  },
+  {
+    key: 'reopen',
+    label: t('CAPTAIN.OVERVIEW.METRICS.REOPEN.LABEL'),
+    hint: t('CAPTAIN.OVERVIEW.METRICS.REOPEN.HINT'),
+    ...metricFor('reopen_rate', v => `${v}%`, 'down', 'point'),
+  },
+  {
+    key: 'depth',
+    label: t('CAPTAIN.OVERVIEW.METRICS.DEPTH.LABEL'),
+    hint: t('CAPTAIN.OVERVIEW.METRICS.DEPTH.HINT'),
+    ...metricFor(
+      'conversation_depth',
+      v => v.toFixed(1),
+      'neutral',
+      'absolute'
+    ),
+  },
+]);
+</script>
+
+<template>
+  <PageLayout
+    :header-title="$t('CAPTAIN.OVERVIEW.HEADER')"
+    :is-empty="false"
+    :show-pagination-footer="false"
+    :show-know-more="false"
+    :feature-flag="FEATURE_FLAGS.CAPTAIN"
+  >
+    <template #headerActions>
+      <RangeSelector v-model="selectedRange" />
+    </template>
+    <template #paywall>
+      <CaptainPaywall />
+    </template>
+    <template #body>
+      <div class="flex flex-col gap-6">
+        <InboxBanner />
+
+        <CoverageBanner :knowledge="stats?.knowledge" />
+
+        <WelcomeCard :range="selectedRange" />
+
+        <div
+          class="grid grid-cols-1 gap-px overflow-hidden border rounded-xl sm:grid-cols-2 lg:grid-cols-3 bg-n-weak border-n-weak"
+        >
+          <MetricCard
+            v-for="metric in metrics"
+            :key="metric.key"
+            :label="metric.label"
+            :value="metric.value"
+            :trend="metric.trend"
+            :hint="metric.hint"
+            :trend-good="metric.trendGood"
+          />
+        </div>
+
+        <KnowledgeCard :knowledge="stats?.knowledge" />
+
+        <QuickLinks />
+      </div>
+    </template>
+  </PageLayout>
+</template>
diff --git a/app/javascript/dashboard/routes/dashboard/captain/captain.routes.js b/app/javascript/dashboard/routes/dashboard/captain/captain.routes.js
index 1ab4fa501..8448f32cf 100644
--- a/app/javascript/dashboard/routes/dashboard/captain/captain.routes.js
+++ b/app/javascript/dashboard/routes/dashboard/captain/captain.routes.js
@@ -6,6 +6,7 @@ import CaptainPageRouteView from './pages/CaptainPageRouteView.vue';
 import AssistantsIndexPage from './pages/AssistantsIndexPage.vue';
 import AssistantEmptyStateIndex from './assistants/Index.vue';
 
+import AssistantOverviewIndex from './assistants/overview/Index.vue';
 import AssistantSettingsIndex from './assistants/settings/Settings.vue';
 import AssistantInboxesIndex from './assistants/inboxes/Index.vue';
 import AssistantPlaygroundIndex from './assistants/playground/Index.vue';
@@ -36,6 +37,12 @@ const metaV2 = {
 };
 
 const assistantRoutes = [
+  {
+    path: frontendURL('accounts/:accountId/captain/:assistantId/overview'),
+    component: AssistantOverviewIndex,
+    name: 'captain_assistants_overview_index',
+    meta,
+  },
   {
     path: frontendURL('accounts/:accountId/captain/:assistantId/faqs'),
     component: ResponsesIndex,
@@ -129,7 +136,7 @@ export const routes = [
       return {
         name: 'captain_assistants_index',
         params: {
-          navigationPath: 'captain_assistants_responses_index',
+          navigationPath: 'captain_assistants_overview_index',
           ...to.params,
         },
       };
diff --git a/app/javascript/dashboard/routes/dashboard/captain/pages/AssistantsIndexPage.vue b/app/javascript/dashboard/routes/dashboard/captain/pages/AssistantsIndexPage.vue
index 01ec64618..d366d4254 100644
--- a/app/javascript/dashboard/routes/dashboard/captain/pages/AssistantsIndexPage.vue
+++ b/app/javascript/dashboard/routes/dashboard/captain/pages/AssistantsIndexPage.vue
@@ -53,6 +53,7 @@ const routeToLastActiveAssistant = () => {
 
   const { navigationPath } = route.params;
   const isAValidRoute = [
+    'captain_assistants_overview_index', // Overview page
     'captain_assistants_responses_index', // Faq page
     'captain_assistants_documents_index', // Document page
     'captain_assistants_scenarios_index', // Scenario page
@@ -64,7 +65,7 @@ const routeToLastActiveAssistant = () => {
 
   const navigateTo = isAValidRoute
     ? navigationPath
-    : 'captain_assistants_responses_index';
+    : 'captain_assistants_overview_index';
 
   return routeToView(navigateTo, {
     accountId: route.params.accountId,
diff --git a/app/models/message.rb b/app/models/message.rb
index f25d2e112..220bdd549 100644
--- a/app/models/message.rb
+++ b/app/models/message.rb
@@ -34,7 +34,7 @@
 #  index_messages_on_conversation_id                    (conversation_id)
 #  index_messages_on_created_at                         (created_at)
 #  index_messages_on_inbox_id                           (inbox_id)
-#  index_messages_on_sender_type_and_sender_id          (sender_type,sender_id)
+#  index_messages_on_sender_and_created                 (sender_type,sender_id,created_at)
 #  index_messages_on_source_id                          (source_id)
 #
 
diff --git a/config/routes.rb b/config/routes.rb
index e0a1a8e50..c5e7ded2f 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -66,6 +66,9 @@ Rails.application.routes.draw do
             resources :assistants do
               member do
                 post :playground
+                get :stats
+                get :summary
+                get :drilldown
               end
               collection do
                 get :tools
diff --git a/db/migrate/20260630000000_add_sender_created_index_to_messages.rb b/db/migrate/20260630000000_add_sender_created_index_to_messages.rb
new file mode 100644
index 000000000..3424ead71
--- /dev/null
+++ b/db/migrate/20260630000000_add_sender_created_index_to_messages.rb
@@ -0,0 +1,21 @@
+class AddSenderCreatedIndexToMessages < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  # Adds created_at to the (sender_type, sender_id) index so per-assistant
+  # windowed lookups (Captain Overview stats) can range-scan the time slice
+  # instead of reading every lifetime row and filtering at the heap. The new
+  # index is a left-prefix superset of the old one.
+  #
+  # TODO: drop the now-redundant index_messages_on_sender_type_and_sender_id
+  # once this index has been running in production long enough to confirm it
+  # fully replaces the old one.
+  def up
+    add_index :messages, [:sender_type, :sender_id, :created_at],
+              name: 'index_messages_on_sender_and_created', algorithm: :concurrently, if_not_exists: true
+  end
+
+  def down
+    remove_index :messages, name: 'index_messages_on_sender_and_created',
+                            algorithm: :concurrently, if_exists: true
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index 05afea9a1..1a676dd59 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.1].define(version: 2026_06_20_000000) do
+ActiveRecord::Schema[7.1].define(version: 2026_06_30_000000) do
   # These extensions should be enabled to support this database
   enable_extension "pg_stat_statements"
   enable_extension "pg_trgm"
@@ -1034,6 +1034,7 @@ ActiveRecord::Schema[7.1].define(version: 2026_06_20_000000) do
     t.index ["conversation_id"], name: "index_messages_on_conversation_id"
     t.index ["created_at"], name: "index_messages_on_created_at"
     t.index ["inbox_id"], name: "index_messages_on_inbox_id"
+    t.index ["sender_type", "sender_id", "created_at"], name: "index_messages_on_sender_and_created"
     t.index ["sender_type", "sender_id"], name: "index_messages_on_sender_type_and_sender_id"
     t.index ["source_id"], name: "index_messages_on_source_id"
   end
diff --git a/enterprise/app/builders/captain/assistant_drilldown_builder.rb b/enterprise/app/builders/captain/assistant_drilldown_builder.rb
new file mode 100644
index 000000000..b98aa7620
--- /dev/null
+++ b/enterprise/app/builders/captain/assistant_drilldown_builder.rb
@@ -0,0 +1,162 @@
+# Lists the underlying records behind a single Captain assistant stat card, so a
+# viewer can drill from an aggregate (e.g. "auto-resolution 42%") into the exact
+# conversations or messages that produced it.
+#
+# The window is resolved by Captain::AssistantStatsWindow from the same `range`
+# and `timezone_offset` the stat card used, so the drilldown covers precisely the
+# rows the card counted. Records are serialized with the shared reports drilldown
+# serializer, so the existing frontend drilldown drawer/card can render them.
+class Captain::AssistantDrilldownBuilder
+  ASSISTANT_SENDER_TYPE = 'Captain::Assistant'.freeze
+  RESOLVED_EVENT_NAMES = Captain::AssistantStatsBuilder::RESOLVED_EVENT_NAMES
+  HANDOFF_EVENT_NAMES = Captain::AssistantStatsBuilder::HANDOFF_EVENT_NAMES
+
+  # Metrics whose records are individual messages rather than conversations.
+  MESSAGE_METRICS = %w[hours_saved].freeze
+  SUPPORTED_METRICS = %w[
+    conversations_handled auto_resolution_rate handoff_rate hours_saved reopen_rate conversation_depth
+  ].freeze
+
+  DEFAULT_PAGE = 1
+  DEFAULT_PER_PAGE = 25
+  MAX_PER_PAGE = 100
+
+  pattr_initialize :assistant, :params
+
+  def self.supported_metric?(metric) = SUPPORTED_METRICS.include?(metric.to_s)
+
+  def build
+    records = paginated_records.to_a
+    { meta: meta, payload: records.map { |record| record_serializer(records).serialize(record) } }
+  end
+
+  private
+
+  def account = assistant.account
+
+  def window
+    @window ||= Captain::AssistantStatsWindow.new(params[:range], params[:timezone_offset])
+  end
+
+  def range = window.current
+
+  def meta
+    {
+      metric: metric,
+      record_type: record_type,
+      current_page: current_page,
+      per_page: per_page,
+      total_count: paginated_records.total_count,
+      conversation_count: conversation_count,
+      range: { since: range.first.to_i, until: range.last.to_i }
+    }
+  end
+
+  def conversation_count
+    return paginated_records.total_count unless message_metric?
+
+    drilldown_scope.except(:includes).reorder(nil).distinct.count(:conversation_id)
+  end
+
+  def paginated_records
+    @paginated_records ||= drilldown_scope.page(current_page).per(per_page)
+  end
+
+  def drilldown_scope
+    case metric
+    when 'conversations_handled' then handled_conversations
+    when 'auto_resolution_rate' then conversations_for(resolved_events.select(:conversation_id))
+    when 'handoff_rate' then event_conversations(HANDOFF_EVENT_NAMES)
+    when 'hours_saved' then public_reply_messages
+    when 'reopen_rate' then reopened_conversations
+    when 'conversation_depth' then depth_conversations
+    else
+      raise ArgumentError, "Unsupported assistant drilldown metric: #{metric}"
+    end
+  end
+
+  # Messages the assistant authored in the window; the cohort every metric derives from.
+  def handled_messages
+    account.messages.where(sender_type: ASSISTANT_SENDER_TYPE, sender_id: assistant.id, created_at: range)
+  end
+
+  def handled_conversation_ids
+    handled_messages.select(:conversation_id)
+  end
+
+  def handled_conversations
+    conversations_for(handled_conversation_ids)
+  end
+
+  # Public agent-facing replies the assistant sent; the rows behind hours_saved.
+  def public_reply_messages
+    handled_messages.where(message_type: :outgoing, private: false)
+                    .includes(:sender, conversation: [:assignee, :contact, :inbox])
+                    .reorder(created_at: :desc)
+  end
+
+  # Conversations in the handled cohort that recorded one of the given reporting
+  # events in the window (resolved or handed-off).
+  def event_conversations(event_names)
+    ids = account.reporting_events
+                 .where(name: event_names, created_at: range, conversation_id: handled_conversation_ids)
+                 .select(:conversation_id)
+    conversations_for(ids)
+  end
+
+  # Captain resolves in the window, excluding bot-resolved rows whose conversation
+  # was also handed off, mirroring AssistantStatsBuilder#resolved_clause so the
+  # drilldown lists exactly the conversations the auto-resolution card counted.
+  def resolved_events
+    handoff_ids = account.reporting_events.where(name: HANDOFF_EVENT_NAMES, created_at: range).select(:conversation_id)
+    account.reporting_events
+           .where(name: RESOLVED_EVENT_NAMES, created_at: range, conversation_id: handled_conversation_ids)
+           .where("NOT (name = ? AND conversation_id IN (#{handoff_ids.to_sql}))",
+                  Captain::AssistantStatsBuilder::BOT_RESOLVED_EVENT_NAME)
+  end
+
+  # Auto-resolved conversations that reopened at/after their Captain resolve,
+  # mirroring AssistantStatsBuilder#reopen_rate's numerator cohort.
+  def reopened_conversations
+    ids = account.reporting_events
+                 .where(name: 'conversation_opened')
+                 .where('reporting_events.value > 0')
+                 .where('reporting_events.event_end_time <= ?', range.last)
+                 .joins("INNER JOIN (#{resolved_events.to_sql}) resolves " \
+                        'ON resolves.conversation_id = reporting_events.conversation_id ' \
+                        'AND reporting_events.event_end_time >= resolves.event_end_time')
+                 .select('reporting_events.conversation_id')
+    conversations_for(ids)
+  end
+
+  # Conversations the assistant sent at least one public reply in; the denominator behind conversation_depth.
+  def depth_conversations
+    conversations_for(handled_messages.where(message_type: :outgoing, private: false).select(:conversation_id))
+  end
+
+  def conversations_for(conversation_ids)
+    account.conversations
+           .where(id: conversation_ids)
+           .includes(:assignee, :contact, :inbox)
+           .order(created_at: :desc)
+  end
+
+  def record_serializer(records)
+    @record_serializer ||= V2::Reports::DrilldownRecordSerializer.new(account, metric, false, records)
+  end
+
+  def metric = params[:metric].to_s
+
+  def message_metric? = MESSAGE_METRICS.include?(metric)
+
+  def record_type = message_metric? ? 'message' : 'conversation'
+
+  def current_page = [params[:page].to_i, DEFAULT_PAGE].max
+
+  def per_page
+    requested_per_page = params[:per_page].to_i
+    requested_per_page = DEFAULT_PER_PAGE if requested_per_page <= 0
+
+    [requested_per_page, MAX_PER_PAGE].min
+  end
+end
diff --git a/enterprise/app/builders/captain/assistant_stats_builder.rb b/enterprise/app/builders/captain/assistant_stats_builder.rb
new file mode 100644
index 000000000..7198c39e1
--- /dev/null
+++ b/enterprise/app/builders/captain/assistant_stats_builder.rb
@@ -0,0 +1,224 @@
+# Computes per-assistant overview metrics for the Captain Overview page.
+# Each metric is returned for the current window and the previous equal-length
+# window, plus a derived trend.
+#
+# Queries are batched to cut round trips: the message-derived counts (handled,
+# public replies, depth) and the average reply time are each computed for both
+# windows in a single scan via conditional FILTER aggregation.
+class Captain::AssistantStatsBuilder
+  RESOLVED_EVENT_NAMES = %w[conversation_captain_inference_resolved conversation_bot_resolved].freeze
+  HANDOFF_EVENT_NAMES = %w[conversation_captain_inference_handoff conversation_bot_handoff].freeze
+  BOT_RESOLVED_EVENT_NAME = 'conversation_bot_resolved'.freeze
+
+  attr_reader :assistant, :account
+
+  delegate :range, :period, to: :window
+
+  # `range` is either a day count ('7', '30', '90') or a named period
+  # ('this_month', 'last_month'). `timezone_offset` is the viewer's UTC offset in
+  # hours (as the reports API sends it), so month/day boundaries anchor to the
+  # viewer's day rather than UTC. Both windows are resolved by AssistantStatsWindow.
+  def initialize(assistant, range = Captain::AssistantStatsWindow::DEFAULT_RANGE, timezone_offset = nil)
+    @assistant = assistant
+    @account = assistant.account
+    @window = Captain::AssistantStatsWindow.new(range, timezone_offset)
+  end
+
+  def metrics
+    messages = message_window_metrics
+    reply_times = avg_reply_times
+    current = window_metrics(current_range, messages[:current], reply_times[:current])
+    previous = window_metrics(previous_range, messages[:previous], reply_times[:previous])
+
+    build_metrics(current, previous)
+  end
+
+  private
+
+  attr_reader :window
+
+  def current_range
+    window.current
+  end
+
+  def previous_range
+    window.previous
+  end
+
+  def build_metrics(current, previous)
+    {
+      conversations_handled: pack(current[:handled], previous[:handled], :percent),
+      auto_resolution_rate: pack(current[:auto_resolution], previous[:auto_resolution], :point),
+      handoff_rate: pack(current[:handoff], previous[:handoff], :point),
+      hours_saved: pack(current[:hours_saved], previous[:hours_saved], :percent),
+      reopen_rate: pack(current[:reopen], previous[:reopen], :point),
+      conversation_depth: pack(current[:depth], previous[:depth], :absolute),
+      knowledge: knowledge
+    }
+  end
+
+  # Combines the per-window message counts and reply time with the reporting-event metrics for one window.
+  def window_metrics(range, message_counts, avg_reply)
+    handled = message_counts[:handled]
+    public_count = message_counts[:public_count]
+    depth_conversations = message_counts[:depth_conversations]
+    resolution = resolution_counts(range)
+
+    {
+      handled: handled,
+      auto_resolution: rate(resolution[:resolved], handled),
+      handoff: rate(resolution[:handoff], handled),
+      hours_saved: (public_count * avg_reply / 3600.0).round,
+      reopen: reopen_rate(range),
+      depth: depth_conversations.zero? ? 0 : (public_count.to_f / depth_conversations).round(1)
+    }
+  end
+
+  # One scan over the assistant's messages computes handled, public-reply count,
+  # and depth-conversation count for both windows via conditional aggregation.
+  def message_window_metrics
+    public_clause = "message_type = #{Message.message_types[:outgoing]} AND private = false"
+    cur = window_clause(current_range)
+    prev = window_clause(previous_range)
+
+    row = handled_scope(full_span).reorder(nil).pick(
+      Arel.sql("COUNT(DISTINCT conversation_id) FILTER (WHERE #{cur})"),
+      Arel.sql("COUNT(DISTINCT conversation_id) FILTER (WHERE #{prev})"),
+      Arel.sql("COUNT(*) FILTER (WHERE #{cur} AND #{public_clause})"),
+      Arel.sql("COUNT(*) FILTER (WHERE #{prev} AND #{public_clause})"),
+      Arel.sql("COUNT(DISTINCT conversation_id) FILTER (WHERE #{cur} AND #{public_clause})"),
+      Arel.sql("COUNT(DISTINCT conversation_id) FILTER (WHERE #{prev} AND #{public_clause})")
+    )
+
+    {
+      current: { handled: row[0], public_count: row[2], depth_conversations: row[4] },
+      previous: { handled: row[1], public_count: row[3], depth_conversations: row[5] }
+    }
+  end
+
+  # Average reply time (seconds) for both windows in one scan.
+  def avg_reply_times
+    row = account.reporting_events.where(name: 'reply_time', created_at: full_span).reorder(nil).pick(
+      Arel.sql("AVG(value) FILTER (WHERE #{window_clause(current_range)})"),
+      Arel.sql("AVG(value) FILTER (WHERE #{window_clause(previous_range)})")
+    )
+    { current: row[0].to_f, previous: row[1].to_f }
+  end
+
+  # Resolved and handed-off conversation counts for one window, in a single scan
+  # of the handled set's reporting events.
+  def resolution_counts(range)
+    row = account.reporting_events
+                 .where(name: RESOLVED_EVENT_NAMES + HANDOFF_EVENT_NAMES,
+                        created_at: range,
+                        conversation_id: handled_scope(range).select(:conversation_id))
+                 .reorder(nil)
+                 .pick(
+                   Arel.sql("COUNT(DISTINCT conversation_id) FILTER (WHERE #{resolved_clause(range)})"),
+                   Arel.sql("COUNT(DISTINCT conversation_id) FILTER (WHERE name IN (#{quoted(HANDOFF_EVENT_NAMES)}))")
+                 )
+    { resolved: row[0], handoff: row[1] }
+  end
+
+  # A countable resolve is any inference resolve, or a bot resolve on a conversation
+  # with no handoff in the window. conversation_bot_resolved fires on any resolve
+  # without an agent message (reporting_event_listener), so a handed-off conversation
+  # that goes quiet and gets closed would otherwise count as an auto-resolution too;
+  # the reports bot_resolutions metric applies the same exclusion (:exclude_bot_handoffs).
+  def resolved_clause(range)
+    "name IN (#{quoted(RESOLVED_EVENT_NAMES)}) AND #{bot_resolve_handoff_exclusion(range)}"
+  end
+
+  def bot_resolve_handoff_exclusion(range)
+    "NOT (name = #{quote(BOT_RESOLVED_EVENT_NAME)} AND conversation_id IN (#{handoff_conversation_ids(range).to_sql}))"
+  end
+
+  def handoff_conversation_ids(range)
+    account.reporting_events.where(name: HANDOFF_EVENT_NAMES, created_at: range).select(:conversation_id)
+  end
+
+  # Conversations the assistant participated in (authored any message).
+  def handled_scope(range)
+    account.messages.where(sender_type: 'Captain::Assistant', sender_id: assistant.id, created_at: range)
+  end
+
+  # Span covering both windows so a single scan can split them with FILTER.
+  def full_span
+    [current_range.first, previous_range.first].min..current_range.last
+  end
+
+  def window_clause(range)
+    "created_at >= #{quote(range.first)} AND created_at <= #{quote(range.last)}"
+  end
+
+  def quote(value)
+    account.class.connection.quote(value)
+  end
+
+  def quoted(values)
+    values.map { |value| quote(value) }.join(', ')
+  end
+
+  # Of the conversations Captain auto-resolved, the share reopened afterwards. The cohort is
+  # derived from the assistant's handled conversations (not current inbox membership) so a later
+  # inbox reassignment doesn't drop historical resolves, and covers both the evaluated (inference)
+  # and time-based (bot) resolve paths so the denominator matches auto_resolution_rate.
+  def reopen_rate(range)
+    resolved_scope = account.reporting_events
+                            .where(name: RESOLVED_EVENT_NAMES, created_at: range,
+                                   conversation_id: handled_scope(range).select(:conversation_id))
+                            .where(bot_resolve_handoff_exclusion(range))
+    # event_end_time on a reopen is when it actually reopened. Join it to the conversation's own
+    # Captain resolves and keep only reopens at/after one of them, so a human resolve/reopen earlier
+    # in the same window isn't mistaken for a reopen-after-Captain-resolve. (Comparing the reopen's
+    # start time instead would misfire: the inference event is dispatched just after the generic
+    # conversation_resolved that seeds event_start_time, so it can land after the reopen's start.)
+    # The reopen itself must also fall inside the window, so a completed range (last_month, the
+    # previous window) doesn't count reopens that happened after it ended.
+    reopened = account.reporting_events
+                      .where(name: 'conversation_opened')
+                      .where('reporting_events.value > 0')
+                      .where('reporting_events.event_end_time <= ?', range.last)
+                      .joins("INNER JOIN (#{resolved_scope.to_sql}) resolves " \
+                             'ON resolves.conversation_id = reporting_events.conversation_id ' \
+                             'AND reporting_events.event_end_time >= resolves.event_end_time')
+                      .distinct.count('reporting_events.conversation_id')
+    rate(reopened, resolved_scope.distinct.count(:conversation_id))
+  end
+
+  # Approved/pending FAQ counts and the document total in a single round trip.
+  def knowledge
+    approved, pending, documents = Captain::AssistantResponse.by_assistant(assistant.id).reorder(nil).pick(
+      Arel.sql("COUNT(*) FILTER (WHERE status = #{Captain::AssistantResponse.statuses['approved']})"),
+      Arel.sql("COUNT(*) FILTER (WHERE status = #{Captain::AssistantResponse.statuses['pending']})"),
+      Arel.sql("(SELECT COUNT(*) FROM captain_documents WHERE assistant_id = #{assistant.id.to_i})")
+    )
+    total = approved + pending
+
+    {
+      approved: approved,
+      pending: pending,
+      documents: documents,
+      coverage: total.zero? ? 0 : (approved.to_f / total * 100).round
+    }
+  end
+
+  def rate(numerator, denominator)
+    return 0 if denominator.zero?
+
+    (numerator.to_f / denominator * 100).round(1)
+  end
+
+  def pack(current, previous, mode)
+    { current: current, previous: previous, trend: trend(current, previous, mode) }
+  end
+
+  def trend(current, previous, mode)
+    case mode
+    when :percent
+      previous.zero? ? 0 : ((current - previous).to_f / previous * 100).round(1)
+    else # :point and :absolute are both current - previous
+      (current - previous).round(1)
+    end
+  end
+end
diff --git a/enterprise/app/builders/captain/assistant_stats_window.rb b/enterprise/app/builders/captain/assistant_stats_window.rb
new file mode 100644
index 000000000..4495ef1e8
--- /dev/null
+++ b/enterprise/app/builders/captain/assistant_stats_window.rb
@@ -0,0 +1,78 @@
+# Resolves the current and previous comparison windows for Captain assistant
+# stats. `range` is either a day count ('7', '30', '90') or a named period
+# ('this_month', 'last_month'). The previous window mirrors the current one: the
+# preceding N days for day ranges, or the preceding month for month ranges.
+# `timezone_offset` is the viewer's UTC offset in hours (as the reports API sends
+# it), so month/day boundaries anchor to the viewer's day rather than UTC.
+#
+# Shared by Captain::AssistantStatsBuilder (which needs both windows) and
+# Captain::AssistantDrilldownBuilder (which drills into the current window), so a
+# drilldown always covers exactly the rows its stat card counted.
+class Captain::AssistantStatsWindow
+  include TimezoneHelper
+
+  DEFAULT_RANGE = '30'.freeze
+  ALLOWED_RANGES = %w[7 30 90 this_month last_month].freeze
+
+  attr_reader :range
+
+  def initialize(range = DEFAULT_RANGE, timezone_offset = nil)
+    @range = ALLOWED_RANGES.include?(range.to_s) ? range.to_s : DEFAULT_RANGE
+    @timezone = timezone_name_from_offset(timezone_offset) || Time.zone
+  end
+
+  def current
+    resolved_ranges[:current]
+  end
+
+  def previous
+    resolved_ranges[:previous]
+  end
+
+  # Human-readable description of the period the current window covers, for
+  # grounding the LLM summary in real dates.
+  def period
+    { label: period_label, starts_on: current.first.to_date, ends_on: current.last.to_date }
+  end
+
+  private
+
+  def resolved_ranges
+    @resolved_ranges ||= case range
+                         when 'this_month' then this_month_ranges
+                         when 'last_month' then last_month_ranges
+                         else day_ranges
+                         end
+  end
+
+  # Current time anchored to the viewer's timezone, so calendar boundaries land on
+  # the viewer's day instead of UTC's.
+  def now
+    @now ||= Time.current.in_time_zone(@timezone)
+  end
+
+  def this_month_ranges
+    start = now.beginning_of_month
+    elapsed = now - start
+    previous_start = start - 1.month
+    # Clamp to the previous month's end so a longer current month can't pull the
+    # comparison window into the current month and double-count its rows.
+    previous_end = [previous_start + elapsed, previous_start.end_of_month].min
+    { current: start..now, previous: previous_start..previous_end }
+  end
+
+  def last_month_ranges
+    start = (now - 1.month).beginning_of_month
+    previous_start = start - 1.month
+    { current: start..start.end_of_month, previous: previous_start..previous_start.end_of_month }
+  end
+
+  def day_ranges
+    days = range.to_i
+    { current: (now - days.days)..now, previous: (now - (2 * days).days)..(now - days.days) }
+  end
+
+  def period_label
+    { 'this_month' => 'this month', 'last_month' => 'last month' }[range] || "the last #{range.to_i} days"
+  end
+end
diff --git a/enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb b/enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb
index df9dfe5cc..4fbb93d20 100644
--- a/enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb
+++ b/enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb
@@ -2,7 +2,7 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
   before_action :current_account
   before_action -> { check_authorization(Captain::Assistant) }
 
-  before_action :set_assistant, only: [:show, :update, :destroy, :playground]
+  before_action :set_assistant, only: [:show, :update, :destroy, :playground, :stats, :summary, :drilldown]
 
   def index
     @assistants = account_assistants.ordered
@@ -43,8 +43,53 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
     @tools = assistant.available_agent_tools
   end
 
+  def stats
+    render json: Captain::AssistantStatsBuilder.new(@assistant, params[:range], params[:timezone_offset]).metrics
+  end
+
+  def summary
+    result = cached_or_generated_summary(Captain::AssistantStatsBuilder.new(@assistant, params[:range], params[:timezone_offset]))
+
+    if result[:error]
+      render json: { error: result[:error] }, status: :unprocessable_content
+    else
+      render json: { message: result[:message] }
+    end
+  end
+
+  def drilldown
+    return head :unprocessable_entity unless Captain::AssistantDrilldownBuilder.supported_metric?(params[:metric])
+
+    render json: Captain::AssistantDrilldownBuilder.new(@assistant, drilldown_params).build
+  end
+
   private
 
+  def drilldown_params
+    params.permit(:metric, :range, :timezone_offset, :page, :per_page)
+  end
+
+  def cached_or_generated_summary(builder)
+    cache_key = summary_cache_key(builder.range)
+    cached = Rails.cache.read(cache_key)
+    return cached if cached
+
+    result = Captain::OverviewSummaryService.new(
+      account: Current.account,
+      assistant: @assistant,
+      first_name: Current.user.name.to_s.split.first,
+      stats: builder.metrics,
+      period: builder.period
+    ).perform
+    # Don't cache transient LLM/config failures, otherwise every reload returns 422 for the next hour.
+    Rails.cache.write(cache_key, result, expires_in: 1.hour) unless result[:error]
+    result
+  end
+
+  def summary_cache_key(range)
+    "captain_overview_summary/#{@assistant.id}/#{Current.user.id}/#{range}/#{Date.current}"
+  end
+
   def set_assistant
     @assistant = account_assistants.find(params[:id])
   end
diff --git a/enterprise/app/policies/captain/assistant_policy.rb b/enterprise/app/policies/captain/assistant_policy.rb
index bbde3ffb0..573c0400c 100644
--- a/enterprise/app/policies/captain/assistant_policy.rb
+++ b/enterprise/app/policies/captain/assistant_policy.rb
@@ -11,6 +11,14 @@ class Captain::AssistantPolicy < ApplicationPolicy
     true
   end
 
+  def summary?
+    true
+  end
+
+  def drilldown?
+    @account_user.administrator?
+  end
+
   def tools?
     @account_user.administrator?
   end
diff --git a/lib/captain/overview_summary_service.rb b/lib/captain/overview_summary_service.rb
new file mode 100644
index 000000000..e11132d42
--- /dev/null
+++ b/lib/captain/overview_summary_service.rb
@@ -0,0 +1,83 @@
+# Generates the LLM welcome summary for the Captain Overview page from the
+# assistant's stats hash (see Captain::AssistantStatsBuilder). Renders the
+# captain_overview_summary.liquid prompt and returns markdown.
+class Captain::OverviewSummaryService < Captain::BaseTaskService
+  pattr_initialize [:account!, :assistant!, :first_name!, :stats!, :period!]
+
+  def perform
+    api_response = make_api_call(
+      feature: 'editor',
+      messages: [
+        { role: 'system', content: system_prompt },
+        { role: 'user', content: 'Write the summary.' }
+      ]
+    )
+
+    return api_response if api_response[:error]
+
+    { message: api_response[:message] }
+  end
+
+  private
+
+  def system_prompt
+    Liquid::Template.parse(prompt_from_file('captain_overview_summary')).render(prompt_variables)
+  end
+
+  def prompt_variables
+    stat_variables.merge(period_variables)
+  end
+
+  def stat_variables
+    {
+      'first_name' => first_name.to_s,
+      'assistant_name' => assistant.name.to_s,
+      'conversations_handled' => current(:conversations_handled),
+      'hours_saved' => current(:hours_saved),
+      'auto_resolution_rate' => current(:auto_resolution_rate),
+      'auto_resolution_trend' => trend(:auto_resolution_rate),
+      'handoff_rate' => current(:handoff_rate),
+      'handoff_trend' => trend(:handoff_rate),
+      'reopen_rate' => current(:reopen_rate),
+      'reopen_trend' => trend(:reopen_rate),
+      'knowledge_coverage' => stats.dig(:knowledge, :coverage).to_s,
+      'knowledge_approved' => stats.dig(:knowledge, :approved).to_s,
+      'knowledge_documents' => stats.dig(:knowledge, :documents).to_s
+    }
+  end
+
+  def period_variables
+    {
+      'today' => formatted_date(Time.zone.today),
+      'period_label' => period[:label].to_s,
+      'period_start' => formatted_date(period[:starts_on]),
+      'period_end' => formatted_date(period[:ends_on])
+    }
+  end
+
+  def formatted_date(date)
+    date.strftime('%B %-d, %Y')
+  end
+
+  def current(key)
+    stats.dig(key, :current).to_s
+  end
+
+  def trend(key)
+    stats.dig(key, :trend).to_s
+  end
+
+  def event_name
+    'captain_overview_summary'
+  end
+
+  def use_account_openai_hook?
+    true
+  end
+
+  # The overview summary is an internal analytics readout, not a customer-facing
+  # response, so it should not consume or be blocked by the captain_responses quota.
+  def counts_toward_usage?
+    false
+  end
+end
diff --git a/lib/integrations/openai/openai_prompts/captain_overview_summary.liquid b/lib/integrations/openai/openai_prompts/captain_overview_summary.liquid
new file mode 100644
index 000000000..19c32ed7c
--- /dev/null
+++ b/lib/integrations/openai/openai_prompts/captain_overview_summary.liquid
@@ -0,0 +1,38 @@
+You are writing a short, warm summary of how an AI support assistant named "{{ assistant_name }}" performed over a reporting period, for {{ first_name }}, the person who manages it.
+
+Voice and format:
+- Address {{ first_name }} directly and open with "Hey {{ first_name }},". Be conversational, never robotic.
+- Always call the assistant by its name, {{ assistant_name }}. Never call it "Captain", "the assistant", or "your assistant".
+- This is a static, read-only poster on an analytics dashboard, not a chat. The reader cannot reply or ask you for anything. Never ask a question, invite a reply, offer further help, or say things like "let me know" or "I can dive in".
+- Write 2 to 4 sentences in one short paragraph. Add a second short paragraph only for a genuinely useful heads-up.
+- Output plain markdown only: no headings, lists, preamble, or sign-off. Do not use em dashes.
+- Never state an exact figure. This summary is cached and the live numbers keep moving, so a precise value would quickly look wrong. Round every number down to a clean approximation and soften it with words like "around", "roughly", "about", "nearly", "just over", or "upwards of". For example, render **1,248** as "upwards of **1,200**", **63.2%** as "around **60%**", and **612** hours as "roughly **600** hours". For a small count, use a loose phrase like "a handful" instead of the exact number.
+- Wrap the approximate figure in **double asterisks** so the interface can highlight it. Bold only the figures, never whole phrases or the softening word.
+
+Timing: today is {{ today }}. These stats cover {{ period_label }} ({{ period_start }} to {{ period_end }}). You may lightly reference the month, the season, or how far into the period things stand when it genuinely fits, but never invent events or facts.
+
+The stats for this period:
+<stats>
+- Conversations handled: {{ conversations_handled }}. Distinct conversations {{ assistant_name }} replied in at least once. Raw volume and adoption, not a measure of quality.
+- Hours saved: {{ hours_saved }} hours. A rough, directional estimate of agent time saved. A feel-good figure, not exact measured labor.
+- Auto-resolution rate: {{ auto_resolution_rate }}% ({{ auto_resolution_trend }} points vs previous period). Of the conversations it handled, the share {{ assistant_name }} resolved on its own with no human reply. The core performance signal; higher is better.
+- Handoff rate: {{ handoff_rate }}% ({{ handoff_trend }} points vs previous period). Of the conversations it handled, the share it escalated to a human agent. The inverse of deflection; lower is better.
+- Reopen-after-resolve rate: {{ reopen_rate }}% ({{ reopen_trend }} points vs previous period). Of the conversations it auto-resolved, the share later reopened. A quality signal; lower is better, and a high value means it closed conversations the customer was not actually done with.
+- Knowledge base: {{ knowledge_approved }} approved FAQ answers, {{ knowledge_documents }} documents, {{ knowledge_coverage }}% coverage (the share of FAQ answers the team has approved). This is setup the team controls, not something {{ assistant_name }} earned. It is a leading indicator: low coverage tends to cause low auto-resolution.
+</stats>
+
+Only the auto-resolution, handoff, and reopen rates reflect how {{ assistant_name }} actually performed, and they are the only things worth crediting it for. Conversations handled and hours saved are context. The knowledge base is an input, never a win to praise.
+
+How to judge the numbers (rough bands, do not quote them in the summary):
+- Auto-resolution rate: below 30% is low and early-stage, 30 to 50% is decent, above 50% is genuinely strong.
+- Handoff rate: above 60% is high, 30 to 60% is moderate, below 30% is strong.
+- Reopen-after-resolve rate: below 5% is healthy, 5 to 15% is worth watching, above 15% is a real problem.
+- Knowledge coverage: only worth mentioning when below 85% (below 60% is seriously thin), as a likely cause of weak auto-resolution. At 85% or above it is just the healthy baseline, so do not mention or praise it.
+- When the conversation volume is small (roughly under 30), rates are noisy, so describe them tentatively and do not over-interpret a perfect or terrible looking percentage.
+
+Writing the summary:
+- Cold start: if conversations handled is 0, there is no performance to report. Skip the auto-resolution, handoff, reopen, and hours-saved figures entirely. Instead note the knowledge base and say {{ assistant_name }} is set up and ready to start handling support (or ready to start once some knowledge is added, if the base is empty). Ignore the rest of these points in this case.
+- Be honest and proportionate. Do not call a result impressive, strong, excellent, solid, flawless, or perfect unless it clears the "strong" band above. State a low or middling number plainly or as room to grow, never dressed up. A modest summary is fine and often correct.
+- Lead with the genuinely strong results if there are any. If nothing clears the strong band, open plainly with the volume of work handled, without overselling it.
+- Mention a trend only when it is meaningful, and judge it against the bands rather than the direction alone (a rate that rose but is still in the low band is not yet a win).
+- Surface at most one proactive concern when a stat warrants it (a high handoff rate, a low auto-resolution rate, a rising reopen rate, or thin coverage). Skip it entirely when everything looks healthy. Keep it a calm observation about the data, not an alarm.
diff --git a/lib/seeders/reports/assistant_conversation_creator.rb b/lib/seeders/reports/assistant_conversation_creator.rb
new file mode 100644
index 000000000..542da1b42
--- /dev/null
+++ b/lib/seeders/reports/assistant_conversation_creator.rb
@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'faker'
+require 'active_support/testing/time_helpers'
+
+# Seeds Captain assistant activity for the reports/overview test data.
+#
+# Produces a variety of assistant-handled conversations in a single web inbox so
+# every Captain assistant overview metric (handled, auto-resolution, handoff,
+# hours saved, reopen rate, conversation depth) has realistic data:
+#   - :resolved_by_assistant  assistant answers and Captain auto-resolves
+#   - :handled_by_both        assistant answers, a human also replies and resolves
+#   - :handed_off             assistant answers, then hands off to a human
+#   - :resolved_and_reopened  Captain resolves, then the conversation reopens
+#
+# Reporting events are fired through ReportingEventListener directly (mirroring
+# ConversationCreator) so the same rows the builder reads from get populated.
+class Seeders::Reports::AssistantConversationCreator
+  include ActiveSupport::Testing::TimeHelpers
+
+  OUTCOMES = %i[resolved_by_assistant handled_by_both handed_off resolved_and_reopened].freeze
+
+  def initialize(account:, assistant:, inbox:, resources:)
+    @account = account
+    @assistant = assistant
+    @inbox = inbox
+    @contacts = resources[:contacts]
+    @agents = inbox.members.to_a.presence || resources[:agents]
+  end
+
+  def create_conversation(created_at:, outcome:)
+    conversation = nil
+
+    travel_to(created_at) do
+      conversation = build_conversation
+      conversation.save!
+      seed_dialogue(conversation, outcome)
+    end
+    travel_back
+
+    apply_outcome(conversation, created_at, outcome)
+    conversation
+  end
+
+  private
+
+  def build_conversation
+    contact = @contacts.sample
+    contact_inbox = @inbox.contact_inboxes.find_or_create_by!(contact: contact, source_id: SecureRandom.hex)
+
+    contact_inbox.conversations.create!(
+      account: @account,
+      inbox: @inbox,
+      contact: contact,
+      priority: [nil, 'high', 'medium', 'low'].sample
+    )
+  end
+
+  # Builds the message exchange for the conversation while time is frozen at its
+  # creation moment. Every outcome starts with a customer question and at least
+  # one public assistant reply so the conversation lands in the assistant's
+  # handled set; some outcomes add a human reply or a handoff.
+  def seed_dialogue(conversation, outcome)
+    customer_message = incoming_message(conversation)
+
+    travel(rand((20.seconds)..(5.minutes)))
+    assistant_reply(conversation, waiting_since: customer_message.created_at)
+
+    case outcome
+    when :handed_off then seed_handoff(conversation)
+    when :handled_by_both then seed_human_turn(conversation)
+    else seed_assistant_follow_up(conversation)
+    end
+  end
+
+  def seed_handoff(conversation)
+    travel(rand((1.minute)..(10.minutes)))
+    handoff_to_human(conversation)
+    travel(rand((1.minute)..(15.minutes)))
+    human_reply(conversation)
+  end
+
+  def seed_human_turn(conversation)
+    travel(rand((1.minute)..(15.minutes)))
+    human_reply(conversation)
+  end
+
+  # Pure assistant threads occasionally take a second turn, giving depth > 1.
+  def seed_assistant_follow_up(conversation)
+    return unless rand < 0.6
+
+    travel(rand((1.minute)..(10.minutes)))
+    incoming_message(conversation)
+    travel(rand((20.seconds)..(5.minutes)))
+    assistant_reply(conversation, waiting_since: Time.current)
+  end
+
+  def apply_outcome(conversation, created_at, outcome)
+    resolved_at = created_at + rand((30.minutes)..(8.hours))
+
+    case outcome
+    when :resolved_by_assistant
+      resolve_by_captain(conversation, resolved_at)
+    when :handled_by_both
+      resolve_by_human(conversation, resolved_at)
+    when :handed_off
+      resolve_by_human(conversation, resolved_at) if rand < 0.6
+    when :resolved_and_reopened
+      resolve_by_captain(conversation, resolved_at)
+      reopen(conversation, resolved_at + rand((1.hour)..(24.hours)))
+    end
+  end
+
+  def incoming_message(conversation)
+    conversation.messages.create!(
+      account: @account,
+      inbox: @inbox,
+      message_type: :incoming,
+      content: Faker::Lorem.paragraph(sentence_count: rand(1..3)),
+      sender: conversation.contact
+    )
+  end
+
+  def assistant_reply(conversation, waiting_since:)
+    message = conversation.messages.create!(
+      account: @account,
+      inbox: @inbox,
+      message_type: :outgoing,
+      private: false,
+      content: Faker::Lorem.paragraph(sentence_count: rand(1..4)),
+      sender: @assistant
+    )
+    trigger_reply_time(message, waiting_since)
+    message
+  end
+
+  def human_reply(conversation)
+    agent = @agents.sample
+    conversation.update_column(:assignee_id, agent.id) if conversation.assignee_id.nil? # rubocop:disable Rails/SkipsModelValidations
+
+    conversation.messages.create!(
+      account: @account,
+      inbox: @inbox,
+      message_type: :outgoing,
+      private: false,
+      content: Faker::Lorem.paragraph(sentence_count: rand(1..4)),
+      sender: agent
+    )
+  end
+
+  def resolve_by_captain(conversation, resolved_at)
+    mark_resolved(conversation, resolved_at)
+    travel_to(resolved_at) do
+      trigger_event('conversation_resolved', conversation)
+      trigger_event('conversation_captain_inference_resolved', conversation)
+    end
+    travel_back
+  end
+
+  def resolve_by_human(conversation, resolved_at)
+    mark_resolved(conversation, resolved_at)
+    travel_to(resolved_at) do
+      trigger_event('conversation_resolved', conversation)
+    end
+    travel_back
+  end
+
+  def reopen(conversation, reopened_at)
+    # rubocop:disable Rails/SkipsModelValidations
+    conversation.update_column(:status, :open)
+    conversation.update_column(:updated_at, reopened_at)
+    # rubocop:enable Rails/SkipsModelValidations
+
+    travel_to(reopened_at) do
+      trigger_event('conversation_opened', conversation)
+    end
+    travel_back
+  end
+
+  def handoff_to_human(conversation)
+    trigger_event('conversation_captain_inference_handoff', conversation)
+  end
+
+  def mark_resolved(conversation, resolved_at)
+    # rubocop:disable Rails/SkipsModelValidations
+    conversation.update_column(:status, :resolved)
+    conversation.update_column(:updated_at, resolved_at)
+    # rubocop:enable Rails/SkipsModelValidations
+  end
+
+  def trigger_event(name, conversation)
+    ReportingEventListener.instance.public_send(
+      name, Events::Base.new(name, Time.current, { conversation: conversation })
+    )
+  end
+
+  def trigger_reply_time(message, waiting_since)
+    ReportingEventListener.instance.reply_created(
+      Events::Base.new('reply_created', Time.current,
+                       { message: message, conversation: message.conversation, waiting_since: waiting_since })
+    )
+  end
+end
diff --git a/lib/seeders/reports/report_data_seeder.rb b/lib/seeders/reports/report_data_seeder.rb
index 909818b72..fecb02deb 100644
--- a/lib/seeders/reports/report_data_seeder.rb
+++ b/lib/seeders/reports/report_data_seeder.rb
@@ -17,6 +17,9 @@
 #   - 5 teams with realistic distribution
 #   - 30 labels with random assignments
 #   - 3 inboxes with agent assignments
+#   - 1 Captain assistant bound to a single web inbox, with knowledge (FAQs + documents)
+#     and a variety of assistant-handled conversations (auto-resolved, handed off,
+#     handled with a human, resolved-then-reopened) for the assistant overview page
 #   - Realistic reporting events with historical timestamps
 #
 # Note: This seeder clears existing data for the account before seeding.
@@ -24,8 +27,9 @@
 require 'faker'
 require_relative 'conversation_creator'
 require_relative 'message_creator'
+require_relative 'assistant_conversation_creator'
 
-# rubocop:disable Rails/Output
+# rubocop:disable Rails/Output, Metrics/ClassLength
 class Seeders::Reports::ReportDataSeeder
   include ActiveSupport::Testing::TimeHelpers
 
@@ -36,6 +40,11 @@ class Seeders::Reports::ReportDataSeeder
   TOTAL_LABELS = 30
   TOTAL_INBOXES = 3
   MESSAGES_PER_CONVERSATION = 5
+  # Captain assistant conversations, split across the outcomes the overview page reports on.
+  TOTAL_ASSISTANT_CONVERSATIONS = 120
+  ASSISTANT_KNOWLEDGE_APPROVED = 14
+  ASSISTANT_KNOWLEDGE_PENDING = 6
+  ASSISTANT_DOCUMENTS = 4
   START_DATE = 3.months.ago # rubocop:disable Rails/RelativeDateConstant
   END_DATE = Time.current
 
@@ -48,6 +57,8 @@ class Seeders::Reports::ReportDataSeeder
     @labels = []
     @inboxes = []
     @contacts = []
+    @assistant = nil
+    @assistant_inbox = nil
   end
 
   def perform!
@@ -61,8 +72,10 @@ class Seeders::Reports::ReportDataSeeder
     create_labels
     create_inboxes
     create_contacts
+    create_assistant
 
     create_conversations
+    create_assistant_conversations
 
     puts "Completed reports data seeding for account: #{@account.name}"
   end
@@ -71,6 +84,7 @@ class Seeders::Reports::ReportDataSeeder
 
   def clear_existing_data
     puts "Clearing existing data for account: #{@account.id}"
+    clear_assistant_data
     @account.teams.destroy_all
     @account.conversations.destroy_all
     @account.labels.destroy_all
@@ -80,6 +94,16 @@ class Seeders::Reports::ReportDataSeeder
     @account.reporting_events.destroy_all
   end
 
+  # Delete Captain records directly (assistant associations are destroy_async, which
+  # would leave rows around mid-reseed); order respects foreign keys.
+  def clear_assistant_data
+    assistant_ids = Captain::Assistant.for_account(@account.id).select(:id)
+    Captain::AssistantResponse.by_account(@account.id).delete_all
+    Captain::Document.for_account(@account.id).delete_all
+    CaptainInbox.where(captain_assistant_id: assistant_ids).delete_all
+    Captain::Assistant.for_account(@account.id).delete_all
+  end
+
   def create_teams
     TOTAL_TEAMS.times do |i|
       team = @account.teams.create!(
@@ -208,6 +232,80 @@ class Seeders::Reports::ReportDataSeeder
     print "\n"
   end
 
+  # One assistant, bound to a single web inbox (the first one), as the overview page expects.
+  def create_assistant
+    @account.enable_features!('captain_integration', 'captain_integration_v2')
+    @assistant_inbox = @inboxes.first
+    @assistant = Captain::Assistant.create!(
+      account: @account,
+      name: "#{Faker::Company.name} Copilot",
+      description: 'Captain assistant handling website support conversations.',
+      config: { feature_faq: true, feature_memory: true, product_name: @account.name }
+    )
+    CaptainInbox.create!(captain_assistant: @assistant, inbox: @assistant_inbox)
+    create_assistant_knowledge
+
+    puts "Created assistant '#{@assistant.name}' for inbox '#{@assistant_inbox.name}'"
+  end
+
+  def create_assistant_knowledge
+    ASSISTANT_KNOWLEDGE_APPROVED.times { create_assistant_response(:approved) }
+    ASSISTANT_KNOWLEDGE_PENDING.times { create_assistant_response(:pending) }
+
+    ASSISTANT_DOCUMENTS.times do
+      Captain::Document.create!(
+        account: @account,
+        assistant: @assistant,
+        name: Faker::Company.catch_phrase,
+        external_link: "https://#{Faker::Internet.domain_name}/#{Faker::Internet.slug}",
+        content: Faker::Lorem.paragraphs(number: rand(2..4)).join("\n\n"),
+        status: :available,
+        sync_status: :synced
+      )
+    end
+  end
+
+  def create_assistant_response(status)
+    Captain::AssistantResponse.create!(
+      account: @account,
+      assistant: @assistant,
+      question: "#{Faker::Lorem.sentence(word_count: rand(4..8)).chomp('.')}?",
+      answer: Faker::Lorem.paragraph(sentence_count: rand(2..4)),
+      status: status
+    )
+  end
+
+  def create_assistant_conversations
+    creator = Seeders::Reports::AssistantConversationCreator.new(
+      account: @account,
+      assistant: @assistant,
+      inbox: @assistant_inbox,
+      resources: { contacts: @contacts, agents: @agents }
+    )
+
+    outcomes = assistant_outcome_distribution
+    outcomes.each_with_index do |outcome, i|
+      created_at = Faker::Time.between(from: 65.days.ago, to: END_DATE)
+      creator.create_conversation(created_at: created_at, outcome: outcome)
+
+      print "\rCreating assistant conversations: #{i + 1}/#{outcomes.size}"
+    end
+
+    print "\n"
+  end
+
+  # Weighted mix of outcomes so every overview metric has meaningful numbers, shuffled
+  # so they interleave across the time span rather than clustering by type.
+  def assistant_outcome_distribution
+    counts = {
+      resolved_by_assistant: (TOTAL_ASSISTANT_CONVERSATIONS * 0.4).round,
+      handled_by_both: (TOTAL_ASSISTANT_CONVERSATIONS * 0.25).round,
+      handed_off: (TOTAL_ASSISTANT_CONVERSATIONS * 0.2).round,
+      resolved_and_reopened: (TOTAL_ASSISTANT_CONVERSATIONS * 0.15).round
+    }
+    counts.flat_map { |outcome, count| [outcome] * count }.shuffle
+  end
+
   def create_conversations
     conversation_creator = Seeders::Reports::ConversationCreator.new(
       account: @account,
@@ -231,4 +329,4 @@ class Seeders::Reports::ReportDataSeeder
     print "\n"
   end
 end
-# rubocop:enable Rails/Output
+# rubocop:enable Rails/Output, Metrics/ClassLength
diff --git a/spec/enterprise/builders/captain/assistant_stats_builder_spec.rb b/spec/enterprise/builders/captain/assistant_stats_builder_spec.rb
new file mode 100644
index 000000000..6575c9856
--- /dev/null
+++ b/spec/enterprise/builders/captain/assistant_stats_builder_spec.rb
@@ -0,0 +1,271 @@
+require 'rails_helper'
+
+RSpec.describe Captain::AssistantStatsBuilder do
+  let(:account) { create(:account) }
+  let(:assistant) { create(:captain_assistant, account: account) }
+  let(:inbox) { create(:inbox, account: account) }
+
+  before { create(:captain_inbox, captain_assistant: assistant, inbox: inbox) }
+
+  describe '#metrics' do
+    # Two conversations handled in the current 30-day window, one in the previous.
+    let(:current_convo_a) { create(:conversation, account: account, inbox: inbox) }
+    let(:current_convo_b) { create(:conversation, account: account, inbox: inbox) }
+    let(:previous_convo) { create(:conversation, account: account, inbox: inbox) }
+
+    before do
+      [current_convo_a, current_convo_b].each do |conversation|
+        create(:message, account: account, inbox: inbox, conversation: conversation,
+                         sender: assistant, message_type: :outgoing, private: false, created_at: 5.days.ago)
+      end
+      create(:message, account: account, inbox: inbox, conversation: previous_convo,
+                       sender: assistant, message_type: :outgoing, private: false, created_at: 45.days.ago)
+    end
+
+    it 'returns every metric for the current and previous window' do
+      metrics = described_class.new(assistant, '30').metrics
+
+      expect(metrics.keys).to contain_exactly(
+        :conversations_handled, :auto_resolution_rate, :handoff_rate,
+        :hours_saved, :reopen_rate, :conversation_depth, :knowledge
+      )
+      expect(metrics[:conversations_handled]).to include(:current, :previous, :trend)
+    end
+
+    it 'counts distinct handled conversations per window and the percent trend' do
+      handled = described_class.new(assistant, '30').metrics[:conversations_handled]
+
+      expect(handled[:current]).to eq(2)
+      expect(handled[:previous]).to eq(1)
+      expect(handled[:trend]).to eq(100.0)
+    end
+
+    it 'derives auto-resolution and handoff rates from reporting events on the handled set' do
+      create(:reporting_event, account: account, conversation: current_convo_a,
+                               name: 'conversation_captain_inference_resolved')
+      create(:reporting_event, account: account, conversation: current_convo_b,
+                               name: 'conversation_captain_inference_handoff')
+
+      metrics = described_class.new(assistant, '30').metrics
+
+      expect(metrics[:auto_resolution_rate][:current]).to eq(50.0)
+      expect(metrics[:handoff_rate][:current]).to eq(50.0)
+    end
+
+    it 'does not count a bot resolve as an auto-resolution when the conversation was handed off' do
+      # convo_a: handoff, customer goes quiet, resolve lands without an agent message, so the
+      # listener still emits conversation_bot_resolved for the handed-off conversation. It must
+      # not count as an auto-resolution, but still counts as a handoff.
+      create(:reporting_event, account: account, conversation: current_convo_a,
+                               name: 'conversation_bot_handoff')
+      create(:reporting_event, account: account, conversation: current_convo_a,
+                               name: 'conversation_bot_resolved')
+      # convo_b: a clean bot resolve with no handoff still counts, so the exclusion is scoped
+      # to handed-off conversations and doesn't drop every bot resolve.
+      create(:reporting_event, account: account, conversation: current_convo_b,
+                               name: 'conversation_bot_resolved')
+
+      metrics = described_class.new(assistant, '30').metrics
+
+      expect(metrics[:auto_resolution_rate][:current]).to eq(50.0)
+      expect(metrics[:handoff_rate][:current]).to eq(50.0)
+    end
+
+    it 'still counts an inference resolve when the conversation was also handed off' do
+      create(:reporting_event, account: account, conversation: current_convo_a,
+                               name: 'conversation_captain_inference_handoff')
+      create(:reporting_event, account: account, conversation: current_convo_a,
+                               name: 'conversation_captain_inference_resolved')
+
+      metrics = described_class.new(assistant, '30').metrics
+
+      expect(metrics[:auto_resolution_rate][:current]).to eq(50.0)
+      expect(metrics[:handoff_rate][:current]).to eq(50.0)
+    end
+
+    it 'excludes resolution events that fall outside the current window' do
+      create(:reporting_event, account: account, conversation: current_convo_a,
+                               name: 'conversation_captain_inference_resolved', created_at: 60.days.ago)
+
+      metrics = described_class.new(assistant, '30').metrics
+
+      expect(metrics[:auto_resolution_rate][:current]).to eq(0.0)
+    end
+
+    it 'computes conversation depth as public replies per handled conversation' do
+      depth = described_class.new(assistant, '30').metrics[:conversation_depth]
+
+      # 2 public outgoing replies across 2 distinct conversations in the current window.
+      expect(depth[:current]).to eq(1.0)
+    end
+
+    it 'ignores private notes and incoming messages when counting public replies' do
+      create(:message, account: account, inbox: inbox, conversation: current_convo_a,
+                       sender: assistant, message_type: :outgoing, private: true, created_at: 5.days.ago)
+
+      depth = described_class.new(assistant, '30').metrics[:conversation_depth]
+
+      expect(depth[:current]).to eq(1.0)
+    end
+  end
+
+  describe 'range handling' do
+    it 'accepts the allowed day and named ranges' do
+      %w[7 30 90 this_month last_month].each do |allowed|
+        expect(described_class.new(assistant, allowed).range).to eq(allowed)
+      end
+    end
+
+    it 'falls back to the default range for values outside the allowed set' do
+      expect(described_class.new(assistant, '365000').range).to eq('30')
+      expect(described_class.new(assistant, 'bogus').range).to eq('30')
+      expect(described_class.new(assistant, nil).range).to eq('30')
+    end
+  end
+
+  describe '#metrics reopen_rate' do
+    # A conversation the assistant handled (messaged) inside the current 30-day window.
+    let(:conversation) { create(:conversation, account: account, inbox: inbox) }
+
+    before do
+      create(:message, account: account, inbox: inbox, conversation: conversation,
+                       sender: assistant, message_type: :outgoing, private: false, created_at: 8.days.ago)
+    end
+
+    it 'counts a reopen that happened after the captain resolve' do
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_bot_resolved', event_start_time: 6.days.ago, event_end_time: 6.days.ago)
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_opened', value: 120, event_start_time: 6.days.ago, event_end_time: 4.days.ago)
+
+      expect(described_class.new(assistant, '30').metrics[:reopen_rate][:current]).to eq(100.0)
+    end
+
+    it 'ignores a human resolve/reopen that happened before the captain resolve' do
+      # Earlier resolve/reopen cycle, then Captain resolves later in the same window.
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_opened', value: 120, event_start_time: 20.days.ago, event_end_time: 18.days.ago)
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_bot_resolved', event_start_time: 5.days.ago, event_end_time: 5.days.ago)
+
+      expect(described_class.new(assistant, '30').metrics[:reopen_rate][:current]).to eq(0.0)
+    end
+
+    it 'counts an evaluated-path reopen when bot_resolved is skipped and the inference event is newer' do
+      # Prior human reply => create_bot_resolved_event skips conversation_bot_resolved, so the cohort
+      # only holds the inference event, which is dispatched a moment after the generic conversation_resolved
+      # that seeds the reopen's event_start_time. The match must use the reopen's actual reopen time.
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_captain_inference_resolved',
+                               event_start_time: 6.days.ago, event_end_time: 6.days.ago + 1.second)
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_opened', value: 120, event_start_time: 6.days.ago, event_end_time: 3.days.ago)
+
+      expect(described_class.new(assistant, '30').metrics[:reopen_rate][:current]).to eq(100.0)
+    end
+
+    it 'counts both inference and time-based bot resolves in the denominator' do
+      # conversation: inference-resolved and reopened
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_captain_inference_resolved', event_start_time: 6.days.ago, event_end_time: 6.days.ago)
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_opened', value: 120, event_start_time: 6.days.ago, event_end_time: 4.days.ago)
+      # other: time-based bot-resolved, never reopened
+      other = create(:conversation, account: account, inbox: inbox)
+      create(:message, account: account, inbox: inbox, conversation: other,
+                       sender: assistant, message_type: :outgoing, private: false, created_at: 8.days.ago)
+      create(:reporting_event, account: account, inbox: inbox, conversation: other,
+                               name: 'conversation_bot_resolved', event_start_time: 6.days.ago, event_end_time: 6.days.ago)
+
+      expect(described_class.new(assistant, '30').metrics[:reopen_rate][:current]).to eq(50.0)
+    end
+
+    it 'ignores a reopen that landed after a completed window ended' do
+      travel_to(Time.utc(2026, 7, 15)) do
+        convo = create(:conversation, account: account, inbox: inbox)
+        create(:message, account: account, inbox: inbox, conversation: convo,
+                         sender: assistant, message_type: :outgoing, private: false, created_at: Time.utc(2026, 6, 10))
+        create(:reporting_event, account: account, inbox: inbox, conversation: convo,
+                                 name: 'conversation_bot_resolved', created_at: Time.utc(2026, 6, 12),
+                                 event_start_time: Time.utc(2026, 6, 12), event_end_time: Time.utc(2026, 6, 12))
+        # Reopened on July 1, after the June window closed; June's rate must not count it.
+        create(:reporting_event, account: account, inbox: inbox, conversation: convo,
+                                 name: 'conversation_opened', value: 120,
+                                 event_start_time: Time.utc(2026, 6, 12), event_end_time: Time.utc(2026, 7, 1))
+
+        expect(described_class.new(assistant, 'last_month').metrics[:reopen_rate][:current]).to eq(0.0)
+      end
+    end
+
+    it 'derives the cohort from handled conversations, not current inbox membership' do
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_captain_inference_resolved', event_start_time: 6.days.ago, event_end_time: 6.days.ago)
+      create(:reporting_event, account: account, inbox: inbox, conversation: conversation,
+                               name: 'conversation_opened', value: 120, event_start_time: 6.days.ago, event_end_time: 4.days.ago)
+      # The assistant is later removed from the inbox; the cohort must still resolve via handled messages.
+      CaptainInbox.where(captain_assistant: assistant).delete_all
+
+      expect(described_class.new(assistant, '30').metrics[:reopen_rate][:current]).to eq(100.0)
+    end
+  end
+
+  describe 'timezone anchoring' do
+    # 2026-07-01 03:00 UTC is still 2026-06-30 in any timezone behind UTC by 4h+.
+    it 'anchors the this_month window to the supplied offset, not UTC' do
+      travel_to(Time.utc(2026, 7, 1, 3, 0, 0)) do
+        utc = described_class.new(assistant, 'this_month').period
+        la = described_class.new(assistant, 'this_month', -7).period
+
+        expect(utc[:starts_on]).to eq(Date.new(2026, 7, 1))
+        expect(la[:starts_on]).to eq(Date.new(2026, 6, 1))
+        expect(la[:ends_on]).to eq(Date.new(2026, 6, 30))
+      end
+    end
+
+    it 'defaults to UTC when no offset is given' do
+      travel_to(Time.utc(2026, 7, 1, 3, 0, 0)) do
+        expect(described_class.new(assistant, 'this_month').period[:starts_on]).to eq(Date.new(2026, 7, 1))
+      end
+    end
+  end
+
+  describe '#metrics knowledge' do
+    before do
+      create_list(:captain_assistant_response, 3, assistant: assistant, account: account, status: :approved)
+      create(:captain_assistant_response, assistant: assistant, account: account, status: :pending)
+      create_list(:captain_document, 2, assistant: assistant, account: account)
+    end
+
+    it 'returns approved, pending, document counts and coverage' do
+      knowledge = described_class.new(assistant, '30').metrics[:knowledge]
+
+      expect(knowledge).to eq(approved: 3, pending: 1, documents: 2, coverage: 75)
+    end
+
+    it 'reports zero coverage when there are no responses' do
+      Captain::AssistantResponse.where(assistant: assistant).delete_all
+
+      knowledge = described_class.new(assistant, '30').metrics[:knowledge]
+
+      expect(knowledge[:coverage]).to eq(0)
+    end
+  end
+
+  describe '#period' do
+    it 'labels a day range and exposes its bounds' do
+      period = described_class.new(assistant, '30').period
+
+      expect(period[:label]).to eq('the last 30 days')
+      expect(period[:starts_on]).to eq(30.days.ago.to_date)
+      expect(period[:ends_on]).to eq(Time.zone.today)
+    end
+
+    it 'labels the this_month range' do
+      expect(described_class.new(assistant, 'this_month').period[:label]).to eq('this month')
+    end
+
+    it 'labels the last_month range' do
+      expect(described_class.new(assistant, 'last_month').period[:label]).to eq('last month')
+    end
+  end
+end
diff --git a/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb b/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb
index 4689defaf..afb6aa2de 100644
--- a/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb
+++ b/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb
@@ -252,6 +252,48 @@ RSpec.describe 'Api::V1::Accounts::Captain::Assistants', type: :request do
     end
   end
 
+  describe 'GET /api/v1/accounts/{account.id}/captain/assistants/{id}/summary' do
+    let(:assistant) { create(:captain_assistant, account: account) }
+    let(:alice) { create(:user, account: account, role: :administrator, name: 'Alice Adams') }
+    let(:bob) { create(:user, account: account, role: :administrator, name: 'Bob Brown') }
+    let(:summary_service) { instance_double(Captain::OverviewSummaryService) }
+
+    def get_summary(user)
+      get "/api/v1/accounts/#{account.id}/captain/assistants/#{assistant.id}/summary",
+          params: { range: '30' },
+          headers: user.create_new_auth_token,
+          as: :json
+    end
+
+    before do
+      # Test env uses a null store; swap in a real store so caching behaviour is observable.
+      allow(Rails).to receive(:cache).and_return(ActiveSupport::Cache::MemoryStore.new)
+      allow(Captain::OverviewSummaryService).to receive(:new).and_return(summary_service)
+    end
+
+    it 'caches the summary per viewer so one user never receives another user\'s greeting' do
+      allow(summary_service).to receive(:perform).and_return({ message: 'Hi Alice' })
+
+      get_summary(alice)
+      get_summary(alice) # served from Alice's cache, no regeneration
+      get_summary(bob)   # distinct cache key, regenerated for Bob
+
+      expect(response).to have_http_status(:success)
+      expect(Captain::OverviewSummaryService).to have_received(:new).twice
+    end
+
+    it 'does not cache failures so a transient error is retried' do
+      allow(summary_service).to receive(:perform).and_return({ error: 'LLM unavailable' })
+
+      get_summary(alice)
+      get_summary(alice)
+
+      expect(response).to have_http_status(:unprocessable_content)
+      expect(json_response[:error]).to eq('LLM unavailable')
+      expect(Captain::OverviewSummaryService).to have_received(:new).twice
+    end
+  end
+
   describe 'POST /api/v1/accounts/{account.id}/captain/assistants/{id}/playground' do
     let(:assistant) { create(:captain_assistant, account: account) }
     let(:valid_params) do
diff --git a/spec/enterprise/policies/captain/assistant_policy_spec.rb b/spec/enterprise/policies/captain/assistant_policy_spec.rb
index e3c62846f..e04b680e4 100644
--- a/spec/enterprise/policies/captain/assistant_policy_spec.rb
+++ b/spec/enterprise/policies/captain/assistant_policy_spec.rb
@@ -22,7 +22,7 @@ RSpec.describe Captain::AssistantPolicy, type: :policy do
     end
   end
 
-  permissions :tools?, :create?, :update?, :destroy?, :sync? do
+  permissions :tools?, :create?, :update?, :destroy?, :sync?, :drilldown? do
     context 'when administrator' do
       it { expect(assistant_policy).to permit(administrator_context, assistant) }
     end

From 29d0b92f1c8b00b74686d89d389405185bdda5d0 Mon Sep 17 00:00:00 2001
From: Shivam Mishra <scm.mymail@gmail.com>
Date: Tue, 7 Jul 2026 19:16:24 +0530
Subject: [PATCH 08/17] fix: captain hours saved metric (#14948)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reworks the Captain assistant "hours saved" metric so it produces a
believable number. It previously multiplied assistant reply count by
customer reply-wait time, which inflated the figure into the millions of
hours. It now estimates saved time as replies × a fixed ~2 min per-reply
effort assumption. On the overview card the value renders in days once
it passes 100 hours, and the label/hint copy was updated to match.

## How to test
1. Open the Captain assistant overview page.
2. Check the "Time saved" card shows a sensible value (hours, or days
past 100h).
3. Hover the hint and confirm it reflects the per-reply estimate.
---
 .../i18n/locale/en/integrations.json          |  4 +--
 .../captain/assistants/overview/Index.vue     |  9 ++++--
 .../captain/assistant_stats_builder.rb        | 29 ++++++++-----------
 .../reports/assistant_conversation_creator.rb |  4 +--
 4 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/app/javascript/dashboard/i18n/locale/en/integrations.json b/app/javascript/dashboard/i18n/locale/en/integrations.json
index a39165268..a6f3ef2f2 100644
--- a/app/javascript/dashboard/i18n/locale/en/integrations.json
+++ b/app/javascript/dashboard/i18n/locale/en/integrations.json
@@ -427,8 +427,8 @@
           "HINT": "Share of handled conversations escalated to a human agent."
         },
         "HOURS_SAVED": {
-          "LABEL": "Hours saved",
-          "HINT": "Estimate: Captain replies times the team's average response time. Directional, not measured labor."
+          "LABEL": "Time saved",
+          "HINT": "Estimate: Captain replies times ~2 minutes of assumed agent effort per reply. Directional, not measured labor."
         },
         "REOPEN": {
           "LABEL": "Reopen rate",
diff --git a/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue b/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue
index 687e97286..b9cc6ae35 100644
--- a/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue
+++ b/app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue
@@ -49,6 +49,11 @@ const resolveTrendGood = (trendValue, direction) => {
 // :point, and a plain number for :absolute counts like conversation depth.
 const TREND_SUFFIX = { percent: '%', point: ' pts', absolute: '' };
 
+// Hours-saved is reported in hours, but large values read better as days. Past
+// 100h we switch the unit so the card stays legible.
+const formatDuration = hours =>
+  hours >= 100 ? `${Math.round(hours / 24)}d` : `${hours}h`;
+
 const metricFor = (statKey, formatValue, direction, trendKind = 'percent') => {
   const data = stats.value?.[statKey];
   if (!data) return { value: '—', trend: '', trendGood: null };
@@ -84,7 +89,7 @@ const metrics = computed(() => [
     key: 'hoursSaved',
     label: t('CAPTAIN.OVERVIEW.METRICS.HOURS_SAVED.LABEL'),
     hint: t('CAPTAIN.OVERVIEW.METRICS.HOURS_SAVED.HINT'),
-    ...metricFor('hours_saved', v => `${v}h`, 'up'),
+    ...metricFor('hours_saved', formatDuration, 'up'),
   },
   {
     key: 'reopen',
@@ -121,7 +126,7 @@ const metrics = computed(() => [
       <CaptainPaywall />
     </template>
     <template #body>
-      <div class="flex flex-col gap-6">
+      <div class="flex flex-col gap-6 pb-8">
         <InboxBanner />
 
         <CoverageBanner :knowledge="stats?.knowledge" />
diff --git a/enterprise/app/builders/captain/assistant_stats_builder.rb b/enterprise/app/builders/captain/assistant_stats_builder.rb
index 7198c39e1..d162406ad 100644
--- a/enterprise/app/builders/captain/assistant_stats_builder.rb
+++ b/enterprise/app/builders/captain/assistant_stats_builder.rb
@@ -3,13 +3,18 @@
 # window, plus a derived trend.
 #
 # Queries are batched to cut round trips: the message-derived counts (handled,
-# public replies, depth) and the average reply time are each computed for both
-# windows in a single scan via conditional FILTER aggregation.
+# public replies, depth) are computed for both windows in a single scan via
+# conditional FILTER aggregation.
 class Captain::AssistantStatsBuilder
   RESOLVED_EVENT_NAMES = %w[conversation_captain_inference_resolved conversation_bot_resolved].freeze
   HANDOFF_EVENT_NAMES = %w[conversation_captain_inference_handoff conversation_bot_handoff].freeze
   BOT_RESOLVED_EVENT_NAME = 'conversation_bot_resolved'.freeze
 
+  # Assumed agent effort displaced by each public assistant reply. Reporting data
+  # only captures reply latency (customer wait time), not handling effort, so hours
+  # saved is a count-times-assumed-effort estimate rather than a measured duration.
+  SECONDS_SAVED_PER_REPLY = 2.minutes.to_i
+
   attr_reader :assistant, :account
 
   delegate :range, :period, to: :window
@@ -26,9 +31,8 @@ class Captain::AssistantStatsBuilder
 
   def metrics
     messages = message_window_metrics
-    reply_times = avg_reply_times
-    current = window_metrics(current_range, messages[:current], reply_times[:current])
-    previous = window_metrics(previous_range, messages[:previous], reply_times[:previous])
+    current = window_metrics(current_range, messages[:current])
+    previous = window_metrics(previous_range, messages[:previous])
 
     build_metrics(current, previous)
   end
@@ -57,8 +61,8 @@ class Captain::AssistantStatsBuilder
     }
   end
 
-  # Combines the per-window message counts and reply time with the reporting-event metrics for one window.
-  def window_metrics(range, message_counts, avg_reply)
+  # Combines the per-window message counts with the reporting-event metrics for one window.
+  def window_metrics(range, message_counts)
     handled = message_counts[:handled]
     public_count = message_counts[:public_count]
     depth_conversations = message_counts[:depth_conversations]
@@ -68,7 +72,7 @@ class Captain::AssistantStatsBuilder
       handled: handled,
       auto_resolution: rate(resolution[:resolved], handled),
       handoff: rate(resolution[:handoff], handled),
-      hours_saved: (public_count * avg_reply / 3600.0).round,
+      hours_saved: (public_count * SECONDS_SAVED_PER_REPLY / 3600.0).round,
       reopen: reopen_rate(range),
       depth: depth_conversations.zero? ? 0 : (public_count.to_f / depth_conversations).round(1)
     }
@@ -96,15 +100,6 @@ class Captain::AssistantStatsBuilder
     }
   end
 
-  # Average reply time (seconds) for both windows in one scan.
-  def avg_reply_times
-    row = account.reporting_events.where(name: 'reply_time', created_at: full_span).reorder(nil).pick(
-      Arel.sql("AVG(value) FILTER (WHERE #{window_clause(current_range)})"),
-      Arel.sql("AVG(value) FILTER (WHERE #{window_clause(previous_range)})")
-    )
-    { current: row[0].to_f, previous: row[1].to_f }
-  end
-
   # Resolved and handed-off conversation counts for one window, in a single scan
   # of the handled set's reporting events.
   def resolution_counts(range)
diff --git a/lib/seeders/reports/assistant_conversation_creator.rb b/lib/seeders/reports/assistant_conversation_creator.rb
index 542da1b42..9462d899e 100644
--- a/lib/seeders/reports/assistant_conversation_creator.rb
+++ b/lib/seeders/reports/assistant_conversation_creator.rb
@@ -90,9 +90,9 @@ class Seeders::Reports::AssistantConversationCreator
     return unless rand < 0.6
 
     travel(rand((1.minute)..(10.minutes)))
-    incoming_message(conversation)
+    follow_up = incoming_message(conversation)
     travel(rand((20.seconds)..(5.minutes)))
-    assistant_reply(conversation, waiting_since: Time.current)
+    assistant_reply(conversation, waiting_since: follow_up.created_at)
   end
 
   def apply_outcome(conversation, created_at, outcome)

From ce8c8e9a11e5e5684f060f9cb858aa71728ea568 Mon Sep 17 00:00:00 2001
From: Muhsin Keloth <muhsinkeramam@gmail.com>
Date: Wed, 8 Jul 2026 05:04:24 +0400
Subject: [PATCH 09/17] fix: sanitize control characters in team names 
 (#14865)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Team names created via the API could contain control characters (for
example a trailing newline). Because the team-delete confirmation dialog
requires you to retype the team name and matches it against the stored
value, a hidden control character meant the typed name never matched —
leaving the team impossible to delete from the UI. This sanitizes team
names on save so they stay clean and deletable.

#### How to reproduce
1. Create a team via `POST /api/v1/accounts/{account_id}/teams` with
`{"name": "test\n"}`.
2. The team is created with the trailing newline stored in `name`.
3. In **Settings → Teams**, click delete and type the team name to
confirm — the match fails, so the team cannot be deleted.

#### What changed
- `app/models/team.rb`: the existing `before_validation` now strips
control characters and surrounding whitespace before downcasing the
name. Names that reduce to blank (e.g. only newlines/tabs) are rejected
loudly by the existing `presence` validation.
- Fixing at the model layer covers the API and every other create/update
path, rather than relying on the frontend confirm-dialog `.trim()`
(which only handles leading/trailing whitespace, not internal control
characters).

Note: this prevents new malformed names. Any team already saved with a
control character can be made deletable again simply by renaming it (an
update re-runs the same sanitization).

| Input | Stored as | Result |
|---|---|---|
| `"test\n"` | `"test"` | valid, deletable |
| `"te\nst"` (internal) | `"test"` | valid |
| `"\t\n "` (only control/ws) | — | rejected: "Name must not be blank" |
| `"Customer Support"` | `"customer support"` | unchanged behavior |

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Muhsin <12408980+muhsin-k@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/models/team.rb       |  2 +-
 spec/models/team_spec.rb | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/app/models/team.rb b/app/models/team.rb
index 48990b488..15de8ab56 100644
--- a/app/models/team.rb
+++ b/app/models/team.rb
@@ -30,7 +30,7 @@ class Team < ApplicationRecord
             uniqueness: { scope: :account_id }
 
   before_validation do
-    self.name = name.downcase if attribute_present?('name')
+    self.name = name.gsub(/[[:cntrl:]]/, '').strip.downcase if attribute_present?('name')
   end
 
   # Adds multiple members to the team
diff --git a/spec/models/team_spec.rb b/spec/models/team_spec.rb
index cb55dba61..8272b5925 100644
--- a/spec/models/team_spec.rb
+++ b/spec/models/team_spec.rb
@@ -7,6 +7,31 @@ RSpec.describe Team do
     it { is_expected.to have_many(:team_members) }
   end
 
+  describe 'name normalization' do
+    let(:account) { create(:account) }
+
+    it 'downcases the name' do
+      team = create(:team, account: account, name: 'Customer Support')
+      expect(team.name).to eq('customer support')
+    end
+
+    it 'strips control characters and surrounding whitespace' do
+      team = create(:team, account: account, name: "  Sales\n")
+      expect(team.name).to eq('sales')
+    end
+
+    it 'removes control characters embedded within the name' do
+      team = create(:team, account: account, name: "su\npport")
+      expect(team.name).to eq('support')
+    end
+
+    it 'is invalid when the name reduces to blank after sanitization' do
+      team = build(:team, account: account, name: "\t\n  ")
+      expect(team).not_to be_valid
+      expect(team.errors[:name]).to include(I18n.t('errors.validations.presence'))
+    end
+  end
+
   describe '#add_members' do
     let(:team) { FactoryBot.create(:team) }
 

From 0e07a27c743629e55d9fae61f1d941b15ba47b7a Mon Sep 17 00:00:00 2001
From: Sojan Jose <sojan@pepalo.com>
Date: Wed, 8 Jul 2026 02:18:07 -0700
Subject: [PATCH 10/17] fix: enforce inbox limits at model level (#14949)

Fixes https://linear.app/chatwoot/issue/CW-7559/inbox-limit-abuse

## Why

The regular inbox API checked limits in the controller, but WhatsApp
embedded signup creates inboxes through a service using `Inbox.create!`.
That let Enterprise account inbox limits be skipped for embedded signup.

## What this change does

- Adds an Inbox create-time validation hook in OSS and implements the
limit check in the Enterprise Inbox module.
- Removes the duplicate controller/helper limit check so the model is
the single enforcement point.
- Preserves the existing `402 Payment Required` API response for account
inbox limit failures.
- Keeps updates to existing inboxes allowed when an account is already
at its inbox limit.

## Validation

- `bundle exec rspec
spec/controllers/api/v1/accounts/inboxes_controller_spec.rb
spec/enterprise/models/inbox_spec.rb`
---
 .../api/v1/accounts/callbacks_controller.rb   |  3 ++
 .../channels/twilio_channels_controller.rb    |  2 ++
 .../api/v1/accounts/inboxes_controller.rb     |  1 -
 .../whatsapp/authorizations_controller.rb     |  6 ++--
 .../concerns/request_exception_handler.rb     |  5 +--
 .../instagram/callbacks_controller.rb         | 10 ++++++
 .../tiktok/callbacks_controller.rb            | 10 ++++++
 app/helpers/api/v1/inboxes_helper.rb          |  6 ----
 .../app/models/enterprise/concerns/inbox.rb   |  6 ++++
 lib/custom_exceptions/inbox/limit_exceeded.rb | 15 ++++++++
 .../v1/accounts/callbacks_controller_spec.rb  | 34 +++++++++++++++++++
 .../lib/captain/base_task_service_spec.rb     | 23 ++++++-------
 .../conversation_completion_service_spec.rb   | 10 ++++--
 spec/enterprise/models/inbox_spec.rb          | 23 +++++++++++++
 .../audio_transcription_service_spec.rb       |  8 ++++-
 spec/lib/captain/base_task_service_spec.rb    |  5 ++-
 .../mappers/conversation_mapper_spec.rb       |  1 +
 .../whatsapp/channel_creation_service_spec.rb | 11 ++++++
 18 files changed, 151 insertions(+), 28 deletions(-)
 create mode 100644 lib/custom_exceptions/inbox/limit_exceeded.rb
 create mode 100644 spec/enterprise/controllers/api/v1/accounts/callbacks_controller_spec.rb

diff --git a/app/controllers/api/v1/accounts/callbacks_controller.rb b/app/controllers/api/v1/accounts/callbacks_controller.rb
index 90cdf2418..08c0ffe43 100644
--- a/app/controllers/api/v1/accounts/callbacks_controller.rb
+++ b/app/controllers/api/v1/accounts/callbacks_controller.rb
@@ -6,6 +6,7 @@ class Api::V1::Accounts::CallbacksController < Api::V1::Accounts::BaseController
     page_access_token = params[:page_access_token]
     page_id = params[:page_id]
     inbox_name = params[:inbox_name]
+
     ActiveRecord::Base.transaction do
       facebook_channel = Current.account.facebook_pages.create!(
         page_id: page_id, user_access_token: user_access_token,
@@ -15,6 +16,8 @@ class Api::V1::Accounts::CallbacksController < Api::V1::Accounts::BaseController
       set_instagram_id(page_access_token, facebook_channel)
       set_avatar(@facebook_inbox, page_id)
     end
+  rescue CustomExceptions::Inbox::LimitExceeded => e
+    render_error_response(e)
   rescue StandardError => e
     ChatwootExceptionTracker.new(e).capture_exception
     Rails.logger.error "Error in register_facebook_page: #{e.message}"
diff --git a/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb b/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb
index f3b14d49f..1691b5489 100644
--- a/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb
+++ b/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb
@@ -6,6 +6,8 @@ class Api::V1::Accounts::Channels::TwilioChannelsController < Api::V1::Accounts:
 
   def create
     process_create
+  rescue CustomExceptions::Inbox::LimitExceeded => e
+    render_error_response(e)
   rescue StandardError => e
     render_could_not_create_error(e.message)
   end
diff --git a/app/controllers/api/v1/accounts/inboxes_controller.rb b/app/controllers/api/v1/accounts/inboxes_controller.rb
index 757af9b62..9f56c3817 100644
--- a/app/controllers/api/v1/accounts/inboxes_controller.rb
+++ b/app/controllers/api/v1/accounts/inboxes_controller.rb
@@ -2,7 +2,6 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
   include Api::V1::InboxesHelper
   before_action :fetch_inbox, except: [:index, :create]
   before_action :fetch_agent_bot, only: [:set_agent_bot]
-  before_action :validate_limit, only: [:create]
   # we are already handling the authorization in fetch inbox
   before_action :check_authorization, except: [:show]
 
diff --git a/app/controllers/api/v1/accounts/whatsapp/authorizations_controller.rb b/app/controllers/api/v1/accounts/whatsapp/authorizations_controller.rb
index d52f396fc..db94113d9 100644
--- a/app/controllers/api/v1/accounts/whatsapp/authorizations_controller.rb
+++ b/app/controllers/api/v1/accounts/whatsapp/authorizations_controller.rb
@@ -8,8 +8,10 @@ class Api::V1::Accounts::Whatsapp::AuthorizationsController < Api::V1::Accounts:
     validate_embedded_signup_params!
     channel = process_embedded_signup
     render_success_response(channel.inbox)
-  rescue StandardError => e
+  rescue CustomExceptions::Inbox::LimitExceeded => e
     render_error_response(e)
+  rescue StandardError => e
+    render_embedded_signup_error(e)
   end
 
   private
@@ -55,7 +57,7 @@ class Api::V1::Accounts::Whatsapp::AuthorizationsController < Api::V1::Accounts:
     render json: response
   end
 
-  def render_error_response(error)
+  def render_embedded_signup_error(error)
     Rails.logger.error "[WHATSAPP AUTHORIZATION] Embedded signup error: #{error.message}"
     Rails.logger.error error.backtrace.join("\n")
     render json: {
diff --git a/app/controllers/concerns/request_exception_handler.rb b/app/controllers/concerns/request_exception_handler.rb
index 7f4e313b1..43d6edf1f 100644
--- a/app/controllers/concerns/request_exception_handler.rb
+++ b/app/controllers/concerns/request_exception_handler.rb
@@ -9,6 +9,7 @@ module RequestExceptionHandler
 
   included do
     rescue_from ActiveRecord::RecordInvalid, with: :render_record_invalid
+    rescue_from CustomExceptions::Inbox::LimitExceeded, with: :render_error_response
   end
 
   private
@@ -40,8 +41,8 @@ module RequestExceptionHandler
     render json: { error: message }, status: :not_found
   end
 
-  def render_could_not_create_error(message)
-    render json: { error: sanitized_error_message(message) }, status: :unprocessable_entity
+  def render_could_not_create_error(error)
+    render json: { error: sanitized_error_message(error) }, status: :unprocessable_entity
   end
 
   def render_payment_required(message)
diff --git a/app/controllers/instagram/callbacks_controller.rb b/app/controllers/instagram/callbacks_controller.rb
index cd317363c..e9065119f 100644
--- a/app/controllers/instagram/callbacks_controller.rb
+++ b/app/controllers/instagram/callbacks_controller.rb
@@ -11,6 +11,8 @@ class Instagram::CallbacksController < ApplicationController
     end
 
     process_successful_authorization
+  rescue CustomExceptions::Inbox::LimitExceeded => e
+    handle_limit_error(e)
   rescue StandardError => e
     handle_error(e)
   end
@@ -47,6 +49,14 @@ class Instagram::CallbacksController < ApplicationController
     redirect_to_error_page(error_info)
   end
 
+  def handle_limit_error(error)
+    redirect_to_error_page(
+      'error_type' => error.class.name,
+      'code' => Rack::Utils.status_code(error.http_status),
+      'error_message' => error.message
+    )
+  end
+
   # Extract error details from the exception
   def extract_error_info(error)
     if error.is_a?(OAuth2::Error)
diff --git a/app/controllers/tiktok/callbacks_controller.rb b/app/controllers/tiktok/callbacks_controller.rb
index 20c0ee9c0..a39fec5ed 100644
--- a/app/controllers/tiktok/callbacks_controller.rb
+++ b/app/controllers/tiktok/callbacks_controller.rb
@@ -6,6 +6,8 @@ class Tiktok::CallbacksController < ApplicationController
     return handle_ungranted_scopes_error unless all_scopes_granted?
 
     process_successful_authorization
+  rescue CustomExceptions::Inbox::LimitExceeded => e
+    handle_limit_error(e)
   rescue StandardError => e
     handle_error(e)
   end
@@ -36,6 +38,14 @@ class Tiktok::CallbacksController < ApplicationController
     redirect_to_error_page(error_type: error.class.name, code: 500, error_message: error.message)
   end
 
+  def handle_limit_error(error)
+    redirect_to_error_page(
+      error_type: error.class.name,
+      code: Rack::Utils.status_code(error.http_status),
+      error_message: error.message
+    )
+  end
+
   # Handles the case when a user denies permissions or cancels the authorization flow
   def handle_authorization_error
     redirect_to_error_page(
diff --git a/app/helpers/api/v1/inboxes_helper.rb b/app/helpers/api/v1/inboxes_helper.rb
index 8a10fa99c..6c64dd009 100644
--- a/app/helpers/api/v1/inboxes_helper.rb
+++ b/app/helpers/api/v1/inboxes_helper.rb
@@ -114,10 +114,4 @@ module Api::V1::InboxesHelper
       'sms' => Current.account.sms_channels
     }[permitted_params[:channel][:type]]
   end
-
-  def validate_limit
-    return unless Current.account.inboxes.count >= Current.account.usage_limits[:inboxes]
-
-    render_payment_required('Account limit exceeded. Upgrade to a higher plan')
-  end
 end
diff --git a/enterprise/app/models/enterprise/concerns/inbox.rb b/enterprise/app/models/enterprise/concerns/inbox.rb
index bdcd0fd63..b327878b4 100644
--- a/enterprise/app/models/enterprise/concerns/inbox.rb
+++ b/enterprise/app/models/enterprise/concerns/inbox.rb
@@ -8,5 +8,11 @@ module Enterprise::Concerns::Inbox
             class_name: 'Captain::Assistant'
     has_many :inbox_capacity_limits, dependent: :destroy
     has_many :calls, dependent: :destroy_async
+
+    before_create :ensure_create_permitted
+  end
+
+  def ensure_create_permitted
+    raise CustomExceptions::Inbox::LimitExceeded.new({}) if account.inboxes.count >= account.usage_limits[:inboxes]
   end
 end
diff --git a/lib/custom_exceptions/inbox/limit_exceeded.rb b/lib/custom_exceptions/inbox/limit_exceeded.rb
new file mode 100644
index 000000000..9b5624929
--- /dev/null
+++ b/lib/custom_exceptions/inbox/limit_exceeded.rb
@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CustomExceptions::Inbox::LimitExceeded < CustomExceptions::Base
+  def message
+    'Account limit exceeded. Upgrade to a higher plan'
+  end
+
+  def to_hash
+    { error: message }
+  end
+
+  def http_status
+    :payment_required
+  end
+end
diff --git a/spec/enterprise/controllers/api/v1/accounts/callbacks_controller_spec.rb b/spec/enterprise/controllers/api/v1/accounts/callbacks_controller_spec.rb
new file mode 100644
index 000000000..33cc95fc1
--- /dev/null
+++ b/spec/enterprise/controllers/api/v1/accounts/callbacks_controller_spec.rb
@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe 'Enterprise Callbacks API', type: :request do
+  describe 'POST /api/v1/accounts/{account.id}/callbacks/register_facebook_page' do
+    let(:account) { create(:account, limits: { inboxes: 1 }) }
+    let(:admin) { create(:user, account: account, role: :administrator) }
+    let(:params) do
+      {
+        user_access_token: 'user-token',
+        page_access_token: 'page-token',
+        page_id: '12345',
+        inbox_name: 'Facebook Inbox'
+      }
+    end
+
+    before do
+      create(:inbox, account: account)
+    end
+
+    it 'returns payment required before creating a Facebook channel when account inbox limit is reached' do
+      expect do
+        post "/api/v1/accounts/#{account.id}/callbacks/register_facebook_page",
+             headers: admin.create_new_auth_token,
+             params: params,
+             as: :json
+      end.not_to change(Channel::FacebookPage, :count)
+
+      expect(response).to have_http_status(:payment_required)
+      expect(response.parsed_body['error']).to eq('Account limit exceeded. Upgrade to a higher plan')
+    end
+  end
+end
diff --git a/spec/enterprise/lib/captain/base_task_service_spec.rb b/spec/enterprise/lib/captain/base_task_service_spec.rb
index fb970f726..9186874b7 100644
--- a/spec/enterprise/lib/captain/base_task_service_spec.rb
+++ b/spec/enterprise/lib/captain/base_task_service_spec.rb
@@ -5,6 +5,13 @@ RSpec.describe Captain::BaseTaskService, type: :model do
   let(:inbox) { create(:inbox, account: account) }
   let(:conversation) { create(:conversation, account: account, inbox: inbox) }
   let(:perform_result) { { message: 'Test response' } }
+  let(:exhausted_usage_limits) do
+    {
+      agents: ChatwootApp.max_limit,
+      inboxes: ChatwootApp.max_limit,
+      captain: { responses: { current_available: 0 } }
+    }
+  end
 
   # Create a concrete test service class with enterprise module prepended
   let(:test_service_class) do
@@ -38,9 +45,7 @@ RSpec.describe Captain::BaseTaskService, type: :model do
     context 'when usage limit is exceeded' do
       before do
         allow(ChatwootApp).to receive(:chatwoot_cloud?).and_return(true)
-        allow(account).to receive(:usage_limits).and_return({
-                                                              captain: { responses: { current_available: 0 } }
-                                                            })
+        allow(account).to receive(:usage_limits).and_return(exhausted_usage_limits)
       end
 
       it 'returns usage limit exceeded error' do
@@ -125,9 +130,7 @@ RSpec.describe Captain::BaseTaskService, type: :model do
       context 'when the captain_responses quota is exhausted on Cloud' do
         before do
           allow(ChatwootApp).to receive(:chatwoot_cloud?).and_return(true)
-          allow(account).to receive(:usage_limits).and_return({
-                                                                captain: { responses: { current_available: 0 } }
-                                                              })
+          allow(account).to receive(:usage_limits).and_return(exhausted_usage_limits)
         end
 
         it 'returns usage limit exceeded error for services that do not opt into BYOK' do
@@ -162,9 +165,7 @@ RSpec.describe Captain::BaseTaskService, type: :model do
       context 'when the captain_responses quota is exhausted on Cloud' do
         before do
           allow(ChatwootApp).to receive(:chatwoot_cloud?).and_return(true)
-          allow(account).to receive(:usage_limits).and_return({
-                                                                captain: { responses: { current_available: 0 } }
-                                                              })
+          allow(account).to receive(:usage_limits).and_return(exhausted_usage_limits)
         end
 
         it 'bypasses the 429 gate and returns the underlying result' do
@@ -249,9 +250,7 @@ RSpec.describe Captain::BaseTaskService, type: :model do
       context 'when the captain_responses quota is exhausted on Cloud' do
         before do
           allow(ChatwootApp).to receive(:chatwoot_cloud?).and_return(true)
-          allow(account).to receive(:usage_limits).and_return({
-                                                                captain: { responses: { current_available: 0 } }
-                                                              })
+          allow(account).to receive(:usage_limits).and_return(exhausted_usage_limits)
         end
 
         it 'bypasses the 429 gate and returns the underlying result' do
diff --git a/spec/enterprise/lib/captain/conversation_completion_service_spec.rb b/spec/enterprise/lib/captain/conversation_completion_service_spec.rb
index 8b059acc3..80b9ab1d8 100644
--- a/spec/enterprise/lib/captain/conversation_completion_service_spec.rb
+++ b/spec/enterprise/lib/captain/conversation_completion_service_spec.rb
@@ -166,9 +166,13 @@ RSpec.describe Captain::ConversationCompletionService do
 
       before do
         allow(ChatwootApp).to receive(:chatwoot_cloud?).and_return(true)
-        allow(account).to receive(:usage_limits).and_return({
-                                                              captain: { responses: { current_available: 0 } }
-                                                            })
+        allow(account).to receive(:usage_limits).and_return(
+          {
+            agents: ChatwootApp.max_limit,
+            inboxes: ChatwootApp.max_limit,
+            captain: { responses: { current_available: 0 } }
+          }
+        )
         create(:message, conversation: conversation, message_type: :incoming, content: 'What are your hours?')
         create(:message, conversation: conversation, message_type: :outgoing, content: 'We are open 9-5 Monday to Friday.')
         allow(mock_chat).to receive(:ask).and_return(mock_response)
diff --git a/spec/enterprise/models/inbox_spec.rb b/spec/enterprise/models/inbox_spec.rb
index cfcbdd573..1dce2833b 100644
--- a/spec/enterprise/models/inbox_spec.rb
+++ b/spec/enterprise/models/inbox_spec.rb
@@ -134,6 +134,29 @@ RSpec.describe Inbox do
     end
   end
 
+  describe 'validations' do
+    describe 'account inbox limit' do
+      let(:account) { create(:account, limits: { inboxes: 1 }) }
+
+      before do
+        create(:inbox, account: account)
+      end
+
+      it 'prevents saving inboxes beyond the account limit' do
+        new_inbox = build(:inbox, account: account)
+
+        expect { new_inbox.save! }.to raise_error(CustomExceptions::Inbox::LimitExceeded, 'Account limit exceeded. Upgrade to a higher plan')
+      end
+
+      it 'does not block updates to existing inboxes when the account is at the limit' do
+        inbox = account.inboxes.first
+        inbox.name = 'Updated Inbox'
+
+        expect(inbox).to be_valid
+      end
+    end
+  end
+
   describe 'audit log' do
     context 'when inbox is created' do
       it 'has associated audit log created' do
diff --git a/spec/enterprise/services/messages/audio_transcription_service_spec.rb b/spec/enterprise/services/messages/audio_transcription_service_spec.rb
index 265ce6c33..4881e8cf1 100644
--- a/spec/enterprise/services/messages/audio_transcription_service_spec.rb
+++ b/spec/enterprise/services/messages/audio_transcription_service_spec.rb
@@ -12,7 +12,13 @@ RSpec.describe Messages::AudioTranscriptionService, type: :service do
     InstallationConfig.find_or_create_by!(name: 'CAPTAIN_OPEN_AI_MODEL') { |config| config.value = 'gpt-4o-mini' }
 
     # Mock usage limits for transcription to be available
-    allow(account).to receive(:usage_limits).and_return({ captain: { responses: { current_available: 100 } } })
+    allow(account).to receive(:usage_limits).and_return(
+      {
+        agents: ChatwootApp.max_limit,
+        inboxes: ChatwootApp.max_limit,
+        captain: { responses: { current_available: 100 } }
+      }
+    )
   end
 
   describe '#perform' do
diff --git a/spec/lib/captain/base_task_service_spec.rb b/spec/lib/captain/base_task_service_spec.rb
index b24a5c49c..2cb24ce04 100644
--- a/spec/lib/captain/base_task_service_spec.rb
+++ b/spec/lib/captain/base_task_service_spec.rb
@@ -385,7 +385,10 @@ RSpec.describe Captain::BaseTaskService do
 
   describe '#prompt_from_file' do
     it 'reads prompt from file' do
-      allow(Rails.root).to receive(:join).and_return(instance_double(Pathname, read: 'Test prompt content'))
+      service
+      prompt_path = instance_double(Pathname, read: 'Test prompt content')
+      allow(Rails.root).to receive(:join).with('lib/integrations/openai/openai_prompts', 'test.liquid').and_return(prompt_path)
+
       expect(service.send(:prompt_from_file, 'test')).to eq('Test prompt content')
     end
   end
diff --git a/spec/services/crm/leadsquared/mappers/conversation_mapper_spec.rb b/spec/services/crm/leadsquared/mappers/conversation_mapper_spec.rb
index 75abc8518..988fb0116 100644
--- a/spec/services/crm/leadsquared/mappers/conversation_mapper_spec.rb
+++ b/spec/services/crm/leadsquared/mappers/conversation_mapper_spec.rb
@@ -32,6 +32,7 @@ RSpec.describe Crm::Leadsquared::Mappers::ConversationMapper do
 
   before do
     account.enable_features('crm_integration')
+    allow(GlobalConfig).to receive(:get).and_return({})
     allow(GlobalConfig).to receive(:get).with('BRAND_NAME').and_return({ 'BRAND_NAME' => 'TestBrand' })
   end
 
diff --git a/spec/services/whatsapp/channel_creation_service_spec.rb b/spec/services/whatsapp/channel_creation_service_spec.rb
index 983af6c78..e7016f6a4 100644
--- a/spec/services/whatsapp/channel_creation_service_spec.rb
+++ b/spec/services/whatsapp/channel_creation_service_spec.rb
@@ -60,6 +60,17 @@ describe Whatsapp::ChannelCreationService do
         expect(inbox.name).to eq('Test Business WhatsApp')
         expect(inbox.account).to eq(account)
       end
+
+      it 'does not leave an orphan channel when inbox creation fails' do
+        allow(Inbox).to receive(:create!).and_wrap_original do |method, *args|
+          method.call(*args)
+          raise ActiveRecord::RecordInvalid, Inbox.new
+        end
+
+        expect do
+          expect { service.perform }.to raise_error(ActiveRecord::RecordInvalid)
+        end.not_to change(Channel::Whatsapp, :count)
+      end
     end
 
     context 'when channel already exists for the phone number' do

From f6c18f52258dfbcb41d7792914fbc77b92e90cb0 Mon Sep 17 00:00:00 2001
From: Tanmay Deep Sharma <32020192+tds-1@users.noreply.github.com>
Date: Wed, 8 Jul 2026 15:31:03 +0530
Subject: [PATCH 11/17] feat: account calls dashboard index endpoint (#14780)

## Description

Adds a backend endpoint that powers an account-wide calls dashboard,
letting users list and filter all calls in the account.

## Linear Ticket
- https://linear.app/chatwoot/issue/UPM-28/voice-call-dashboard-view

## Type of change

- [ ] New feature (non-breaking change which adds functionality)

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules
---
 config/routes.rb                              |   1 +
 ...0_add_account_created_at_index_to_calls.rb |   7 ++
 db/schema.rb                                  |   1 +
 .../api/v1/accounts/calls_controller.rb       |   7 ++
 enterprise/app/finders/call_finder.rb         |  70 ++++++++++++
 enterprise/app/models/call.rb                 |  11 ++
 .../api/v1/accounts/calls/index.json.jbuilder |  11 ++
 .../views/api/v1/models/_call.json.jbuilder   |  40 +++++++
 .../api/v1/accounts/calls_controller_spec.rb  |  46 ++++++++
 spec/enterprise/finders/call_finder_spec.rb   | 108 ++++++++++++++++++
 10 files changed, 302 insertions(+)
 create mode 100644 db/migrate/20260622000000_add_account_created_at_index_to_calls.rb
 create mode 100644 enterprise/app/controllers/api/v1/accounts/calls_controller.rb
 create mode 100644 enterprise/app/finders/call_finder.rb
 create mode 100644 enterprise/app/views/api/v1/accounts/calls/index.json.jbuilder
 create mode 100644 enterprise/app/views/api/v1/models/_call.json.jbuilder
 create mode 100644 spec/enterprise/controllers/api/v1/accounts/calls_controller_spec.rb
 create mode 100644 spec/enterprise/finders/call_finder_spec.rb

diff --git a/config/routes.rb b/config/routes.rb
index c5e7ded2f..c31400719 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -240,6 +240,7 @@ Rails.application.routes.draw do
           resources :reporting_events, only: [:index] if ChatwootApp.enterprise?
 
           if ChatwootApp.enterprise?
+            resources :calls, only: [:index]
             resources :whatsapp_calls, only: [:show] do
               member do
                 post :accept
diff --git a/db/migrate/20260622000000_add_account_created_at_index_to_calls.rb b/db/migrate/20260622000000_add_account_created_at_index_to_calls.rb
new file mode 100644
index 000000000..9c15dcda6
--- /dev/null
+++ b/db/migrate/20260622000000_add_account_created_at_index_to_calls.rb
@@ -0,0 +1,7 @@
+class AddAccountCreatedAtIndexToCalls < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  def change
+    add_index :calls, [:account_id, :created_at], algorithm: :concurrently
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index 1a676dd59..99d083d89 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -282,6 +282,7 @@ ActiveRecord::Schema[7.1].define(version: 2026_06_30_000000) do
     t.datetime "updated_at", null: false
     t.index ["account_id", "contact_id"], name: "index_calls_on_account_id_and_contact_id"
     t.index ["account_id", "conversation_id"], name: "index_calls_on_account_id_and_conversation_id"
+    t.index ["account_id", "created_at"], name: "index_calls_on_account_id_and_created_at"
     t.index ["message_id"], name: "index_calls_on_message_id"
     t.index ["provider", "provider_call_id"], name: "index_calls_on_provider_and_provider_call_id", unique: true
   end
diff --git a/enterprise/app/controllers/api/v1/accounts/calls_controller.rb b/enterprise/app/controllers/api/v1/accounts/calls_controller.rb
new file mode 100644
index 000000000..71772e4a0
--- /dev/null
+++ b/enterprise/app/controllers/api/v1/accounts/calls_controller.rb
@@ -0,0 +1,7 @@
+class Api::V1::Accounts::CallsController < Api::V1::Accounts::EnterpriseAccountsController
+  def index
+    result = CallFinder.new(Current.user, Current.account, params).perform
+    @calls = result[:calls]
+    @calls_count = result[:count]
+  end
+end
diff --git a/enterprise/app/finders/call_finder.rb b/enterprise/app/finders/call_finder.rb
new file mode 100644
index 000000000..31d6ae5f2
--- /dev/null
+++ b/enterprise/app/finders/call_finder.rb
@@ -0,0 +1,70 @@
+class CallFinder
+  RESULTS_PER_PAGE = 25
+
+  def initialize(current_user, current_account, params)
+    @current_user = current_user
+    @current_account = current_account
+    @params = params
+  end
+
+  def perform
+    @calls = @current_account.calls
+    filter_by_visibility
+    filter_by_status
+    filter_by_direction
+    filter_by_inbox
+    filter_by_agent
+    filter_by_date_range
+
+    { calls: paginated_calls, count: @calls.count }
+  end
+
+  private
+
+  # Admins and report managers see the whole account; everyone else only sees
+  # calls they handled within conversations they can still access.
+  def filter_by_visibility
+    return if account_wide_access?
+
+    @calls = @calls.where(accepted_by_agent_id: @current_user.id, conversation_id: accessible_conversations)
+  end
+
+  def accessible_conversations
+    Conversations::PermissionFilterService.new(@current_account.conversations, @current_user, @current_account).perform.select(:id)
+  end
+
+  def account_wide_access?
+    account_user = Current.account_user
+    account_user&.administrator? || account_user&.custom_role&.permissions&.include?('report_manage')
+  end
+
+  def filter_by_status
+    @calls = @calls.where(status: Call.status_from_display(@params[:status])) if @params[:status].present?
+  end
+
+  def filter_by_direction
+    @calls = @calls.where(direction: Call.direction_from_label(@params[:direction])) if @params[:direction].present?
+  end
+
+  def filter_by_inbox
+    @calls = @calls.where(inbox_id: @params[:inbox_id]) if @params[:inbox_id].present?
+  end
+
+  def filter_by_agent
+    @calls = @calls.where(accepted_by_agent_id: @params[:agent_id]) if @params[:agent_id].present?
+  end
+
+  # since/until are unix timestamps, matching DateRangeHelper conventions.
+  def filter_by_date_range
+    return if @params[:since].blank? || @params[:until].blank?
+
+    @calls = @calls.where(created_at: Time.zone.at(@params[:since].to_i)..Time.zone.at(@params[:until].to_i))
+  end
+
+  def paginated_calls
+    @calls.includes(:contact, :inbox, :conversation, :accepted_by_agent)
+          .order(created_at: :desc)
+          .page(@params[:page] || 1)
+          .per(RESULTS_PER_PAGE)
+  end
+end
diff --git a/enterprise/app/models/call.rb b/enterprise/app/models/call.rb
index 71dfac100..8c76103ea 100644
--- a/enterprise/app/models/call.rb
+++ b/enterprise/app/models/call.rb
@@ -78,6 +78,17 @@ class Call < ApplicationRecord
     DISPLAY_DIRECTION[direction]
   end
 
+  # Normalize filter values back to stored forms so API/dashboard clients can
+  # query using either the display value (inbound/outbound, in-progress) or the
+  # stored value (incoming/outgoing, in_progress).
+  def self.direction_from_label(value)
+    DISPLAY_DIRECTION.key(value) || value
+  end
+
+  def self.status_from_display(value)
+    value.to_s.tr('-', '_')
+  end
+
   def ringing?
     status == 'ringing'
   end
diff --git a/enterprise/app/views/api/v1/accounts/calls/index.json.jbuilder b/enterprise/app/views/api/v1/accounts/calls/index.json.jbuilder
new file mode 100644
index 000000000..15f66ddc1
--- /dev/null
+++ b/enterprise/app/views/api/v1/accounts/calls/index.json.jbuilder
@@ -0,0 +1,11 @@
+json.meta do
+  json.count @calls_count
+  json.current_page @calls.current_page
+  json.total_pages @calls.total_pages
+end
+
+json.payload do
+  json.array! @calls do |call|
+    json.partial! 'api/v1/models/call', formats: [:json], call: call
+  end
+end
diff --git a/enterprise/app/views/api/v1/models/_call.json.jbuilder b/enterprise/app/views/api/v1/models/_call.json.jbuilder
new file mode 100644
index 000000000..7a3531b39
--- /dev/null
+++ b/enterprise/app/views/api/v1/models/_call.json.jbuilder
@@ -0,0 +1,40 @@
+json.id call.id
+json.call_id call.provider_call_id
+json.provider call.provider
+json.status call.display_status
+json.direction call.direction_label
+json.duration_seconds call.duration_seconds
+json.end_reason call.end_reason
+json.started_at call.started_at&.to_i
+json.created_at call.created_at.to_i
+json.message_id call.message_id
+json.recording_url call.recording_url
+json.transcript call.transcript
+
+json.conversation do
+  json.id call.conversation_id
+  json.display_id call.conversation.display_id
+end
+
+json.inbox do
+  json.id call.inbox_id
+  json.name call.inbox.name
+end
+
+if call.accepted_by_agent
+  json.agent do
+    json.id call.accepted_by_agent.id
+    json.name call.accepted_by_agent.available_name
+    json.avatar call.accepted_by_agent.avatar_url
+  end
+else
+  json.agent nil
+end
+
+contact = call.contact
+json.contact do
+  json.id contact.id
+  json.name contact.name
+  json.phone_number contact.phone_number
+  json.avatar contact.avatar_url
+end
diff --git a/spec/enterprise/controllers/api/v1/accounts/calls_controller_spec.rb b/spec/enterprise/controllers/api/v1/accounts/calls_controller_spec.rb
new file mode 100644
index 000000000..86e4fb317
--- /dev/null
+++ b/spec/enterprise/controllers/api/v1/accounts/calls_controller_spec.rb
@@ -0,0 +1,46 @@
+require 'rails_helper'
+
+RSpec.describe 'Calls API', type: :request do
+  let(:account) { create(:account) }
+  let(:admin) { create(:user, account: account, role: :administrator) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:contact) { create(:contact, :with_phone_number, account: account) }
+  let(:conversation) { create(:conversation, account: account, inbox: inbox, contact: contact) }
+  let!(:agent_call) do
+    create(:call, account: account, inbox: inbox, conversation: conversation, contact: contact,
+                  accepted_by_agent: agent, status: 'completed', transcript: 'hello world')
+  end
+  let!(:other_call) do
+    create(:call, account: account, inbox: inbox, conversation: conversation, contact: contact, accepted_by_agent: admin)
+  end
+
+  before { create(:inbox_member, user: agent, inbox: inbox) }
+
+  describe 'GET /api/v1/accounts/:account_id/calls' do
+    it 'returns 401 when unauthenticated' do
+      get "/api/v1/accounts/#{account.id}/calls"
+      expect(response).to have_http_status(:unauthorized)
+    end
+
+    it 'returns the whole account with sensitive fields for an administrator' do
+      get "/api/v1/accounts/#{account.id}/calls", headers: admin.create_new_auth_token
+
+      expect(response).to have_http_status(:ok)
+      body = response.parsed_body
+      expect(body['payload'].map { |c| c['id'] }).to contain_exactly(agent_call.id, other_call.id)
+      item = body['payload'].find { |c| c['id'] == agent_call.id }
+      expect(item['transcript']).to eq('hello world')
+      expect(item['contact']['phone_number']).to eq(contact.phone_number)
+    end
+
+    it 'scopes the list to calls the agent accepted' do
+      get "/api/v1/accounts/#{account.id}/calls", headers: agent.create_new_auth_token
+
+      expect(response).to have_http_status(:ok)
+      body = response.parsed_body
+      expect(body['meta']['count']).to eq(1)
+      expect(body['payload'].map { |c| c['id'] }).to contain_exactly(agent_call.id)
+    end
+  end
+end
diff --git a/spec/enterprise/finders/call_finder_spec.rb b/spec/enterprise/finders/call_finder_spec.rb
new file mode 100644
index 000000000..4f4607370
--- /dev/null
+++ b/spec/enterprise/finders/call_finder_spec.rb
@@ -0,0 +1,108 @@
+require 'rails_helper'
+
+describe CallFinder do
+  let(:account) { create(:account) }
+  let(:admin) { create(:user, account: account, role: :administrator) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:conversation) { create(:conversation, account: account, inbox: inbox) }
+
+  before { create(:inbox_member, user: agent, inbox: inbox) }
+
+  def perform(user, params = {})
+    Current.account = account
+    Current.account_user = account.account_users.find_by(user_id: user.id)
+    described_class.new(user, account, params).perform
+  end
+
+  describe 'visibility' do
+    let!(:agent_call) do
+      create(:call, account: account, inbox: inbox, conversation: conversation, contact: conversation.contact, accepted_by_agent: agent)
+    end
+    let!(:other_call) do
+      create(:call, account: account, inbox: inbox, conversation: conversation, contact: conversation.contact, accepted_by_agent: admin)
+    end
+
+    it 'lets an administrator see every call in the account' do
+      result = perform(admin)
+      expect(result[:count]).to eq(2)
+      expect(result[:calls].map(&:id)).to contain_exactly(agent_call.id, other_call.id)
+    end
+
+    it 'lets an agent with report_manage see every call in the account' do
+      report_manager = create(:user, account: account, role: :agent)
+      custom_role = create(:custom_role, account: account, permissions: ['report_manage'])
+      account.account_users.find_by(user_id: report_manager.id).update!(custom_role: custom_role)
+
+      result = perform(report_manager)
+      expect(result[:calls].map(&:id)).to contain_exactly(agent_call.id, other_call.id)
+    end
+
+    it 'limits a regular agent to calls they accepted in accessible conversations' do
+      result = perform(agent)
+      expect(result[:calls].map(&:id)).to contain_exactly(agent_call.id)
+    end
+
+    it 'limits a custom-role agent without report_manage to their own accepted calls' do
+      scoped_agent = create(:user, account: account, role: :agent)
+      custom_role = create(:custom_role, account: account, permissions: ['conversation_manage'])
+      account.account_users.find_by(user_id: scoped_agent.id).update!(custom_role: custom_role)
+      create(:inbox_member, user: scoped_agent, inbox: inbox)
+      scoped_call = create(:call, account: account, inbox: inbox, conversation: conversation,
+                                  contact: conversation.contact, accepted_by_agent: scoped_agent)
+
+      result = perform(scoped_agent)
+      expect(result[:calls].map(&:id)).to contain_exactly(scoped_call.id)
+    end
+  end
+
+  describe 'filters' do
+    let(:inbox2) { create(:inbox, account: account) }
+    let(:conversation2) { create(:conversation, account: account, inbox: inbox2) }
+    let(:agent2) { create(:user, account: account, role: :agent) }
+    let!(:ringing) do
+      create(:call, account: account, inbox: inbox, conversation: conversation, contact: conversation.contact,
+                    status: 'ringing', direction: :incoming, accepted_by_agent: agent)
+    end
+    let!(:in_progress) do
+      create(:call, account: account, inbox: inbox, conversation: conversation, contact: conversation.contact,
+                    status: 'in_progress', direction: :incoming, accepted_by_agent: agent)
+    end
+    let!(:completed) do
+      create(:call, account: account, inbox: inbox2, conversation: conversation2, contact: conversation2.contact,
+                    status: 'completed', direction: :outgoing, accepted_by_agent: agent2, created_at: 10.days.ago)
+    end
+
+    it 'filters by status using the display value' do
+      expect(perform(admin, status: 'in-progress')[:calls].map(&:id)).to contain_exactly(in_progress.id)
+    end
+
+    it 'filters by direction using the display label' do
+      expect(perform(admin, direction: 'outbound')[:calls].map(&:id)).to contain_exactly(completed.id)
+    end
+
+    it 'filters by inbox' do
+      expect(perform(admin, inbox_id: inbox2.id)[:calls].map(&:id)).to contain_exactly(completed.id)
+    end
+
+    it 'filters by agent' do
+      expect(perform(admin, agent_id: agent2.id)[:calls].map(&:id)).to contain_exactly(completed.id)
+    end
+
+    it 'filters by created_at date range' do
+      params = { since: 2.days.ago.to_i.to_s, until: 1.hour.from_now.to_i.to_s }
+      expect(perform(admin, params)[:calls].map(&:id)).to contain_exactly(ringing.id, in_progress.id)
+    end
+  end
+
+  describe 'account scoping' do
+    it 'never returns calls from another account' do
+      other_account = create(:account)
+      other_conversation = create(:conversation, account: other_account)
+      create(:call, account: other_account, inbox: other_conversation.inbox, conversation: other_conversation,
+                    contact: other_conversation.contact)
+
+      expect(perform(admin)[:count]).to eq(0)
+    end
+  end
+end

From d3c588ff1050779c3fd32807f960fca59e617a2e Mon Sep 17 00:00:00 2001
From: Muhsin Keloth <muhsinkeramam@gmail.com>
Date: Wed, 8 Jul 2026 16:07:46 +0400
Subject: [PATCH 12/17] chore(inbox): re-enable Instagram inbox creation
 (#14955)

Brings the Instagram channel back in inbox creation and onboarding.
Instagram was temporarily disabled along with WhatsApp embedded signup
in #14943; this re-enables Instagram while keeping WhatsApp embedded
signup and WhatsApp Call inbox creation disabled.

Fixes https://linear.app/chatwoot/issue/CW-7549/enable-instagram

Co-authored-by: Muhsin <12408980+muhsin-k@users.noreply.github.com>
---
 .../dashboard/components/widgets/ChannelItem.vue         | 9 +++------
 app/javascript/dashboard/constants/globals.js            | 7 +++----
 .../dashboard/onboarding/inbox-setup/useChannelConfig.js | 8 +++-----
 .../specs/inbox-setup/useDetectedChannels.spec.js        | 6 +++---
 .../dashboard/settings/inbox/channels/Whatsapp.vue       | 4 ++--
 5 files changed, 14 insertions(+), 20 deletions(-)

diff --git a/app/javascript/dashboard/components/widgets/ChannelItem.vue b/app/javascript/dashboard/components/widgets/ChannelItem.vue
index 2652b582b..c084d6086 100644
--- a/app/javascript/dashboard/components/widgets/ChannelItem.vue
+++ b/app/javascript/dashboard/components/widgets/ChannelItem.vue
@@ -1,7 +1,7 @@
 <script setup>
 import { computed } from 'vue';
 import ChannelSelector from '../ChannelSelector.vue';
-import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
+import { IS_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 const props = defineProps({
   channel: {
@@ -21,10 +21,7 @@ const hasFbConfigured = computed(() => {
 });
 
 const hasInstagramConfigured = computed(() => {
-  return (
-    !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
-    window.chatwootConfig?.instagramAppId
-  );
+  return window.chatwootConfig?.instagramAppId;
 });
 
 const hasTiktokConfigured = computed(() => {
@@ -62,7 +59,7 @@ const isActive = computed(() => {
 
   if (key === 'whatsapp_call') {
     return (
-      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+      !IS_WHATSAPP_INBOX_CREATION_DISABLED &&
       props.enabledFeatures.channel_voice &&
       !!window.chatwootConfig?.whatsappAppId &&
       window.chatwootConfig.whatsappAppId !== 'none'
diff --git a/app/javascript/dashboard/constants/globals.js b/app/javascript/dashboard/constants/globals.js
index 717e5104f..bb602e751 100644
--- a/app/javascript/dashboard/constants/globals.js
+++ b/app/javascript/dashboard/constants/globals.js
@@ -79,7 +79,6 @@ export default {
 };
 export const DEFAULT_REDIRECT_URL = '/app/';
 
-// Temporarily disables Instagram and WhatsApp inbox creation
-// (WhatsApp embedded signup popup, Instagram OAuth, WhatsApp Call).
-// Flip to false when the channels are brought back.
-export const IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED = true;
+// Temporarily disables WhatsApp embedded signup and WhatsApp Call inbox
+// creation. Flip to false when the channel is brought back.
+export const IS_WHATSAPP_INBOX_CREATION_DISABLED = true;
diff --git a/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js b/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
index 9618c5e44..32b3904de 100644
--- a/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
+++ b/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
@@ -1,5 +1,5 @@
 import { useMapGetter } from 'dashboard/composables/store';
-import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
+import { IS_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 // OAuth/SDK channels need installation-level app credentials to be usable. When
 // the credential is missing the channel is "not configured" and is hidden from
@@ -14,14 +14,12 @@ export function useChannelConfig() {
     // WhatsApp is onboarded only via Meta embedded signup, which needs both the
     // app id (not the 'none' sentinel) and the signup configuration id.
     whatsapp: () =>
-      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+      !IS_WHATSAPP_INBOX_CREATION_DISABLED &&
       Boolean(installationConfig.whatsappAppId) &&
       installationConfig.whatsappAppId !== 'none' &&
       Boolean(installationConfig.whatsappConfigurationId),
     facebook: () => Boolean(installationConfig.fbAppId),
-    instagram: () =>
-      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
-      Boolean(installationConfig.instagramAppId),
+    instagram: () => Boolean(installationConfig.instagramAppId),
     tiktok: () => Boolean(installationConfig.tiktokAppId),
     gmail: () => Boolean(installationConfig.googleOAuthClientId),
     outlook: () => Boolean(globalConfig.value.azureAppId),
diff --git a/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js b/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
index 875bfaf0d..d130a3712 100644
--- a/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
+++ b/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
@@ -6,11 +6,11 @@ import { useDetectedChannels } from '../../inbox-setup/useDetectedChannels';
 
 vi.mock('vue-router');
 
-// Neutralize the temporary Instagram/WhatsApp kill switch so these specs keep
-// covering the credential-based gating it currently short-circuits.
+// Neutralize the temporary WhatsApp kill switch so these specs keep covering
+// the credential-based gating it short-circuits.
 vi.mock('dashboard/constants/globals', async importOriginal => ({
   ...(await importOriginal()),
-  IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED: false,
+  IS_WHATSAPP_INBOX_CREATION_DISABLED: false,
 }));
 
 // Mounts the composable against a real store and the real useAccount (only
diff --git a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
index 98cc90fee..9436ccc2a 100644
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
@@ -7,7 +7,7 @@ import ThreeSixtyDialogWhatsapp from './360DialogWhatsapp.vue';
 import CloudWhatsapp from './CloudWhatsapp.vue';
 import WhatsappEmbeddedSignup from './WhatsappEmbeddedSignup.vue';
 import ChannelSelector from 'dashboard/components/ChannelSelector.vue';
-import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
+import { IS_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 const route = useRoute();
 const router = useRouter();
@@ -24,7 +24,7 @@ const PROVIDER_TYPES = {
 
 const hasWhatsappAppId = computed(() => {
   return (
-    !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+    !IS_WHATSAPP_INBOX_CREATION_DISABLED &&
     window.chatwootConfig?.whatsappAppId &&
     window.chatwootConfig.whatsappAppId !== 'none'
   );

From 873d16f54c3f6c785c909673befddfb4bc199523 Mon Sep 17 00:00:00 2001
From: Sony Mathew <sony@chatwoot.com>
Date: Wed, 8 Jul 2026 17:38:26 +0530
Subject: [PATCH 13/17] feat: Extend account feature flag storage (#14947)

# Pull Request Template

## Description

Extends account-level feature flags by adding a second bigint bitset
column, `feature_flags_ext_2`, while preserving the existing
`flag_shih_tzu` feature check and enable/disable APIs. Existing flags
continue to live on `feature_flags`; future flags can opt into the
extension column through `config/features.yml` metadata.

Fixes
[CW-7238](https://linear.app/chatwoot/issue/CW-7238/feature-flag-extension)

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality not to work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

- `eval "$(rbenv init -)" && RAILS_ENV=test
POSTGRES_DATABASE=chatwoot_test_31a6 bundle exec rspec
spec/models/concerns/featurable_spec.rb spec/models/account_spec.rb
spec/lib/config_loader_spec.rb
spec/controllers/platform/api/v1/accounts_controller_spec.rb
spec/controllers/super_admin/accounts_controller_spec.rb
spec/enterprise/models/account_spec.rb` - 144 examples, 0 failures
- `eval "$(rbenv init -)" && bundle exec rubocop
app/models/concerns/featurable.rb app/models/account.rb
db/migrate/20260706215758_add_feature_flags_ext_2_to_accounts.rb
spec/models/concerns/featurable_spec.rb spec/models/account_spec.rb
spec/lib/config_loader_spec.rb spec/enterprise/models/account_spec.rb` -
7 files inspected, no offenses detected
- `ruby -ryaml -e "features =
YAML.safe_load(File.read('config/features.yml')); abort unless
features.size == 63; puts features.group_by { |f| f['column'] ||
'feature_flags' }.transform_values(&:size).inspect"` - `{"feature_flags"
=> 63}`
- `git diff --check`

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented on my code, particularly in hard-to-understand
areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream
modules
---
 app/models/account.rb                         |  3 +-
 app/models/concerns/featurable.rb             | 57 ++++++++++++++++++-
 config/features.yml                           | 20 +++++--
 ...758_add_feature_flags_ext_2_to_accounts.rb |  5 ++
 db/schema.rb                                  |  3 +-
 spec/enterprise/models/account_spec.rb        | 21 +++++++
 spec/lib/config_loader_spec.rb                | 22 +++++++
 spec/models/account_spec.rb                   | 27 +++++++++
 spec/models/concerns/featurable_spec.rb       | 50 ++++++++++++++++
 9 files changed, 197 insertions(+), 11 deletions(-)
 create mode 100644 db/migrate/20260706215758_add_feature_flags_ext_2_to_accounts.rb
 create mode 100644 spec/models/concerns/featurable_spec.rb

diff --git a/app/models/account.rb b/app/models/account.rb
index 0fa3e6659..4295b162e 100644
--- a/app/models/account.rb
+++ b/app/models/account.rb
@@ -7,6 +7,7 @@
 #  custom_attributes     :jsonb
 #  domain                :string(100)
 #  feature_flags         :bigint           default(0), not null
+#  feature_flags_ext_1   :bigint           default(0), not null
 #  internal_attributes   :jsonb            not null
 #  limits                :jsonb
 #  locale                :integer          default("en")
@@ -23,7 +24,7 @@
 #
 
 class Account < ApplicationRecord
-  # used for single column multi flags
+  # used for multi-flag bitset columns
   include FlagShihTzu
   include Reportable
   include Featurable
diff --git a/app/models/concerns/featurable.rb b/app/models/concerns/featurable.rb
index daa0b4bf6..914df8449 100644
--- a/app/models/concerns/featurable.rb
+++ b/app/models/concerns/featurable.rb
@@ -1,6 +1,10 @@
 module Featurable
   extend ActiveSupport::Concern
 
+  DEFAULT_FEATURE_FLAG_COLUMN = 'feature_flags'.freeze
+  FEATURE_FLAG_COLUMNS = [DEFAULT_FEATURE_FLAG_COLUMN, 'feature_flags_ext_1'].freeze
+  MAX_FEATURES_PER_COLUMN = 63
+
   QUERY_MODE = {
     flag_query_mode: :bit_operator,
     check_for_column: false
@@ -8,15 +12,62 @@ module Featurable
 
   FEATURE_LIST = YAML.safe_load(Rails.root.join('config/features.yml').read).freeze
 
-  FEATURES = FEATURE_LIST.each_with_object({}) do |feature, result|
-    result[result.keys.size + 1] = "feature_#{feature['name']}".to_sym
+  def self.feature_flag_mappings_for(feature_list)
+    features_by_column = feature_list.group_by { |feature| feature['column'].presence || DEFAULT_FEATURE_FLAG_COLUMN }
+
+    mappings = FEATURE_FLAG_COLUMNS.index_with do |column|
+      features = features_by_column.delete(column) || []
+      validate_feature_count!(column, features)
+
+      features.each_with_index.to_h do |feature, index|
+        [index + 1, "feature_#{feature['name']}".to_sym]
+      end
+    end
+
+    validate_feature_columns!(features_by_column)
+    mappings
   end
 
+  def self.validate_feature_count!(column, features)
+    return if features.size <= MAX_FEATURES_PER_COLUMN
+
+    raise ArgumentError, "Account feature flag column #{column} supports up to #{MAX_FEATURES_PER_COLUMN} features"
+  end
+
+  def self.validate_feature_columns!(features_by_column)
+    return if features_by_column.blank?
+
+    invalid_columns = features_by_column.keys.join(', ')
+    raise ArgumentError, "Unknown account feature flag column: #{invalid_columns}"
+  end
+
+  FEATURES_BY_COLUMN = feature_flag_mappings_for(FEATURE_LIST).freeze
+
   included do
     include FlagShihTzu
-    has_flags FEATURES.merge(column: 'feature_flags').merge(QUERY_MODE)
+
+    FEATURE_FLAG_COLUMNS.each do |column|
+      has_flags FEATURES_BY_COLUMN.fetch(column).merge(column: column).merge(QUERY_MODE)
+    end
 
     before_create :enable_default_features
+
+    define_method :all_feature_flags do
+      FEATURE_FLAG_COLUMNS.flat_map { |column| all_flags(column) }
+    end
+
+    define_method :selected_feature_flags do
+      FEATURE_FLAG_COLUMNS.flat_map { |column| selected_flags(column) }
+    end
+
+    define_method :selected_feature_flags= do |chosen_flags|
+      FEATURE_FLAG_COLUMNS.each { |column| unselect_all_flags(column) }
+      return if chosen_flags.nil?
+
+      chosen_flags.each do |selected_flag|
+        enable_flag(selected_flag.to_sym) if selected_flag.present?
+      end
+    end
   end
 
   def enable_features(*names)
diff --git a/config/features.yml b/config/features.yml
index c5bc8f608..55a1e815d 100644
--- a/config/features.yml
+++ b/config/features.yml
@@ -1,11 +1,19 @@
 # DO NOT change the order of features EVER
 ############################################
-# name: the name to be used internally in the code
-# display_name: the name to be used in the UI
-# enabled: whether the feature is enabled by default
-# help_url: the url to the help center article
-# chatwoot_internal: whether the feature is internal to Chatwoot and should not be shown in the UI for other self hosted installations
-# deprecated: purpose of feature flag is done, no need to show it in the UI anymore
+# name:               the name to be used internally in the code
+# display_name:       the name to be used in the UI
+# enabled:            whether the feature is enabled by default
+# column:             the account bitset column used to store the flag. Defaults to feature_flags. 
+#                     Use feature_flags_ext_1 for extension flags. Each bigint column supports 63 flags.
+# help_url:           the url to the help center article
+# chatwoot_internal:  whether the feature is internal to Chatwoot and should not be shown in the UI for other self hosted installations
+# deprecated:         purpose of feature flag is done, no need to show it in the UI anymore
+#
+# ADDING A NEW FEATURE FLAG:
+#   - The `feature_flags` column is FULL (63/63 slots used). Do NOT add to it.
+#   - New flags MUST set `column: feature_flags_ext_1` and be appended at the end.
+#   - Bit positions are persisted per column; never reorder or remove existing
+#     entries, and never change an existing feature's `column` after release.
 - name: inbound_emails
   display_name: Inbound Emails
   enabled: true
diff --git a/db/migrate/20260706215758_add_feature_flags_ext_2_to_accounts.rb b/db/migrate/20260706215758_add_feature_flags_ext_2_to_accounts.rb
new file mode 100644
index 000000000..ae7263aac
--- /dev/null
+++ b/db/migrate/20260706215758_add_feature_flags_ext_2_to_accounts.rb
@@ -0,0 +1,5 @@
+class AddFeatureFlagsExt2ToAccounts < ActiveRecord::Migration[7.0]
+  def change
+    add_column :accounts, :feature_flags_ext_1, :bigint, default: 0, null: false
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index 99d083d89..5e506a475 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.1].define(version: 2026_06_30_000000) do
+ActiveRecord::Schema[7.1].define(version: 2026_07_06_215758) do
   # These extensions should be enabled to support this database
   enable_extension "pg_stat_statements"
   enable_extension "pg_trgm"
@@ -73,6 +73,7 @@ ActiveRecord::Schema[7.1].define(version: 2026_06_30_000000) do
     t.integer "status", default: 0
     t.jsonb "internal_attributes", default: {}, null: false
     t.jsonb "settings", default: {}
+    t.bigint "feature_flags_ext_1", default: 0, null: false
     t.index ["status"], name: "index_accounts_on_status"
   end
 
diff --git a/spec/enterprise/models/account_spec.rb b/spec/enterprise/models/account_spec.rb
index 03f3b8d37..7c57e217f 100644
--- a/spec/enterprise/models/account_spec.rb
+++ b/spec/enterprise/models/account_spec.rb
@@ -11,6 +11,27 @@ RSpec.describe Account, type: :model do
     it { is_expected.to have_many(:custom_roles).dependent(:destroy_async) }
   end
 
+  describe '#selected_feature_flags=' do
+    it 'keeps advanced assignment enabled when assignment v2 is selected for a business account' do
+      account = build(:account, custom_attributes: { 'plan_name' => 'Business' })
+
+      account.selected_feature_flags = [:feature_assignment_v2]
+
+      expect(account).to be_feature_assignment_v2
+      expect(account).to be_feature_advanced_assignment
+    end
+
+    it 'disables advanced assignment when assignment v2 is not selected' do
+      account = build(:account, custom_attributes: { 'plan_name' => 'Business' })
+      account.enable_features(:assignment_v2, :advanced_assignment)
+
+      account.selected_feature_flags = []
+
+      expect(account).not_to be_feature_assignment_v2
+      expect(account).not_to be_feature_advanced_assignment
+    end
+  end
+
   describe 'sla_policies' do
     let!(:account) { create(:account) }
     let!(:sla_policy) { create(:sla_policy, account: account) }
diff --git a/spec/lib/config_loader_spec.rb b/spec/lib/config_loader_spec.rb
index 60b689872..4c5fd4fbd 100644
--- a/spec/lib/config_loader_spec.rb
+++ b/spec/lib/config_loader_spec.rb
@@ -42,5 +42,27 @@ describe ConfigLoader do
         expect(InstallationConfig.find_by(name: 'WHO').value).to eq('covid 19')
       end
     end
+
+    it 'preserves feature flag column metadata in account level defaults' do
+      Dir.mktmpdir do |config_path|
+        File.write("#{config_path}/installation_config.yml", <<~YAML)
+          - name: TEST_CONFIG
+            value: test
+            locked: true
+        YAML
+        File.write("#{config_path}/features.yml", <<~YAML)
+          - name: extension_feature
+            display_name: Extension Feature
+            enabled: false
+            column: feature_flags_ext_1
+        YAML
+
+        described_class.new.process(config_path: config_path)
+
+        expect(InstallationConfig.find_by(name: 'ACCOUNT_LEVEL_FEATURE_DEFAULTS').value).to include(
+          a_hash_including('name' => 'extension_feature', 'column' => 'feature_flags_ext_1')
+        )
+      end
+    end
   end
 end
diff --git a/spec/models/account_spec.rb b/spec/models/account_spec.rb
index e3bc636d1..9adc98cc0 100644
--- a/spec/models/account_spec.rb
+++ b/spec/models/account_spec.rb
@@ -103,6 +103,33 @@ RSpec.describe Account do
     end
   end
 
+  describe 'feature flag columns' do
+    let(:account) { described_class.new(name: 'Test Account') }
+
+    it 'configures the account feature flag extension column' do
+      expect(described_class.flag_columns).to include('feature_flags', 'feature_flags_ext_1')
+      expect(described_class.flag_mapping['feature_flags_ext_1']).to eq({})
+    end
+
+    it 'keeps existing feature flags on the original column' do
+      expect(described_class.flag_mapping['feature_flags'][:feature_inbound_emails]).to eq(1)
+      expect(described_class.flag_mapping['feature_flags'][:feature_advanced_assignment]).to eq(1 << 62)
+    end
+
+    it 'keeps bulk selected feature assignment compatible with existing feature names' do
+      account.selected_feature_flags = [:feature_ip_lookup, :feature_assignment_v2, :feature_advanced_assignment]
+
+      expect(account).to be_feature_ip_lookup
+      expect(account).to be_feature_assignment_v2
+      expect(account).to be_feature_advanced_assignment
+      expect(account.selected_feature_flags).to contain_exactly(
+        :feature_ip_lookup,
+        :feature_assignment_v2,
+        :feature_advanced_assignment
+      )
+    end
+  end
+
   describe 'inbound_email_domain' do
     let(:account) { create(:account) }
 
diff --git a/spec/models/concerns/featurable_spec.rb b/spec/models/concerns/featurable_spec.rb
new file mode 100644
index 000000000..8f0b64b05
--- /dev/null
+++ b/spec/models/concerns/featurable_spec.rb
@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe Featurable do
+  describe '.feature_flag_mappings_for' do
+    it 'maps features to the default feature_flags column when column is omitted' do
+      mappings = described_class.feature_flag_mappings_for([
+                                                             { 'name' => 'inbound_emails' },
+                                                             { 'name' => 'ip_lookup' }
+                                                           ])
+
+      expect(mappings['feature_flags']).to eq(
+        1 => :feature_inbound_emails,
+        2 => :feature_ip_lookup
+      )
+      expect(mappings['feature_flags_ext_1']).to eq({})
+    end
+
+    it 'maps extension flags to feature_flags_ext_1 with independent bit positions' do
+      mappings = described_class.feature_flag_mappings_for([
+                                                             { 'name' => 'inbound_emails' },
+                                                             { 'name' => 'ext_one', 'column' => 'feature_flags_ext_1' },
+                                                             { 'name' => 'ext_two', 'column' => 'feature_flags_ext_1' }
+                                                           ])
+
+      expect(mappings['feature_flags']).to eq(1 => :feature_inbound_emails)
+      expect(mappings['feature_flags_ext_1']).to eq(
+        1 => :feature_ext_one,
+        2 => :feature_ext_two
+      )
+    end
+
+    it 'raises when a feature references an unknown flag column' do
+      expect do
+        described_class.feature_flag_mappings_for([
+                                                    { 'name' => 'unknown_column_feature', 'column' => 'feature_flags_3' }
+                                                  ])
+      end.to raise_error(ArgumentError, /Unknown account feature flag column: feature_flags_3/)
+    end
+
+    it 'raises when a flag column has more than the supported number of features' do
+      features = Array.new(64) { |index| { 'name' => "feature_#{index}" } }
+
+      expect do
+        described_class.feature_flag_mappings_for(features)
+      end.to raise_error(ArgumentError, /feature_flags supports up to 63 features/)
+    end
+  end
+end

From b9536fb8ed4756e461ab87e12c0bce8fac22ae2a Mon Sep 17 00:00:00 2001
From: Shivam Mishra <scm.mymail@gmail.com>
Date: Wed, 8 Jul 2026 21:55:38 +0530
Subject: [PATCH 14/17] fix: use reserved example domain in SAML placeholders
 (#14958)

---
 app/javascript/dashboard/i18n/locale/en/settings.json    | 4 ++--
 app/javascript/dashboard/i18n/locale/pt_BR/settings.json | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/app/javascript/dashboard/i18n/locale/en/settings.json b/app/javascript/dashboard/i18n/locale/en/settings.json
index 23058d739..8d58b87aa 100644
--- a/app/javascript/dashboard/i18n/locale/en/settings.json
+++ b/app/javascript/dashboard/i18n/locale/en/settings.json
@@ -542,7 +542,7 @@
       "SSO_URL": {
         "LABEL": "SSO URL",
         "HELP": "The URL where SAML authentication requests will be sent",
-        "PLACEHOLDER": "https://your-idp.com/saml/sso"
+        "PLACEHOLDER": "https://sso.example.com/saml/sso"
       },
       "CERTIFICATE": {
         "LABEL": "Signing certificate in PEM format",
@@ -562,7 +562,7 @@
       "IDP_ENTITY_ID": {
         "LABEL": "Identity Provider Entity ID",
         "HELP": "Unique identifier for your identity provider (usually found in IdP configuration)",
-        "PLACEHOLDER": "https://your-idp.com/saml"
+        "PLACEHOLDER": "https://sso.example.com/saml"
       },
       "UPDATE_BUTTON": "Update SAML Settings",
       "API": {
diff --git a/app/javascript/dashboard/i18n/locale/pt_BR/settings.json b/app/javascript/dashboard/i18n/locale/pt_BR/settings.json
index 9d047dd92..69700c43b 100644
--- a/app/javascript/dashboard/i18n/locale/pt_BR/settings.json
+++ b/app/javascript/dashboard/i18n/locale/pt_BR/settings.json
@@ -501,7 +501,7 @@
       "SSO_URL": {
         "LABEL": "SSO URL",
         "HELP": "A URL para onde as solicitações de autenticação SAML serão enviadas",
-        "PLACEHOLDER": "https://your-idp.com/saml/sso"
+        "PLACEHOLDER": "https://sso.example.com/saml/sso"
       },
       "CERTIFICATE": {
         "LABEL": "Certificado de assinatura no formato PEM",
@@ -521,7 +521,7 @@
       "IDP_ENTITY_ID": {
         "LABEL": "ID da Entidade do Provedor de Identidade",
         "HELP": "Identificador exclusivo do seu provedor de identidade (geralmente encontrado na configuração do IdP)",
-        "PLACEHOLDER": "https://seu-idp.com/saml"
+        "PLACEHOLDER": "https://sso.example.com/saml"
       },
       "UPDATE_BUTTON": "Atualizar configurações de SAML",
       "API": {

From 66cfb26c77a902937713033edca5794e6f62cc7e Mon Sep 17 00:00:00 2001
From: Sony Mathew <sony@chatwoot.com>
Date: Wed, 8 Jul 2026 23:50:40 +0530
Subject: [PATCH 15/17] feat: Add unread count filters feature flag (1/6)
 (#14885)

## Description

Adds the account-level `unread_count_for_filters` feature flag as the
dark-launch gate for filtered sidebar unread counts. This reuses the
deprecated `quoted_email_reply` flag slot, resets the reused bit for
existing accounts, and removes stale defaults so new accounts do not
reference the old flag.

This also adds the feature where we are now calculating the unread counts for built in filters like mentions, participating and unattended along with unread count for saved filters/folders.

Closes
[CW-7262](https://linear.app/chatwoot/issue/CW-7262/unread-counts-for-filters-folders)

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality not to work as expected)
- [ ] This change requires a documentation update
---
 .../conversations/participants_controller.rb  |  26 +-
 .../conversations/unread_counts_controller.rb |  18 +-
 .../v1/accounts/conversations_controller.rb   |   1 +
 app/helpers/filters/filter_helper.rb          |  10 +
 .../components-next/sidebar/Sidebar.vue       |  47 +-
 app/javascript/dashboard/featureFlags.js      |   1 +
 .../dashboard/helper/actionCable.js           |  78 +++
 .../dashboard/helper/sidebarSort.js           |   2 +
 .../helper/specs/actionCable.spec.js          | 217 +++++++
 .../helper/specs/sidebarSort.spec.js          |  31 +-
 .../store/modules/conversationUnreadCounts.js |  23 +
 .../store/modules/conversationWatchers.js     |  57 +-
 .../dashboard/store/modules/customViews.js    |  59 +-
 .../conversationUnreadCounts/actions.spec.js  |   4 +
 .../conversationUnreadCounts/getters.spec.js  |  26 +
 .../mutations.spec.js                         |  47 +-
 .../conversationWatchers/actions.spec.js      |  71 +++
 .../modules/specs/customViews/actions.spec.js | 111 ++++
 .../sidebarSortPreferences/actions.spec.js    |   4 +-
 app/jobs/agents/destroy_job.rb                |   6 +-
 app/models/account_user.rb                    |  18 +
 app/models/campaign.rb                        |  10 +
 .../concerns/account_cache_revalidator.rb     |   2 +
 app/models/conversation.rb                    |  30 +-
 app/models/conversation_participant.rb        |   5 +
 app/models/custom_attribute_definition.rb     |  23 +
 app/models/custom_filter.rb                   |  21 +
 app/models/inbox.rb                           |  14 +
 app/models/inbox_member.rb                    |   5 +
 app/models/team.rb                            |  15 +
 app/models/team_member.rb                     |   8 +
 app/services/conversations/unread_counts.rb   |   6 +
 .../conversations/unread_counts/counter.rb    |  14 +-
 .../unread_counts/filter_query_counter.rb     | 151 +++++
 .../filtered_count_instrumentation.rb         | 188 ++++++
 .../filtered_count_invalidator.rb             | 184 ++++++
 .../filtered_count_snapshot_resolver.rb       |  67 +++
 .../unread_counts/filtered_count_store.rb     | 214 +++++++
 .../filtered_count_store_keys.rb              |  67 +++
 .../filtered_count_version_cache.rb           |  29 +
 .../unread_counts/filtered_counter.rb         | 216 +++++++
 .../conversations/unread_counts/listener.rb   |  87 ++-
 .../conversations/unread_counts/notifier.rb   |  12 +-
 app/services/labels/destroy_service.rb        |  12 +-
 config/features.yml                           |   6 +-
 ...reply_flag_for_unread_count_for_filters.rb |  22 +
 enterprise/app/models/custom_role.rb          |  33 ++
 .../permission_filter_service.rb              |  17 +-
 lib/redis/redis_keys.rb                       |  17 +
 .../participants_controller_spec.rb           |  54 ++
 .../accounts/conversations_controller_spec.rb | 125 ++++
 .../finders/conversation_finder_spec.rb       |  41 ++
 spec/enterprise/models/account_user_spec.rb   |  23 +
 spec/enterprise/models/custom_role_spec.rb    |  45 ++
 .../unread_counts/filtered_counter_spec.rb    |  58 ++
 .../permission_filter_service_spec.rb         |  10 +-
 spec/jobs/agents/destroy_job_spec.rb          |   9 +
 .../captain/reply_suggestion_service_spec.rb  |   1 +
 spec/listeners/action_cable_listener_spec.rb  |  24 +
 spec/models/account_user_spec.rb              |  39 ++
 spec/models/campaign_spec.rb                  |  37 ++
 spec/models/conversation_participants_spec.rb |  26 +
 spec/models/conversation_spec.rb              |  71 ++-
 .../custom_attribute_definition_spec.rb       |  46 ++
 spec/models/custom_filter_spec.rb             |  58 ++
 spec/models/inbox_member_spec.rb              |  42 ++
 spec/models/inbox_spec.rb                     |  28 +
 spec/models/team_member_spec.rb               |  43 ++
 .../conversations/filter_service_spec.rb      |  18 +
 .../unread_counts/counter_spec.rb             |  18 +
 .../filtered_count_instrumentation_spec.rb    | 137 +++++
 .../filtered_count_invalidator_spec.rb        | 244 ++++++++
 .../filtered_count_store_spec.rb              | 262 +++++++++
 .../unread_counts/filtered_counter_spec.rb    | 549 ++++++++++++++++++
 .../unread_counts/listener_spec.rb            | 231 +++++++-
 .../unread_counts/notifier_spec.rb            |  12 +
 spec/services/labels/destroy_service_spec.rb  |  13 +
 77 files changed, 4539 insertions(+), 57 deletions(-)
 create mode 100644 app/services/conversations/unread_counts/filter_query_counter.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_count_instrumentation.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_count_invalidator.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_count_snapshot_resolver.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_count_store.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_count_store_keys.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_count_version_cache.rb
 create mode 100644 app/services/conversations/unread_counts/filtered_counter.rb
 create mode 100644 db/migrate/20260629000000_repurpose_quoted_email_reply_flag_for_unread_count_for_filters.rb
 create mode 100644 spec/enterprise/finders/conversation_finder_spec.rb
 create mode 100644 spec/enterprise/services/conversations/unread_counts/filtered_counter_spec.rb
 create mode 100644 spec/models/custom_filter_spec.rb
 create mode 100644 spec/services/conversations/unread_counts/filtered_count_instrumentation_spec.rb
 create mode 100644 spec/services/conversations/unread_counts/filtered_count_invalidator_spec.rb
 create mode 100644 spec/services/conversations/unread_counts/filtered_count_store_spec.rb
 create mode 100644 spec/services/conversations/unread_counts/filtered_counter_spec.rb

diff --git a/app/controllers/api/v1/accounts/conversations/participants_controller.rb b/app/controllers/api/v1/accounts/conversations/participants_controller.rb
index ebd02380f..7569142b2 100644
--- a/app/controllers/api/v1/accounts/conversations/participants_controller.rb
+++ b/app/controllers/api/v1/accounts/conversations/participants_controller.rb
@@ -1,27 +1,40 @@
 class Api::V1::Accounts::Conversations::ParticipantsController < Api::V1::Accounts::Conversations::BaseController
+  include Events::Types
+
   def show
     @participants = @conversation.conversation_participants
   end
 
   def create
+    participant_ids_to_add = participants_to_be_added_ids
+
     ActiveRecord::Base.transaction do
-      @participants = participants_to_be_added_ids.map { |user_id| @conversation.conversation_participants.find_or_create_by(user_id: user_id) }
+      @participants = participant_ids_to_add.map { |user_id| @conversation.conversation_participants.find_or_create_by(user_id: user_id) }
     end
+    notify_unread_count_change if participant_ids_to_add.any?
   end
 
   def update
+    participant_ids_to_add = participants_to_be_added_ids
+    participant_ids_to_remove = participants_to_be_removed_ids
+    changed_participant_ids = participant_ids_to_add + participant_ids_to_remove
+
     ActiveRecord::Base.transaction do
-      participants_to_be_added_ids.each { |user_id| @conversation.conversation_participants.find_or_create_by(user_id: user_id) }
-      participants_to_be_removed_ids.each { |user_id| @conversation.conversation_participants.find_by(user_id: user_id)&.destroy }
+      participant_ids_to_add.each { |user_id| @conversation.conversation_participants.find_or_create_by(user_id: user_id) }
+      participant_ids_to_remove.each { |user_id| @conversation.conversation_participants.find_by(user_id: user_id)&.destroy }
     end
+    notify_unread_count_change if changed_participant_ids.any?
     @participants = @conversation.conversation_participants
     render action: 'show'
   end
 
   def destroy
+    participant_ids_to_remove = current_participant_ids & params[:user_ids]
+
     ActiveRecord::Base.transaction do
       params[:user_ids].map { |user_id| @conversation.conversation_participants.find_by(user_id: user_id)&.destroy }
     end
+    notify_unread_count_change if participant_ids_to_remove.any?
     head :ok
   end
 
@@ -38,4 +51,11 @@ class Api::V1::Accounts::Conversations::ParticipantsController < Api::V1::Accoun
   def current_participant_ids
     @current_participant_ids ||= @conversation.conversation_participants.pluck(:user_id)
   end
+
+  def notify_unread_count_change
+    return unless Current.account.feature_enabled?('conversation_unread_counts')
+    return unless Current.account.feature_enabled?('unread_count_for_filters')
+
+    Rails.configuration.dispatcher.dispatch(CONVERSATION_UNREAD_COUNT_CHANGED, Time.zone.now, conversation: @conversation)
+  end
 end
diff --git a/app/controllers/api/v1/accounts/conversations/unread_counts_controller.rb b/app/controllers/api/v1/accounts/conversations/unread_counts_controller.rb
index d9f15613b..0b2335475 100644
--- a/app/controllers/api/v1/accounts/conversations/unread_counts_controller.rb
+++ b/app/controllers/api/v1/accounts/conversations/unread_counts_controller.rb
@@ -2,12 +2,28 @@ class Api::V1::Accounts::Conversations::UnreadCountsController < Api::V1::Accoun
   before_action :ensure_unread_counts_enabled
 
   def index
-    counts = ::Conversations::UnreadCounts::Counter.new(account: Current.account, user: Current.user).perform
+    counts = if filtered_unread_counts_enabled?
+               instrumentation.summarize_request(account_id: Current.account.id) { unread_counts }
+             else
+               unread_counts
+             end
     render json: { payload: counts }
   end
 
   private
 
+  def unread_counts
+    ::Conversations::UnreadCounts::Counter.new(account: Current.account, user: Current.user).perform
+  end
+
+  def filtered_unread_counts_enabled?
+    Current.account.feature_enabled?(::Conversations::UnreadCounts::FilteredCounter::FEATURE_FLAG)
+  end
+
+  def instrumentation
+    ::Conversations::UnreadCounts::FilteredCountInstrumentation
+  end
+
   def ensure_unread_counts_enabled
     return if Current.account.feature_enabled?('conversation_unread_counts')
 
diff --git a/app/controllers/api/v1/accounts/conversations_controller.rb b/app/controllers/api/v1/accounts/conversations_controller.rb
index 2e53fa7c9..38e8d94aa 100644
--- a/app/controllers/api/v1/accounts/conversations_controller.rb
+++ b/app/controllers/api/v1/accounts/conversations_controller.rb
@@ -164,6 +164,7 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro
     # rubocop:enable Rails/SkipsModelValidations
 
     ::Conversations::UnreadCounts::Notifier.new(@conversation).perform
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(Current.account).conversation_changed!
   end
 
   def should_update_last_seen?
diff --git a/app/helpers/filters/filter_helper.rb b/app/helpers/filters/filter_helper.rb
index 4f345676e..d32c9468a 100644
--- a/app/helpers/filters/filter_helper.rb
+++ b/app/helpers/filters/filter_helper.rb
@@ -68,6 +68,8 @@ module Filters::FilterHelper
     when 'text_case_insensitive'
       text_case_insensitive_filter(query_hash, filter_operator_value)
     else
+      return text_cast_filter(query_hash, filter_operator_value) if text_search_on_display_id?(query_hash)
+
       default_filter(query_hash, filter_operator_value)
     end
   end
@@ -82,10 +84,18 @@ module Filters::FilterHelper
       "#{filter_operator_value} #{query_hash[:query_operator]}"
   end
 
+  def text_cast_filter(query_hash, filter_operator_value)
+    "(#{filter_config[:table_name]}.#{query_hash[:attribute_key]})::text #{filter_operator_value} #{query_hash[:query_operator]}"
+  end
+
   def default_filter(query_hash, filter_operator_value)
     "#{filter_config[:table_name]}.#{query_hash[:attribute_key]} #{filter_operator_value} #{query_hash[:query_operator]}"
   end
 
+  def text_search_on_display_id?(query_hash)
+    query_hash[:attribute_key] == 'display_id' && %w[contains does_not_contain].include?(query_hash[:filter_operator])
+  end
+
   def validate_single_condition(condition)
     return if condition['query_operator'].nil?
     return if condition['query_operator'].empty?
diff --git a/app/javascript/dashboard/components-next/sidebar/Sidebar.vue b/app/javascript/dashboard/components-next/sidebar/Sidebar.vue
index 0e6b3468b..a78460ca2 100644
--- a/app/javascript/dashboard/components-next/sidebar/Sidebar.vue
+++ b/app/javascript/dashboard/components-next/sidebar/Sidebar.vue
@@ -75,6 +75,16 @@ const hasConversationUnreadCounts = computed(() => {
   );
 });
 
+const hasFilteredUnreadCounts = computed(() => {
+  return (
+    hasConversationUnreadCounts.value &&
+    isFeatureEnabledonAccount.value(
+      accountId.value,
+      FEATURE_FLAGS.UNREAD_COUNT_FOR_FILTERS
+    )
+  );
+});
+
 const fetchConversationUnreadCounts = ([currentAccountId, isEnabled]) => {
   if (!currentAccountId) return;
 
@@ -199,6 +209,18 @@ const getLabelUnreadCount = useMapGetter(
 const getTeamUnreadCount = useMapGetter(
   'conversationUnreadCounts/getTeamUnreadCount'
 );
+const mentionsUnreadCount = useMapGetter(
+  'conversationUnreadCounts/getMentionsUnreadCount'
+);
+const participatingUnreadCount = useMapGetter(
+  'conversationUnreadCounts/getParticipatingUnreadCount'
+);
+const unattendedUnreadCount = useMapGetter(
+  'conversationUnreadCounts/getUnattendedUnreadCount'
+);
+const getFolderUnreadCount = useMapGetter(
+  'conversationUnreadCounts/getFolderUnreadCount'
+);
 const teams = useMapGetter('teams/getMyTeams');
 const contactCustomViews = useMapGetter('customViews/getContactCustomViews');
 const conversationCustomViews = useMapGetter(
@@ -226,14 +248,22 @@ watch([accountId, currentUserId], fetchSidebarSortPreferences, {
   immediate: true,
 });
 
+const hasUnreadCountsForSection = section => {
+  if (section === SIDEBAR_SORT_SECTIONS.FOLDERS) {
+    return hasFilteredUnreadCounts.value;
+  }
+
+  return hasConversationUnreadCounts.value;
+};
+
 const getSortOptionsForSection = section =>
   getSidebarSortOptions(section, {
-    hasUnreadCounts: hasConversationUnreadCounts.value,
+    hasUnreadCounts: hasUnreadCountsForSection(section),
   });
 
 const getSortForSection = section =>
   resolveSidebarSort(section, getSidebarSectionSort.value(section), {
-    hasUnreadCounts: hasConversationUnreadCounts.value,
+    hasUnreadCounts: hasUnreadCountsForSection(section),
   });
 
 const updateSortPreference = (section, sortBy) => {
@@ -253,6 +283,7 @@ const sortedFolders = computed(() =>
   sortSidebarItems(conversationCustomViews.value, {
     sortBy: getSortForSection(SIDEBAR_SORT_SECTIONS.FOLDERS),
     labelKey: view => view.name,
+    unreadCountKey: view => getFolderUnreadCount.value(view.id),
   })
 );
 
@@ -342,6 +373,9 @@ const menuItems = computed(() => {
           name: 'Mentions',
           label: t('SIDEBAR.MENTIONED_CONVERSATIONS'),
           icon: 'i-lucide-at-sign',
+          badgeCount: hasFilteredUnreadCounts.value
+            ? mentionsUnreadCount.value
+            : 0,
           activeOn: ['conversation_through_mentions'],
           to: accountScopedRoute('conversation_mentions'),
         },
@@ -349,6 +383,9 @@ const menuItems = computed(() => {
           name: 'Participating',
           label: t('SIDEBAR.PARTICIPATING_CONVERSATIONS'),
           icon: 'i-lucide-user-round-check',
+          badgeCount: hasFilteredUnreadCounts.value
+            ? participatingUnreadCount.value
+            : 0,
           activeOn: ['conversation_through_participating'],
           to: accountScopedRoute('conversation_participating'),
         },
@@ -357,6 +394,9 @@ const menuItems = computed(() => {
           activeOn: ['conversation_through_unattended'],
           label: t('SIDEBAR.UNATTENDED_CONVERSATIONS'),
           icon: 'i-lucide-clock-alert',
+          badgeCount: hasFilteredUnreadCounts.value
+            ? unattendedUnreadCount.value
+            : 0,
           to: accountScopedRoute('conversation_unattended'),
         },
         {
@@ -370,6 +410,9 @@ const menuItems = computed(() => {
           children: sortedFolders.value.map(view => ({
             name: `${view.name}-${view.id}`,
             label: view.name,
+            badgeCount: hasFilteredUnreadCounts.value
+              ? getFolderUnreadCount.value(view.id)
+              : 0,
             to: accountScopedRoute('folder_conversations', { id: view.id }),
           })),
         },
diff --git a/app/javascript/dashboard/featureFlags.js b/app/javascript/dashboard/featureFlags.js
index 00a79763b..b9f59eba0 100644
--- a/app/javascript/dashboard/featureFlags.js
+++ b/app/javascript/dashboard/featureFlags.js
@@ -47,6 +47,7 @@ export const FEATURE_FLAGS = {
   ADVANCED_SEARCH: 'advanced_search',
   CONVERSATION_REQUIRED_ATTRIBUTES: 'conversation_required_attributes',
   CONVERSATION_UNREAD_COUNTS: 'conversation_unread_counts',
+  UNREAD_COUNT_FOR_FILTERS: 'unread_count_for_filters',
 };
 
 export const PREMIUM_FEATURES = [
diff --git a/app/javascript/dashboard/helper/actionCable.js b/app/javascript/dashboard/helper/actionCable.js
index e6f2993e4..ef03b1c01 100644
--- a/app/javascript/dashboard/helper/actionCable.js
+++ b/app/javascript/dashboard/helper/actionCable.js
@@ -17,6 +17,13 @@ import { FEATURE_FLAGS } from 'dashboard/featureFlags';
 
 const { isImpersonating } = useImpersonation();
 const UNREAD_COUNTS_REFETCH_THROTTLE_MS = 5000;
+const FILTERED_UNREAD_COUNTS_REFRESH_RETRY_MS = 30000;
+const FILTERED_UNREAD_COUNTS_REFRESH_RETRY_JITTER_MS = 15000;
+const MENTION_UNREAD_COUNTS_REFETCH_DELAY_MS =
+  UNREAD_COUNTS_REFETCH_THROTTLE_MS;
+const getFilteredUnreadCountsRefreshRetryDelay = () =>
+  FILTERED_UNREAD_COUNTS_REFRESH_RETRY_MS +
+  Math.random() * FILTERED_UNREAD_COUNTS_REFRESH_RETRY_JITTER_MS;
 
 class ActionCableConnector extends BaseActionCableConnector {
   constructor(app, pubsubToken) {
@@ -25,6 +32,9 @@ class ActionCableConnector extends BaseActionCableConnector {
     this.CancelTyping = [];
     this.lastUnreadCountsFetchAt = null;
     this.unreadCountsFetchTimer = null;
+    this.mentionUnreadCountsFetchTimer = null;
+    this.mentionUnreadCountsRetryTimer = null;
+    this.filteredUnreadCountsRetryTimer = null;
     this.events = {
       'message.created': this.onMessageCreated,
       'message.updated': this.onMessageUpdated,
@@ -140,7 +150,12 @@ class ActionCableConnector extends BaseActionCableConnector {
   };
 
   onConversationUnreadCountChanged = () => {
+    this.refreshConversationUnreadCountsWithFilteredRetry();
+  };
+
+  refreshConversationUnreadCountsWithFilteredRetry = () => {
     this.throttledFetchConversationUnreadCounts();
+    this.scheduleFilteredUnreadCountsRetry();
   };
 
   throttledFetchConversationUnreadCounts = () => {
@@ -171,6 +186,51 @@ class ActionCableConnector extends BaseActionCableConnector {
     this.unreadCountsFetchTimer = null;
   };
 
+  scheduleMentionUnreadCountsFetch = () => {
+    if (!this.isFilteredUnreadCountsEnabled()) return;
+
+    // Mention invalidation runs through the async dispatcher, and stale snapshots
+    // can be served until the filtered-count backend refresh window opens.
+    this.scheduleUnreadCountsFetchAfter(
+      'mentionUnreadCountsFetchTimer',
+      MENTION_UNREAD_COUNTS_REFETCH_DELAY_MS
+    );
+    this.scheduleUnreadCountsFetchAfter(
+      'mentionUnreadCountsRetryTimer',
+      getFilteredUnreadCountsRefreshRetryDelay(),
+      { reset: true }
+    );
+  };
+
+  scheduleFilteredUnreadCountsRetry = () => {
+    if (!this.isFilteredUnreadCountsEnabled()) return;
+
+    // Filtered snapshots can intentionally stay stale until the backend
+    // refresh window opens.
+    this.scheduleUnreadCountsFetchAfter(
+      'filteredUnreadCountsRetryTimer',
+      getFilteredUnreadCountsRefreshRetryDelay(),
+      { reset: true }
+    );
+  };
+
+  scheduleUnreadCountsFetchAfter = (
+    timerName,
+    delay,
+    { reset = false } = {}
+  ) => {
+    if (this[timerName]) {
+      if (!reset) return;
+
+      clearTimeout(this[timerName]);
+    }
+
+    this[timerName] = setTimeout(() => {
+      this[timerName] = null;
+      this.throttledFetchConversationUnreadCounts();
+    }, delay);
+  };
+
   fetchConversationUnreadCounts = () => {
     if (!this.isConversationUnreadCountsEnabled()) return;
 
@@ -189,6 +249,17 @@ class ActionCableConnector extends BaseActionCableConnector {
     );
   };
 
+  isFilteredUnreadCountsEnabled = () => {
+    const accountId = this.app.$store.getters.getCurrentAccountId;
+    const isFeatureEnabled =
+      this.app.$store.getters['accounts/isFeatureEnabledonAccount'];
+
+    return (
+      isFeatureEnabled?.(accountId, FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS) &&
+      isFeatureEnabled?.(accountId, FEATURE_FLAGS.UNREAD_COUNT_FOR_FILTERS)
+    );
+  };
+
   onTypingOn = ({ conversation, user }) => {
     const conversationId = conversation.id;
 
@@ -212,6 +283,7 @@ class ActionCableConnector extends BaseActionCableConnector {
 
   onConversationMentioned = data => {
     this.app.$store.dispatch('addMentions', data);
+    this.scheduleMentionUnreadCountsFetch();
   };
 
   clearTimer = conversationId => {
@@ -273,6 +345,12 @@ class ActionCableConnector extends BaseActionCableConnector {
     this.app.$store.dispatch('labels/revalidate', { newKey: keys.label });
     this.app.$store.dispatch('inboxes/revalidate', { newKey: keys.inbox });
     this.app.$store.dispatch('teams/revalidate', { newKey: keys.team });
+
+    if (this.isFilteredUnreadCountsEnabled()) {
+      // Inbox/team/label visibility changes can change the accessible set used
+      // by filtered unread counts even when no conversation row changes.
+      this.refreshConversationUnreadCountsWithFilteredRetry();
+    }
   };
 
   onVoiceCallIncoming = data => {
diff --git a/app/javascript/dashboard/helper/sidebarSort.js b/app/javascript/dashboard/helper/sidebarSort.js
index 801dd94e2..f1167f70c 100644
--- a/app/javascript/dashboard/helper/sidebarSort.js
+++ b/app/javascript/dashboard/helper/sidebarSort.js
@@ -20,6 +20,8 @@ export const SIDEBAR_SORT_OPTIONS_BY_SECTION = Object.freeze({
     SIDEBAR_SORT_KEYS.CREATED_ASC,
     SIDEBAR_SORT_KEYS.ALPHABETICAL_ASC,
     SIDEBAR_SORT_KEYS.ALPHABETICAL_DESC,
+    SIDEBAR_SORT_KEYS.UNREAD_COUNT_DESC,
+    SIDEBAR_SORT_KEYS.UNREAD_COUNT_ASC,
   ],
   [SIDEBAR_SORT_SECTIONS.TEAMS]: [
     SIDEBAR_SORT_KEYS.CREATED_DESC,
diff --git a/app/javascript/dashboard/helper/specs/actionCable.spec.js b/app/javascript/dashboard/helper/specs/actionCable.spec.js
index 8ba411a5f..b288aee83 100644
--- a/app/javascript/dashboard/helper/specs/actionCable.spec.js
+++ b/app/javascript/dashboard/helper/specs/actionCable.spec.js
@@ -1,5 +1,6 @@
 import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
 import ActionCableConnector from '../actionCable';
+import { FEATURE_FLAGS } from 'dashboard/featureFlags';
 
 vi.mock('shared/helpers/mitt', () => ({
   emitter: {
@@ -17,6 +18,9 @@ global.chatwootConfig = {
   websocketURL: 'wss://test.chatwoot.com',
 };
 
+const mockRetryJitter = value =>
+  vi.spyOn(Math, 'random').mockReturnValue(value);
+
 describe('ActionCableConnector - Copilot Tests', () => {
   let store;
   let actionCable;
@@ -39,6 +43,8 @@ describe('ActionCableConnector - Copilot Tests', () => {
   });
 
   afterEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllTimers();
     vi.useRealTimers();
   });
   describe('copilot event handlers', () => {
@@ -81,12 +87,223 @@ describe('ActionCableConnector - Copilot Tests', () => {
     });
 
     it('should refetch unread counts when unread count changes', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+      mockRetryJitter(0.5);
+
       actionCable.onReceived({
         event: 'conversation.unread_count_changed',
         data: { account_id: 1 },
       });
 
       expect(mockDispatch).toHaveBeenCalledWith('conversationUnreadCounts/get');
+
+      vi.advanceTimersByTime(37499);
+      expect(mockDispatch).toHaveBeenCalledTimes(1);
+
+      vi.advanceTimersByTime(1);
+      expect(mockDispatch).toHaveBeenCalledTimes(2);
+      expect(mockDispatch).toHaveBeenLastCalledWith(
+        'conversationUnreadCounts/get'
+      );
+    });
+
+    it('does not retry unread count changes when filtered counts are disabled', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+      store.$store.getters[
+        'accounts/isFeatureEnabledonAccount'
+      ].mockImplementation(
+        (_, featureFlag) =>
+          featureFlag === FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS
+      );
+
+      actionCable.onReceived({
+        event: 'conversation.unread_count_changed',
+        data: { account_id: 1 },
+      });
+
+      expect(mockDispatch).toHaveBeenCalledTimes(1);
+
+      vi.advanceTimersByTime(45000);
+      expect(mockDispatch).toHaveBeenCalledTimes(1);
+    });
+
+    it('delays unread count refetch when a conversation is mentioned', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+
+      const conversation = { id: 1, account_id: 1 };
+
+      actionCable.onReceived({
+        event: 'conversation.mentioned',
+        data: conversation,
+      });
+
+      expect(mockDispatch).toHaveBeenCalledWith('addMentions', conversation);
+      expect(mockDispatch).not.toHaveBeenCalledWith(
+        'conversationUnreadCounts/get'
+      );
+
+      vi.advanceTimersByTime(4999);
+      expect(mockDispatch).not.toHaveBeenCalledWith(
+        'conversationUnreadCounts/get'
+      );
+
+      vi.advanceTimersByTime(1);
+      expect(mockDispatch).toHaveBeenCalledWith('conversationUnreadCounts/get');
+    });
+
+    it('does not schedule mention unread count fetches when filtered counts are disabled', () => {
+      vi.useFakeTimers();
+      store.$store.getters[
+        'accounts/isFeatureEnabledonAccount'
+      ].mockImplementation(
+        (_, featureFlag) =>
+          featureFlag === FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS
+      );
+
+      const conversation = { id: 1, account_id: 1 };
+
+      actionCable.onReceived({
+        event: 'conversation.mentioned',
+        data: conversation,
+      });
+
+      expect(mockDispatch).toHaveBeenCalledWith('addMentions', conversation);
+
+      vi.advanceTimersByTime(45000);
+      expect(mockDispatch).not.toHaveBeenCalledWith(
+        'conversationUnreadCounts/get'
+      );
+    });
+
+    it('retries mentioned unread counts after the backend refresh window', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+      mockRetryJitter(0.5);
+
+      actionCable.onReceived({
+        event: 'conversation.mentioned',
+        data: { id: 1, account_id: 1 },
+      });
+
+      const unreadCountFetches = () =>
+        mockDispatch.mock.calls.filter(
+          ([action]) => action === 'conversationUnreadCounts/get'
+        );
+
+      vi.advanceTimersByTime(5000);
+      expect(unreadCountFetches()).toHaveLength(1);
+
+      vi.advanceTimersByTime(32499);
+      expect(unreadCountFetches()).toHaveLength(1);
+
+      vi.advanceTimersByTime(1);
+      expect(unreadCountFetches()).toHaveLength(2);
+    });
+
+    it('reschedules mentioned unread count retries for later invalidations', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+      mockRetryJitter(0);
+
+      const unreadCountFetches = () =>
+        mockDispatch.mock.calls.filter(
+          ([action]) => action === 'conversationUnreadCounts/get'
+        );
+
+      actionCable.onReceived({
+        event: 'conversation.mentioned',
+        data: { id: 1, account_id: 1 },
+      });
+
+      vi.advanceTimersByTime(5000);
+      expect(unreadCountFetches()).toHaveLength(1);
+
+      vi.advanceTimersByTime(10000);
+      actionCable.onReceived({
+        event: 'conversation.mentioned',
+        data: { id: 1, account_id: 1 },
+      });
+
+      vi.advanceTimersByTime(5000);
+      expect(unreadCountFetches()).toHaveLength(2);
+
+      vi.advanceTimersByTime(10000);
+      expect(unreadCountFetches()).toHaveLength(2);
+
+      vi.advanceTimersByTime(15000);
+      expect(unreadCountFetches()).toHaveLength(3);
+    });
+
+    it('refetches filtered unread counts after account cache invalidation', () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+      mockRetryJitter(0.5);
+
+      const cacheKeys = {
+        label: 'label-key',
+        inbox: 'inbox-key',
+        team: 'team-key',
+      };
+      const unreadCountFetches = () =>
+        mockDispatch.mock.calls.filter(
+          ([action]) => action === 'conversationUnreadCounts/get'
+        );
+
+      actionCable.onReceived({
+        event: 'account.cache_invalidated',
+        data: { account_id: 1, cache_keys: cacheKeys },
+      });
+
+      expect(mockDispatch).toHaveBeenCalledWith('labels/revalidate', {
+        newKey: cacheKeys.label,
+      });
+      expect(mockDispatch).toHaveBeenCalledWith('inboxes/revalidate', {
+        newKey: cacheKeys.inbox,
+      });
+      expect(mockDispatch).toHaveBeenCalledWith('teams/revalidate', {
+        newKey: cacheKeys.team,
+      });
+      expect(unreadCountFetches()).toHaveLength(1);
+
+      vi.advanceTimersByTime(37499);
+      expect(unreadCountFetches()).toHaveLength(1);
+
+      vi.advanceTimersByTime(1);
+      expect(unreadCountFetches()).toHaveLength(2);
+    });
+
+    it('does not refetch unread counts after cache invalidation when filtered counts are disabled', () => {
+      vi.useFakeTimers();
+      store.$store.getters[
+        'accounts/isFeatureEnabledonAccount'
+      ].mockImplementation(
+        (_, featureFlag) =>
+          featureFlag === FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS
+      );
+
+      actionCable.onReceived({
+        event: 'account.cache_invalidated',
+        data: {
+          account_id: 1,
+          cache_keys: {
+            label: 'label-key',
+            inbox: 'inbox-key',
+            team: 'team-key',
+          },
+        },
+      });
+
+      expect(mockDispatch).not.toHaveBeenCalledWith(
+        'conversationUnreadCounts/get'
+      );
+
+      vi.advanceTimersByTime(45000);
+      expect(mockDispatch).not.toHaveBeenCalledWith(
+        'conversationUnreadCounts/get'
+      );
     });
 
     it('does not refetch unread counts when unread count feature is disabled', () => {
diff --git a/app/javascript/dashboard/helper/specs/sidebarSort.spec.js b/app/javascript/dashboard/helper/specs/sidebarSort.spec.js
index 3919252c2..7b36e0910 100644
--- a/app/javascript/dashboard/helper/specs/sidebarSort.spec.js
+++ b/app/javascript/dashboard/helper/specs/sidebarSort.spec.js
@@ -148,7 +148,7 @@ describe('#normalizeSidebarSortPreferences', () => {
 
   it('falls back to defaults for unsupported preferences', () => {
     const preferences = normalizeSidebarSortPreferences({
-      [SIDEBAR_SORT_SECTIONS.FOLDERS]: SIDEBAR_SORT_KEYS.UNREAD_COUNT_DESC,
+      [SIDEBAR_SORT_SECTIONS.FOLDERS]: 'unsupported_sort',
     });
 
     expect(preferences).toEqual(DEFAULT_SIDEBAR_SORT_PREFERENCES);
@@ -171,6 +171,15 @@ describe('#getSidebarSortOptions', () => {
     expect(options).toContain(SIDEBAR_SORT_KEYS.UNREAD_COUNT_ASC);
   });
 
+  it('keeps folder unread count options when filtered unread counts are enabled', () => {
+    const options = getSidebarSortOptions(SIDEBAR_SORT_SECTIONS.FOLDERS, {
+      hasUnreadCounts: true,
+    });
+
+    expect(options).toContain(SIDEBAR_SORT_KEYS.UNREAD_COUNT_DESC);
+    expect(options).toContain(SIDEBAR_SORT_KEYS.UNREAD_COUNT_ASC);
+  });
+
   it('removes unread count options when unread counts are disabled', () => {
     const options = getSidebarSortOptions(SIDEBAR_SORT_SECTIONS.TEAMS, {
       hasUnreadCounts: false,
@@ -180,6 +189,16 @@ describe('#getSidebarSortOptions', () => {
     expect(options).not.toContain(SIDEBAR_SORT_KEYS.UNREAD_COUNT_ASC);
     expect(options).toContain(SIDEBAR_SORT_KEYS.ALPHABETICAL_ASC);
   });
+
+  it('removes folder unread count options when filtered unread counts are disabled', () => {
+    const options = getSidebarSortOptions(SIDEBAR_SORT_SECTIONS.FOLDERS, {
+      hasUnreadCounts: false,
+    });
+
+    expect(options).not.toContain(SIDEBAR_SORT_KEYS.UNREAD_COUNT_DESC);
+    expect(options).not.toContain(SIDEBAR_SORT_KEYS.UNREAD_COUNT_ASC);
+    expect(options).toContain(SIDEBAR_SORT_KEYS.ALPHABETICAL_ASC);
+  });
 });
 
 describe('#resolveSidebarSort', () => {
@@ -202,4 +221,14 @@ describe('#resolveSidebarSort', () => {
 
     expect(sortBy).toBe(SIDEBAR_SORT_KEYS.ALPHABETICAL_ASC);
   });
+
+  it('falls back to alphabetical sort for folders when filtered unread counts are disabled', () => {
+    const sortBy = resolveSidebarSort(
+      SIDEBAR_SORT_SECTIONS.FOLDERS,
+      SIDEBAR_SORT_KEYS.UNREAD_COUNT_DESC,
+      { hasUnreadCounts: false }
+    );
+
+    expect(sortBy).toBe(SIDEBAR_SORT_KEYS.ALPHABETICAL_ASC);
+  });
 });
diff --git a/app/javascript/dashboard/store/modules/conversationUnreadCounts.js b/app/javascript/dashboard/store/modules/conversationUnreadCounts.js
index c03249311..03bbb31eb 100644
--- a/app/javascript/dashboard/store/modules/conversationUnreadCounts.js
+++ b/app/javascript/dashboard/store/modules/conversationUnreadCounts.js
@@ -6,6 +6,10 @@ export const state = {
   inboxes: {},
   labels: {},
   teams: {},
+  mentionsCount: 0,
+  participatingCount: 0,
+  unattendedCount: 0,
+  folders: {},
 };
 
 const normalizeCount = count => {
@@ -37,6 +41,18 @@ export const getters = {
   getTeamUnreadCount: $state => teamId => {
     return $state.teams[String(teamId)] || 0;
   },
+  getMentionsUnreadCount($state) {
+    return $state.mentionsCount;
+  },
+  getParticipatingUnreadCount($state) {
+    return $state.participatingCount;
+  },
+  getUnattendedUnreadCount($state) {
+    return $state.unattendedCount;
+  },
+  getFolderUnreadCount: $state => folderId => {
+    return $state.folders[String(folderId)] || 0;
+  },
   getInboxUnreadCounts($state) {
     return $state.inboxes;
   },
@@ -46,6 +62,9 @@ export const getters = {
   getTeamUnreadCounts($state) {
     return $state.teams;
   },
+  getFolderUnreadCounts($state) {
+    return $state.folders;
+  },
 };
 
 export const actions = {
@@ -68,6 +87,10 @@ export const mutations = {
     $state.inboxes = normalizeCounts(payload.inboxes);
     $state.labels = normalizeCounts(payload.labels);
     $state.teams = normalizeCounts(payload.teams);
+    $state.mentionsCount = normalizeCount(payload.mentions_count);
+    $state.participatingCount = normalizeCount(payload.participating_count);
+    $state.unattendedCount = normalizeCount(payload.unattended_count);
+    $state.folders = normalizeCounts(payload.folders);
   },
 };
 
diff --git a/app/javascript/dashboard/store/modules/conversationWatchers.js b/app/javascript/dashboard/store/modules/conversationWatchers.js
index c690da21f..da29acaf6 100644
--- a/app/javascript/dashboard/store/modules/conversationWatchers.js
+++ b/app/javascript/dashboard/store/modules/conversationWatchers.js
@@ -1,8 +1,15 @@
 import types from '../mutation-types';
 import { throwErrorMessage } from 'dashboard/store/utils/api';
+import { FEATURE_FLAGS } from 'dashboard/featureFlags';
 
 import ConversationInboxApi from '../../api/inbox/conversation';
 
+const FILTERED_UNREAD_COUNTS_REFRESH_RETRY_MS = 30000;
+const FILTERED_UNREAD_COUNTS_REFRESH_RETRY_JITTER_MS = 15000;
+const getFilteredUnreadCountsRefreshRetryDelay = () =>
+  FILTERED_UNREAD_COUNTS_REFRESH_RETRY_MS +
+  Math.random() * FILTERED_UNREAD_COUNTS_REFRESH_RETRY_JITTER_MS;
+
 const state = {
   records: {},
   uiFlags: {
@@ -20,6 +27,43 @@ export const getters = {
   },
 };
 
+const hasFeatureEnabled = (rootGetters, featureFlag) => {
+  const accountId = rootGetters?.getCurrentAccountId;
+  const isFeatureEnabled = rootGetters?.['accounts/isFeatureEnabledonAccount'];
+
+  return Boolean(accountId && isFeatureEnabled?.(accountId, featureFlag));
+};
+
+const hasCurrentUser = (participants, currentUserId) =>
+  (Array.isArray(participants) ? participants : []).some(
+    participant => participant.id === currentUserId
+  );
+
+const refreshConversationUnreadCounts = dispatch => {
+  dispatch('conversationUnreadCounts/get', {}, { root: true });
+  setTimeout(
+    () => dispatch('conversationUnreadCounts/get', {}, { root: true }),
+    getFilteredUnreadCountsRefreshRetryDelay()
+  );
+};
+
+const shouldRefreshConversationUnreadCounts = (
+  { rootGetters, state: moduleState },
+  conversationId,
+  participants
+) => {
+  const currentUserId =
+    rootGetters?.getCurrentUserID || rootGetters?.getCurrentUser?.id;
+
+  return (
+    currentUserId &&
+    hasFeatureEnabled(rootGetters, FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS) &&
+    hasFeatureEnabled(rootGetters, FEATURE_FLAGS.UNREAD_COUNT_FOR_FILTERS) &&
+    hasCurrentUser(moduleState.records[conversationId], currentUserId) !==
+      hasCurrentUser(participants, currentUserId)
+  );
+};
+
 export const actions = {
   show: async ({ commit }, { conversationId }) => {
     commit(types.SET_CONVERSATION_PARTICIPANTS_UI_FLAG, {
@@ -42,7 +86,10 @@ export const actions = {
     }
   },
 
-  update: async ({ commit }, { conversationId, userIds }) => {
+  update: async (
+    { commit, dispatch, rootGetters, state: moduleState },
+    { conversationId, userIds }
+  ) => {
     commit(types.SET_CONVERSATION_PARTICIPANTS_UI_FLAG, {
       isUpdating: true,
     });
@@ -52,10 +99,18 @@ export const actions = {
         conversationId,
         userIds,
       });
+      const shouldRefreshUnreadCounts = shouldRefreshConversationUnreadCounts(
+        { rootGetters, state: moduleState },
+        conversationId,
+        response.data
+      );
       commit(types.SET_CONVERSATION_PARTICIPANTS, {
         conversationId,
         data: response.data,
       });
+      if (shouldRefreshUnreadCounts) {
+        refreshConversationUnreadCounts(dispatch);
+      }
     } catch (error) {
       throwErrorMessage(error);
     } finally {
diff --git a/app/javascript/dashboard/store/modules/customViews.js b/app/javascript/dashboard/store/modules/customViews.js
index 388388e0f..b4dff3610 100644
--- a/app/javascript/dashboard/store/modules/customViews.js
+++ b/app/javascript/dashboard/store/modules/customViews.js
@@ -1,11 +1,17 @@
 import * as MutationHelpers from 'shared/helpers/vuex/mutationHelpers';
 import types from '../mutation-types';
 import CustomViewsAPI from '../../api/customViews';
+import { FEATURE_FLAGS } from 'dashboard/featureFlags';
 
 const VIEW_TYPES = {
   CONVERSATION: 'conversation',
   CONTACT: 'contact',
 };
+const FILTERED_UNREAD_COUNTS_REFRESH_RETRY_MS = 30000;
+const FILTERED_UNREAD_COUNTS_REFRESH_RETRY_JITTER_MS = 15000;
+const getFilteredUnreadCountsRefreshRetryDelay = () =>
+  FILTERED_UNREAD_COUNTS_REFRESH_RETRY_MS +
+  Math.random() * FILTERED_UNREAD_COUNTS_REFRESH_RETRY_JITTER_MS;
 
 // use to normalize the filter type
 const FILTER_KEYS = {
@@ -21,6 +27,38 @@ const getFolderContactId = folder =>
   folder?.query?.payload?.find(filter => filter.attribute_key === 'contact_id')
     ?.values?.[0];
 
+const hasFeatureEnabled = (rootGetters, featureFlag) => {
+  const accountId = rootGetters?.getCurrentAccountId;
+  const isFeatureEnabled = rootGetters?.['accounts/isFeatureEnabledonAccount'];
+
+  return Boolean(accountId && isFeatureEnabled?.(accountId, featureFlag));
+};
+
+const shouldRefreshConversationUnreadCounts = (filterType, rootGetters) => {
+  return (
+    FILTER_KEYS[filterType] === VIEW_TYPES.CONVERSATION &&
+    hasFeatureEnabled(rootGetters, FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS) &&
+    hasFeatureEnabled(rootGetters, FEATURE_FLAGS.UNREAD_COUNT_FOR_FILTERS)
+  );
+};
+
+const dispatchConversationUnreadCounts = dispatch => {
+  dispatch('conversationUnreadCounts/get', {}, { root: true });
+};
+
+const refreshConversationUnreadCounts = (
+  { dispatch, rootGetters },
+  filterType
+) => {
+  if (!shouldRefreshConversationUnreadCounts(filterType, rootGetters)) return;
+
+  dispatchConversationUnreadCounts(dispatch);
+  setTimeout(
+    () => dispatchConversationUnreadCounts(dispatch),
+    getFilteredUnreadCountsRefreshRetryDelay()
+  );
+};
+
 export const state = {
   [VIEW_TYPES.CONVERSATION]: {
     records: [],
@@ -71,14 +109,19 @@ export const actions = {
       commit(types.SET_CUSTOM_VIEW_UI_FLAG, { isFetching: false });
     }
   },
-  create: async function createCustomViews({ commit }, obj) {
+  create: async function createCustomViews(
+    { commit, dispatch, rootGetters },
+    obj
+  ) {
     commit(types.SET_CUSTOM_VIEW_UI_FLAG, { isCreating: true });
     try {
       const response = await CustomViewsAPI.create(obj);
+      const filterType = FILTER_KEYS[obj.filter_type];
       commit(types.ADD_CUSTOM_VIEW, {
         data: response.data,
-        filterType: FILTER_KEYS[obj.filter_type],
+        filterType,
       });
+      refreshConversationUnreadCounts({ dispatch, rootGetters }, filterType);
       return response;
     } catch (error) {
       const errorMessage = error?.response?.data?.message;
@@ -87,14 +130,19 @@ export const actions = {
       commit(types.SET_CUSTOM_VIEW_UI_FLAG, { isCreating: false });
     }
   },
-  update: async function updateCustomViews({ commit }, obj) {
+  update: async function updateCustomViews(
+    { commit, dispatch, rootGetters },
+    obj
+  ) {
     commit(types.SET_CUSTOM_VIEW_UI_FLAG, { isCreating: true });
     try {
       const response = await CustomViewsAPI.update(obj.id, obj);
+      const filterType = FILTER_KEYS[obj.filter_type];
       commit(types.UPDATE_CUSTOM_VIEW, {
         data: response.data,
-        filterType: FILTER_KEYS[obj.filter_type],
+        filterType,
       });
+      refreshConversationUnreadCounts({ dispatch, rootGetters }, filterType);
     } catch (error) {
       const errorMessage = error?.response?.data?.message;
       throw new Error(errorMessage);
@@ -102,11 +150,12 @@ export const actions = {
       commit(types.SET_CUSTOM_VIEW_UI_FLAG, { isCreating: false });
     }
   },
-  delete: async ({ commit }, { id, filterType }) => {
+  delete: async ({ commit, dispatch, rootGetters }, { id, filterType }) => {
     commit(types.SET_CUSTOM_VIEW_UI_FLAG, { isDeleting: true });
     try {
       await CustomViewsAPI.deleteCustomViews(id, filterType);
       commit(types.DELETE_CUSTOM_VIEW, { data: id, filterType });
+      refreshConversationUnreadCounts({ dispatch, rootGetters }, filterType);
     } catch (error) {
       throw new Error(error);
     } finally {
diff --git a/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/actions.spec.js b/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/actions.spec.js
index 29fadc897..c3d040d84 100644
--- a/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/actions.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/actions.spec.js
@@ -19,6 +19,10 @@ describe('#actions', () => {
         inboxes: { 1: '2' },
         labels: { 3: 4 },
         teams: { 5: 6 },
+        mentions_count: 7,
+        participating_count: 8,
+        unattended_count: 9,
+        folders: { 10: 11 },
       };
       axios.get.mockResolvedValue({ data: { payload } });
 
diff --git a/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/getters.spec.js b/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/getters.spec.js
index 9fe19e22d..9b7467ae1 100644
--- a/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/getters.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/getters.spec.js
@@ -7,6 +7,7 @@ describe('#getters', () => {
       inboxes: { 1: 2 },
       labels: {},
       teams: {},
+      folders: {},
     };
 
     expect(getters.getInboxUnreadCount(state)(1)).toBe(2);
@@ -20,6 +21,7 @@ describe('#getters', () => {
       inboxes: {},
       labels: { 3: 4 },
       teams: {},
+      folders: {},
     };
 
     expect(getters.getLabelUnreadCount(state)(3)).toBe(4);
@@ -33,6 +35,7 @@ describe('#getters', () => {
       inboxes: {},
       labels: {},
       teams: { 5: 6 },
+      folders: {},
     };
 
     expect(getters.getTeamUnreadCount(state)(5)).toBe(6);
@@ -46,21 +49,44 @@ describe('#getters', () => {
       inboxes: {},
       labels: {},
       teams: {},
+      folders: {},
     };
 
     expect(getters.getAllUnreadCount(state)).toBe(7);
   });
 
+  it('returns filtered unread counts', () => {
+    const state = {
+      allCount: 0,
+      inboxes: {},
+      labels: {},
+      teams: {},
+      mentionsCount: 1,
+      participatingCount: 2,
+      unattendedCount: 3,
+      folders: { 8: 4 },
+    };
+
+    expect(getters.getMentionsUnreadCount(state)).toBe(1);
+    expect(getters.getParticipatingUnreadCount(state)).toBe(2);
+    expect(getters.getUnattendedUnreadCount(state)).toBe(3);
+    expect(getters.getFolderUnreadCount(state)(8)).toBe(4);
+    expect(getters.getFolderUnreadCount(state)('8')).toBe(4);
+    expect(getters.getFolderUnreadCount(state)(9)).toBe(0);
+  });
+
   it('returns unread count maps', () => {
     const state = {
       allCount: 0,
       inboxes: { 1: 2 },
       labels: { 3: 4 },
       teams: { 5: 6 },
+      folders: { 7: 8 },
     };
 
     expect(getters.getInboxUnreadCounts(state)).toEqual({ 1: 2 });
     expect(getters.getLabelUnreadCounts(state)).toEqual({ 3: 4 });
     expect(getters.getTeamUnreadCounts(state)).toEqual({ 5: 6 });
+    expect(getters.getFolderUnreadCounts(state)).toEqual({ 7: 8 });
   });
 });
diff --git a/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/mutations.spec.js b/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/mutations.spec.js
index 8941d7430..60785593c 100644
--- a/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/mutations.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/conversationUnreadCounts/mutations.spec.js
@@ -4,7 +4,16 @@ import { mutations } from '../../conversationUnreadCounts';
 describe('#mutations', () => {
   describe('#SET_CONVERSATION_UNREAD_COUNTS', () => {
     it('normalizes unread count payload', () => {
-      const state = { allCount: 0, inboxes: {}, labels: {}, teams: {} };
+      const state = {
+        allCount: 0,
+        inboxes: {},
+        labels: {},
+        teams: {},
+        mentionsCount: 0,
+        participatingCount: 0,
+        unattendedCount: 0,
+        folders: {},
+      };
 
       mutations[types.SET_CONVERSATION_UNREAD_COUNTS](state, {
         all_count: '3',
@@ -21,6 +30,13 @@ describe('#mutations', () => {
           6: '7',
           7: 0,
         },
+        mentions_count: '8',
+        participating_count: 9,
+        unattended_count: 0,
+        folders: {
+          10: '11',
+          12: -1,
+        },
       });
 
       expect(state).toEqual({
@@ -28,6 +44,10 @@ describe('#mutations', () => {
         inboxes: { 1: 2 },
         labels: { 4: 5 },
         teams: { 6: 7 },
+        mentionsCount: 8,
+        participatingCount: 9,
+        unattendedCount: 0,
+        folders: { 10: 11 },
       });
     });
 
@@ -37,6 +57,10 @@ describe('#mutations', () => {
         inboxes: { 1: 2 },
         labels: { 4: 5 },
         teams: { 6: 7 },
+        mentionsCount: 8,
+        participatingCount: 9,
+        unattendedCount: 10,
+        folders: { 11: 12 },
       };
 
       mutations[types.SET_CONVERSATION_UNREAD_COUNTS](state, {});
@@ -46,17 +70,36 @@ describe('#mutations', () => {
         inboxes: {},
         labels: {},
         teams: {},
+        mentionsCount: 0,
+        participatingCount: 0,
+        unattendedCount: 0,
+        folders: {},
       });
     });
 
     it('normalizes invalid aggregate counts to zero', () => {
-      const state = { allCount: 2, inboxes: {}, labels: {}, teams: {} };
+      const state = {
+        allCount: 2,
+        inboxes: {},
+        labels: {},
+        teams: {},
+        mentionsCount: 2,
+        participatingCount: 3,
+        unattendedCount: 4,
+        folders: {},
+      };
 
       mutations[types.SET_CONVERSATION_UNREAD_COUNTS](state, {
         all_count: 'invalid',
+        mentions_count: 'invalid',
+        participating_count: -1,
+        unattended_count: 0,
       });
 
       expect(state.allCount).toBe(0);
+      expect(state.mentionsCount).toBe(0);
+      expect(state.participatingCount).toBe(0);
+      expect(state.unattendedCount).toBe(0);
     });
   });
 });
diff --git a/app/javascript/dashboard/store/modules/specs/conversationWatchers/actions.spec.js b/app/javascript/dashboard/store/modules/specs/conversationWatchers/actions.spec.js
index b3cfabeba..defa9a3db 100644
--- a/app/javascript/dashboard/store/modules/specs/conversationWatchers/actions.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/conversationWatchers/actions.spec.js
@@ -1,11 +1,32 @@
 import axios from 'axios';
 import { actions } from '../../conversationWatchers';
 import types from '../../../mutation-types';
+import { FEATURE_FLAGS } from '../../../../featureFlags';
 
 const commit = vi.fn();
 global.axios = axios;
 vi.mock('axios');
 
+const mockRetryJitter = value =>
+  vi.spyOn(Math, 'random').mockReturnValue(value);
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
+
+const conversationUnreadCountsEnabledRootGetters = {
+  getCurrentAccountId: 1,
+  getCurrentUserID: 1,
+  'accounts/isFeatureEnabledonAccount': vi.fn((_, featureFlag) =>
+    [
+      FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS,
+      FEATURE_FLAGS.UNREAD_COUNT_FOR_FILTERS,
+    ].includes(featureFlag)
+  ),
+};
+
 describe('#actions', () => {
   describe('#get', () => {
     it('sends correct actions if API is success', async () => {
@@ -48,6 +69,56 @@ describe('#actions', () => {
         [types.SET_CONVERSATION_PARTICIPANTS_UI_FLAG, { isUpdating: false }],
       ]);
     });
+    it('refetches unread counts when the current user starts watching', async () => {
+      vi.useFakeTimers();
+      mockRetryJitter(0.5);
+      const dispatch = vi.fn();
+      const moduleState = { records: { 2: [] } };
+      const mutatingCommit = vi.fn((mutation, payload) => {
+        if (mutation === types.SET_CONVERSATION_PARTICIPANTS) {
+          moduleState.records[payload.conversationId] = payload.data;
+        }
+      });
+      axios.patch.mockResolvedValue({ data: [{ id: 1 }] });
+
+      await actions.update(
+        {
+          commit: mutatingCommit,
+          dispatch,
+          rootGetters: conversationUnreadCountsEnabledRootGetters,
+          state: moduleState,
+        },
+        { conversationId: 2, userIds: [1] }
+      );
+
+      expect(dispatch).toHaveBeenCalledWith(
+        'conversationUnreadCounts/get',
+        {},
+        { root: true }
+      );
+
+      vi.advanceTimersByTime(37499);
+      expect(dispatch).toHaveBeenCalledTimes(1);
+
+      vi.advanceTimersByTime(1);
+      expect(dispatch).toHaveBeenCalledTimes(2);
+    });
+    it('does not refetch unread counts when another watcher changes', async () => {
+      const dispatch = vi.fn();
+      axios.patch.mockResolvedValue({ data: [{ id: 1 }, { id: 2 }] });
+
+      await actions.update(
+        {
+          commit,
+          dispatch,
+          rootGetters: conversationUnreadCountsEnabledRootGetters,
+          state: { records: { 2: [{ id: 1 }] } },
+        },
+        { conversationId: 2, userIds: [1, 2] }
+      );
+
+      expect(dispatch).not.toHaveBeenCalled();
+    });
     it('sends correct actions if API is error', async () => {
       axios.patch.mockRejectedValue({ message: 'Incorrect header' });
       await expect(
diff --git a/app/javascript/dashboard/store/modules/specs/customViews/actions.spec.js b/app/javascript/dashboard/store/modules/specs/customViews/actions.spec.js
index a09dda17f..a1ea0638d 100644
--- a/app/javascript/dashboard/store/modules/specs/customViews/actions.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/customViews/actions.spec.js
@@ -1,6 +1,7 @@
 import axios from 'axios';
 import * as types from '../../../mutation-types';
 import { actions } from '../../customViews';
+import { FEATURE_FLAGS } from '../../../../featureFlags';
 import {
   contactFilterView,
   customViewList,
@@ -11,6 +12,25 @@ const commit = vi.fn();
 global.axios = axios;
 vi.mock('axios');
 
+const mockRetryJitter = value =>
+  vi.spyOn(Math, 'random').mockReturnValue(value);
+
+const conversationUnreadCountsEnabledRootGetters = {
+  getCurrentAccountId: 1,
+  'accounts/isFeatureEnabledonAccount': vi.fn((_, featureFlag) =>
+    [
+      FEATURE_FLAGS.CONVERSATION_UNREAD_COUNTS,
+      FEATURE_FLAGS.UNREAD_COUNT_FOR_FILTERS,
+    ].includes(featureFlag)
+  ),
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
+
 describe('#actions', () => {
   describe('#get', () => {
     it('sends correct actions if API is success', async () => {
@@ -49,6 +69,36 @@ describe('#actions', () => {
         [types.default.SET_CUSTOM_VIEW_UI_FLAG, { isCreating: false }],
       ]);
     });
+
+    it('refetches unread counts after creating a conversation folder', async () => {
+      vi.useFakeTimers();
+      mockRetryJitter(0.5);
+      const dispatch = vi.fn();
+      const firstItem = customViewList[0];
+      axios.post.mockResolvedValue({ data: firstItem });
+
+      await actions.create(
+        {
+          commit,
+          dispatch,
+          rootGetters: conversationUnreadCountsEnabledRootGetters,
+        },
+        firstItem
+      );
+
+      expect(dispatch).toHaveBeenCalledWith(
+        'conversationUnreadCounts/get',
+        {},
+        { root: true }
+      );
+
+      vi.advanceTimersByTime(37499);
+      expect(dispatch).toHaveBeenCalledTimes(1);
+
+      vi.advanceTimersByTime(1);
+      expect(dispatch).toHaveBeenCalledTimes(2);
+    });
+
     it('sends correct actions if API is error', async () => {
       axios.post.mockRejectedValue({ message: 'Incorrect header' });
       await expect(actions.create({ commit })).rejects.toThrow(Error);
@@ -69,6 +119,44 @@ describe('#actions', () => {
         [types.default.SET_CUSTOM_VIEW_UI_FLAG, { isDeleting: false }],
       ]);
     });
+
+    it('refetches unread counts after deleting a conversation folder', async () => {
+      vi.useFakeTimers();
+      const dispatch = vi.fn();
+      axios.delete.mockResolvedValue({ data: customViewList[0] });
+
+      await actions.delete(
+        {
+          commit,
+          dispatch,
+          rootGetters: conversationUnreadCountsEnabledRootGetters,
+        },
+        { id: 1, filterType: 'conversation' }
+      );
+
+      expect(dispatch).toHaveBeenCalledWith(
+        'conversationUnreadCounts/get',
+        {},
+        { root: true }
+      );
+    });
+
+    it('does not refetch unread counts after deleting a contact segment', async () => {
+      const dispatch = vi.fn();
+      axios.delete.mockResolvedValue({ data: contactFilterView });
+
+      await actions.delete(
+        {
+          commit,
+          dispatch,
+          rootGetters: conversationUnreadCountsEnabledRootGetters,
+        },
+        { id: 1, filterType: 'contact' }
+      );
+
+      expect(dispatch).not.toHaveBeenCalled();
+    });
+
     it('sends correct actions if API is error', async () => {
       axios.delete.mockRejectedValue({ message: 'Incorrect header' });
       await expect(actions.delete({ commit }, 1)).rejects.toThrow(Error);
@@ -93,6 +181,29 @@ describe('#actions', () => {
         [types.default.SET_CUSTOM_VIEW_UI_FLAG, { isCreating: false }],
       ]);
     });
+
+    it('refetches unread counts after updating a conversation folder', async () => {
+      vi.useFakeTimers();
+      const dispatch = vi.fn();
+      const item = updateCustomViewList[0];
+      axios.patch.mockResolvedValue({ data: item });
+
+      await actions.update(
+        {
+          commit,
+          dispatch,
+          rootGetters: conversationUnreadCountsEnabledRootGetters,
+        },
+        item
+      );
+
+      expect(dispatch).toHaveBeenCalledWith(
+        'conversationUnreadCounts/get',
+        {},
+        { root: true }
+      );
+    });
+
     it('sends correct actions if API is error', async () => {
       axios.patch.mockRejectedValue({ message: 'Incorrect header' });
       await expect(actions.update({ commit }, 1)).rejects.toThrow(Error);
diff --git a/app/javascript/dashboard/store/modules/specs/sidebarSortPreferences/actions.spec.js b/app/javascript/dashboard/store/modules/specs/sidebarSortPreferences/actions.spec.js
index 7fee1d018..5242f2125 100644
--- a/app/javascript/dashboard/store/modules/specs/sidebarSortPreferences/actions.spec.js
+++ b/app/javascript/dashboard/store/modules/specs/sidebarSortPreferences/actions.spec.js
@@ -83,7 +83,7 @@ describe('#actions', () => {
       );
     });
 
-    it('ignores invalid preferences', () => {
+    it('ignores invalid sort values', () => {
       actions.setSectionSort(
         {
           commit,
@@ -95,7 +95,7 @@ describe('#actions', () => {
         },
         {
           section: SIDEBAR_SORT_SECTIONS.FOLDERS,
-          sortBy: SIDEBAR_SORT_KEYS.UNREAD_COUNT_DESC,
+          sortBy: 'invalid_sort',
         }
       );
 
diff --git a/app/jobs/agents/destroy_job.rb b/app/jobs/agents/destroy_job.rb
index 8596ca1cc..fe0276bc6 100644
--- a/app/jobs/agents/destroy_job.rb
+++ b/app/jobs/agents/destroy_job.rb
@@ -31,7 +31,11 @@ class Agents::DestroyJob < ApplicationJob
 
   def unassign_conversations(account, user)
     # rubocop:disable Rails/SkipsModelValidations
-    user.assigned_conversations.where(account: account).in_batches.update_all(assignee_id: nil)
+    unassigned_count = user.assigned_conversations.where(account: account).in_batches.update_all(assignee_id: nil)
     # rubocop:enable Rails/SkipsModelValidations
+
+    return unless unassigned_count.positive?
+
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).conversation_changed!
   end
 end
diff --git a/app/models/account_user.rb b/app/models/account_user.rb
index bbcb0e010..cdacb9b0e 100644
--- a/app/models/account_user.rb
+++ b/app/models/account_user.rb
@@ -39,6 +39,8 @@ class AccountUser < ApplicationRecord
   after_create_commit :notify_creation, :create_notification_setting
   after_destroy :notify_deletion, :remove_user_from_account
   after_save :update_presence_in_redis, if: :saved_change_to_availability?
+  after_commit :invalidate_filtered_unread_count_visibility, on: [:create, :destroy]
+  after_update_commit :invalidate_filtered_unread_count_visibility_update, if: :filtered_unread_count_visibility_changed?
 
   validates :user_id, uniqueness: { scope: :account_id }
 
@@ -79,6 +81,22 @@ class AccountUser < ApplicationRecord
   def update_presence_in_redis
     OnlineStatusTracker.set_status(account.id, user.id, availability)
   end
+
+  def filtered_unread_count_visibility_changed?
+    previous_changes.key?('role') || previous_changes.key?('custom_role_id')
+  end
+
+  def invalidate_filtered_unread_count_visibility
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).user_visibility_changed!(user_id: user_id)
+  end
+
+  def invalidate_filtered_unread_count_visibility_update
+    dispatch_account_cache_invalidated if invalidate_filtered_unread_count_visibility
+  end
+
+  def dispatch_account_cache_invalidated
+    Rails.configuration.dispatcher.dispatch(ACCOUNT_CACHE_INVALIDATED, Time.zone.now, account: account, cache_keys: account.cache_keys)
+  end
 end
 
 AccountUser.prepend_mod_with('AccountUser')
diff --git a/app/models/campaign.rb b/app/models/campaign.rb
index 1d4da7712..479b5bdd0 100644
--- a/app/models/campaign.rb
+++ b/app/models/campaign.rb
@@ -53,6 +53,7 @@ class Campaign < ApplicationRecord
 
   before_validation :ensure_correct_campaign_attributes
   after_commit :set_display_id, unless: :display_id?
+  after_destroy_commit :invalidate_filtered_unread_count_filters
 
   def trigger!
     return unless one_off?
@@ -88,6 +89,15 @@ class Campaign < ApplicationRecord
     end
   end
 
+  def invalidate_filtered_unread_count_filters
+    filters_changed = ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).conversation_changed!
+    dispatch_account_cache_invalidated if filters_changed
+  end
+
+  def dispatch_account_cache_invalidated
+    Rails.configuration.dispatcher.dispatch(ACCOUNT_CACHE_INVALIDATED, Time.zone.now, account: account, cache_keys: account.cache_keys)
+  end
+
   def set_display_id
     reload
   end
diff --git a/app/models/concerns/account_cache_revalidator.rb b/app/models/concerns/account_cache_revalidator.rb
index b5ff5a473..d2bfaf294 100644
--- a/app/models/concerns/account_cache_revalidator.rb
+++ b/app/models/concerns/account_cache_revalidator.rb
@@ -6,6 +6,8 @@ module AccountCacheRevalidator
   end
 
   def update_account_cache
+    return if account.blank?
+
     account.update_cache_key(self.class.name.underscore)
   end
 end
diff --git a/app/models/conversation.rb b/app/models/conversation.rb
index d9c06c4d8..1e9c38c41 100644
--- a/app/models/conversation.rb
+++ b/app/models/conversation.rb
@@ -62,6 +62,14 @@ class Conversation < ApplicationRecord
   include PushDataHelper
   include ConversationMuteHelpers
 
+  CONVERSATION_UPDATED_ADDITIONAL_ATTRIBUTE_KEYS = %w[conversation_language].freeze
+  FILTERED_UNREAD_COUNT_ADDITIONAL_ATTRIBUTE_KEYS = %w[browser_language conversation_language mail_subject referer].freeze
+  FILTERED_UNREAD_COUNT_UPDATE_KEYS = %w[
+    cached_label_list campaign_id custom_attributes first_reply_created_at label_list last_activity_at priority snoozed_until waiting_since
+  ].freeze
+  private_constant :CONVERSATION_UPDATED_ADDITIONAL_ATTRIBUTE_KEYS, :FILTERED_UNREAD_COUNT_ADDITIONAL_ATTRIBUTE_KEYS,
+                   :FILTERED_UNREAD_COUNT_UPDATE_KEYS
+
   validates :account_id, presence: true
   validates :inbox_id, presence: true
   validates :contact_id, presence: true
@@ -247,6 +255,7 @@ class Conversation < ApplicationRecord
     handle_resolved_status_change
     notify_status_change
     create_activity
+    invalidate_filtered_unread_count_conversation
     notify_conversation_updation
   end
 
@@ -313,10 +322,23 @@ class Conversation < ApplicationRecord
   end
 
   def allowed_keys?
-    (
-      previous_changes.keys.intersect?(list_of_keys) ||
-      (previous_changes['additional_attributes'].present? && previous_changes['additional_attributes'][1].keys.intersect?(%w[conversation_language]))
-    )
+    previous_changes.keys.intersect?(list_of_keys) ||
+      additional_attributes_changed?(CONVERSATION_UPDATED_ADDITIONAL_ATTRIBUTE_KEYS)
+  end
+
+  def invalidate_filtered_unread_count_conversation
+    return unless filtered_unread_count_update?
+
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).conversation_changed!
+  end
+
+  def filtered_unread_count_update?
+    previous_changes.keys.intersect?(FILTERED_UNREAD_COUNT_UPDATE_KEYS) ||
+      additional_attributes_changed?(FILTERED_UNREAD_COUNT_ADDITIONAL_ATTRIBUTE_KEYS)
+  end
+
+  def additional_attributes_changed?(keys)
+    Array(previous_changes['additional_attributes']).compact.any? { |attributes| attributes.keys.intersect?(keys) }
   end
 
   def load_attributes_created_by_db_triggers
diff --git a/app/models/conversation_participant.rb b/app/models/conversation_participant.rb
index 830eb7baa..4103deda4 100644
--- a/app/models/conversation_participant.rb
+++ b/app/models/conversation_participant.rb
@@ -28,6 +28,7 @@ class ConversationParticipant < ApplicationRecord
   belongs_to :user
 
   before_validation :ensure_account_id
+  after_commit :invalidate_filtered_unread_count_visibility, on: [:create, :destroy]
 
   private
 
@@ -38,4 +39,8 @@ class ConversationParticipant < ApplicationRecord
   def ensure_inbox_access
     errors.add(:user, 'must have inbox access') if conversation && conversation.inbox.assignable_agents.exclude?(user)
   end
+
+  def invalidate_filtered_unread_count_visibility
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).user_visibility_changed!(user_id: user_id)
+  end
 end
diff --git a/app/models/custom_attribute_definition.rb b/app/models/custom_attribute_definition.rb
index 35f822335..8270cc70e 100644
--- a/app/models/custom_attribute_definition.rb
+++ b/app/models/custom_attribute_definition.rb
@@ -48,6 +48,8 @@ class CustomAttributeDefinition < ApplicationRecord
   belongs_to :account
   after_update :update_widget_pre_chat_custom_fields, unless: :company_attribute?
   after_destroy :sync_widget_pre_chat_custom_fields, unless: :company_attribute?
+  after_update_commit :invalidate_filtered_unread_count_filters_update, if: :conversation_attribute_before_or_after?
+  after_destroy_commit :invalidate_filtered_unread_count_filters_destroy, if: :conversation_attribute?
 
   private
 
@@ -64,6 +66,27 @@ class CustomAttributeDefinition < ApplicationRecord
     ::Inboxes::UpdateWidgetPreChatCustomFieldsJob.perform_later(account, self)
   end
 
+  def invalidate_filtered_unread_count_filters_update
+    invalidate_filtered_unread_count_filters
+  end
+
+  def invalidate_filtered_unread_count_filters_destroy
+    invalidate_filtered_unread_count_filters
+  end
+
+  def invalidate_filtered_unread_count_filters
+    filters_changed = ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).custom_attribute_definition_changed!(self)
+    dispatch_account_cache_invalidated if filters_changed
+  end
+
+  def dispatch_account_cache_invalidated
+    Rails.configuration.dispatcher.dispatch(ACCOUNT_CACHE_INVALIDATED, Time.zone.now, account: account, cache_keys: account.cache_keys)
+  end
+
+  def conversation_attribute_before_or_after?
+    conversation_attribute? || attribute_model_previously_was == 'conversation_attribute'
+  end
+
   def attribute_must_not_conflict
     model_keys = attribute_model.to_s.delete_suffix('_attribute').to_sym
     standard_attributes = STANDARD_ATTRIBUTES[model_keys]
diff --git a/app/models/custom_filter.rb b/app/models/custom_filter.rb
index 6d64c0447..6e2461a74 100644
--- a/app/models/custom_filter.rb
+++ b/app/models/custom_filter.rb
@@ -22,10 +22,31 @@ class CustomFilter < ApplicationRecord
 
   enum filter_type: { conversation: 0, contact: 1, report: 2 }
   validate :validate_number_of_filters
+  after_create_commit :invalidate_filtered_unread_count_create
+  after_update_commit :invalidate_filtered_unread_count_update
+  after_destroy_commit :invalidate_filtered_unread_count_destroy
 
   def validate_number_of_filters
     return true if account.custom_filters.where(user_id: user_id).size < Limits::MAX_CUSTOM_FILTERS_PER_USER
 
     errors.add :account_id, I18n.t('errors.custom_filters.number_of_records')
   end
+
+  private
+
+  def invalidate_filtered_unread_count_create
+    filtered_count_invalidator.custom_filter_created!(self)
+  end
+
+  def invalidate_filtered_unread_count_update
+    filtered_count_invalidator.custom_filter_updated!(self)
+  end
+
+  def invalidate_filtered_unread_count_destroy
+    filtered_count_invalidator.custom_filter_destroyed!(self)
+  end
+
+  def filtered_count_invalidator
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account)
+  end
 end
diff --git a/app/models/inbox.rb b/app/models/inbox.rb
index 15bfe77dd..1b0cfc587 100644
--- a/app/models/inbox.rb
+++ b/app/models/inbox.rb
@@ -77,10 +77,12 @@ class Inbox < ApplicationRecord
 
   enum sender_name_type: { friendly: 0, professional: 1 }
 
+  before_destroy :capture_filtered_unread_count_user_ids, prepend: true
   after_destroy :delete_round_robin_agents
 
   after_create_commit :dispatch_create_event
   after_update_commit :dispatch_update_event
+  after_destroy_commit :invalidate_filtered_unread_counts_after_destroy
 
   scope :order_by_name, -> { order('lower(name) ASC') }
 
@@ -261,6 +263,18 @@ class Inbox < ApplicationRecord
     ::AutoAssignment::InboxRoundRobinService.new(inbox: self).clear_queue
   end
 
+  def capture_filtered_unread_count_user_ids
+    return if account.blank?
+
+    @filtered_unread_count_user_ids = (inbox_members.pluck(:user_id) + account.account_users.administrator.pluck(:user_id)).uniq
+  end
+
+  def invalidate_filtered_unread_counts_after_destroy
+    invalidator = ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account)
+    invalidator.conversation_changed!
+    invalidator.users_visibility_changed!(user_ids: @filtered_unread_count_user_ids)
+  end
+
   def check_channel_type?
     ['Channel::Email', 'Channel::Api', 'Channel::WebWidget'].include?(channel_type)
   end
diff --git a/app/models/inbox_member.rb b/app/models/inbox_member.rb
index d4a36ccc8..bc4014da9 100644
--- a/app/models/inbox_member.rb
+++ b/app/models/inbox_member.rb
@@ -24,6 +24,7 @@ class InboxMember < ApplicationRecord
 
   after_create :add_agent_to_round_robin
   after_destroy :remove_agent_from_round_robin
+  after_commit :invalidate_filtered_unread_count_visibility, on: [:create, :destroy]
 
   private
 
@@ -34,6 +35,10 @@ class InboxMember < ApplicationRecord
   def remove_agent_from_round_robin
     ::AutoAssignment::InboxRoundRobinService.new(inbox: inbox).remove_agent_from_queue(user_id) if inbox.present?
   end
+
+  def invalidate_filtered_unread_count_visibility
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(inbox&.account).user_visibility_changed!(user_id: user_id)
+  end
 end
 
 InboxMember.include_mod_with('Audit::InboxMember')
diff --git a/app/models/team.rb b/app/models/team.rb
index 15de8ab56..b19f215ca 100644
--- a/app/models/team.rb
+++ b/app/models/team.rb
@@ -25,6 +25,9 @@ class Team < ApplicationRecord
   has_many :members, through: :team_members, source: :user
   has_many :conversations, dependent: :nullify
 
+  before_destroy :capture_filtered_unread_count_member_ids, prepend: true
+  after_destroy_commit :invalidate_filtered_unread_counts_after_destroy
+
   validates :name,
             presence: { message: I18n.t('errors.validations.presence') },
             uniqueness: { scope: :account_id }
@@ -69,6 +72,18 @@ class Team < ApplicationRecord
       icon_color: icon_color
     }
   end
+
+  private
+
+  def capture_filtered_unread_count_member_ids
+    @filtered_unread_count_member_ids = team_members.pluck(:user_id)
+  end
+
+  def invalidate_filtered_unread_counts_after_destroy
+    invalidator = ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account)
+    invalidator.conversation_changed!
+    invalidator.users_visibility_changed!(user_ids: @filtered_unread_count_member_ids)
+  end
 end
 
 Team.include_mod_with('Audit::Team')
diff --git a/app/models/team_member.rb b/app/models/team_member.rb
index f99af264b..0d0e0aa22 100644
--- a/app/models/team_member.rb
+++ b/app/models/team_member.rb
@@ -18,6 +18,14 @@ class TeamMember < ApplicationRecord
   belongs_to :user
   belongs_to :team
   validates :user_id, uniqueness: { scope: :team_id }
+
+  after_commit :invalidate_filtered_unread_count_visibility, on: [:create, :destroy]
+
+  private
+
+  def invalidate_filtered_unread_count_visibility
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(team&.account).user_visibility_changed!(user_id: user_id)
+  end
 end
 
 TeamMember.include_mod_with('Audit::TeamMember')
diff --git a/app/services/conversations/unread_counts.rb b/app/services/conversations/unread_counts.rb
index 668395063..1b3ee3fb2 100644
--- a/app/services/conversations/unread_counts.rb
+++ b/app/services/conversations/unread_counts.rb
@@ -1,4 +1,10 @@
 module Conversations::UnreadCounts
   READY_TTL = 24.hours.to_i
   SET_TTL = 25.hours.to_i
+  FILTERED_COUNT_FRESH_TTL = 5.minutes.to_i
+  FILTERED_COUNT_STALE_WINDOW = 30.minutes.to_i
+  FILTERED_COUNT_REDIS_TTL = FILTERED_COUNT_FRESH_TTL + FILTERED_COUNT_STALE_WINDOW
+  FILTERED_COUNT_VERSION_TTL = SET_TTL
+  FILTERED_COUNT_MIN_REFRESH_INTERVAL = 30.seconds.to_i
+  MAX_INLINE_FILTER_BUILDS = 10
 end
diff --git a/app/services/conversations/unread_counts/counter.rb b/app/services/conversations/unread_counts/counter.rb
index b1ba5ddb0..2a015f3a6 100644
--- a/app/services/conversations/unread_counts/counter.rb
+++ b/app/services/conversations/unread_counts/counter.rb
@@ -14,7 +14,7 @@ class Conversations::UnreadCounts::Counter
   end
 
   def perform
-    return empty_counts if permission_mode == :none
+    return with_filtered_counts(empty_counts, build: false) if permission_mode == :none
 
     ensure_base_cache!
     ensure_assignment_cache! if assignment_mode?
@@ -26,11 +26,17 @@ class Conversations::UnreadCounts::Counter
       inboxes: inbox_counts,
       labels: unread_label_counts,
       teams: unread_team_counts
-    }
+    }.then { |counts| with_filtered_counts(counts) }
   end
 
   private
 
+  def with_filtered_counts(counts, build: true)
+    return counts unless account.feature_enabled?(::Conversations::UnreadCounts::FilteredCounter::FEATURE_FLAG)
+
+    counts.merge(build ? filtered_counter.perform : ::Conversations::UnreadCounts::FilteredCounter.empty_counts)
+  end
+
   def ensure_base_cache!
     ensure_cache_ready!(
       ready: -> { store.base_ready?(account.id) },
@@ -200,4 +206,8 @@ class Conversations::UnreadCounts::Counter
   def store
     ::Conversations::UnreadCounts::Store
   end
+
+  def filtered_counter
+    @filtered_counter ||= ::Conversations::UnreadCounts::FilteredCounter.new(account: account, user: user)
+  end
 end
diff --git a/app/services/conversations/unread_counts/filter_query_counter.rb b/app/services/conversations/unread_counts/filter_query_counter.rb
new file mode 100644
index 000000000..238bed2a1
--- /dev/null
+++ b/app/services/conversations/unread_counts/filter_query_counter.rb
@@ -0,0 +1,151 @@
+class Conversations::UnreadCounts::FilterQueryCounter < Conversations::FilterService
+  BOOLEAN_VALUES = %w[0 1 false f n no off on t true y yes].freeze
+  DATABASE_CAST_ERROR_CLASS_NAMES = %w[
+    PG::DatetimeFieldOverflow
+    PG::InvalidDatetimeFormat
+    PG::InvalidTextRepresentation
+    PG::NumericValueOutOfRange
+  ].freeze
+  DAYS_BEFORE_FILTER_OPERATOR = 'days_before'.freeze
+  MALFORMED_QUERY_ERRORS = [NoMethodError, TypeError].freeze
+  NUMERIC_ATTRIBUTE_KEYS = %w[assignee_id inbox_id].freeze
+  TEXT_DATA_TYPES = %w[labels link text text_case_insensitive].freeze
+  TEXT_FILTER_OPERATORS = %w[contains does_not_contain].freeze
+  TYPED_DATA_TYPES = %w[boolean date number numeric].freeze
+  VALID_QUERY_OPERATORS = %w[AND OR].freeze
+  VALIDATION_DATA_TYPES = (TEXT_DATA_TYPES + TYPED_DATA_TYPES).freeze
+  VALUELESS_FILTER_OPERATORS = %w[is_present is_not_present].freeze
+
+  def initialize(account:, user:, query:)
+    super(query.with_indifferent_access, user, account)
+  end
+
+  def perform
+    return unless valid_query?
+    return unless valid_typed_values?
+
+    validate_query_operator
+    query_builder(@filters['conversations']).count
+  rescue *MALFORMED_QUERY_ERRORS
+    nil
+  rescue ActiveRecord::StatementInvalid => e
+    raise unless database_cast_error?(e)
+
+    nil
+  end
+
+  def base_relation
+    Conversations::PermissionFilterService.new(unread_conversations, @user, @account).perform
+  end
+
+  private
+
+  def valid_query?
+    @params[:payload].is_a?(Array) && valid_query_operator_positions?
+  end
+
+  def database_cast_error?(error)
+    DATABASE_CAST_ERROR_CLASS_NAMES.include?(error.cause&.class&.name)
+  end
+
+  def valid_query_operator_positions?
+    @params[:payload].each_with_index.all? do |query_hash, index|
+      query_operator_position_valid?(query_hash[:query_operator], last_query?(index))
+    end
+  end
+
+  def query_operator_position_valid?(query_operator, last_query)
+    return query_operator.blank? if last_query
+
+    VALID_QUERY_OPERATORS.include?(query_operator.to_s.upcase)
+  end
+
+  def last_query?(index)
+    index == @params[:payload].length - 1
+  end
+
+  def valid_typed_values?
+    @params[:payload].all? do |query_hash|
+      next true if VALUELESS_FILTER_OPERATORS.include?(query_hash[:filter_operator])
+
+      data_type = validation_data_type(query_hash)
+      next true if data_type.blank?
+      next false if text_filter_operator?(query_hash) && TYPED_DATA_TYPES.include?(data_type)
+
+      valid_typed_values_for?(query_hash[:values], data_type, query_hash[:filter_operator])
+    end
+  end
+
+  def validation_data_type(query_hash)
+    attribute_key = query_hash[:attribute_key]
+    data_type = filter_data_type(query_hash)
+
+    return nil if text_search_on_display_id?(query_hash)
+    return 'number' if NUMERIC_ATTRIBUTE_KEYS.include?(attribute_key)
+    return data_type if VALIDATION_DATA_TYPES.include?(data_type)
+
+    nil
+  end
+
+  def filter_data_type(query_hash)
+    attribute_key = query_hash[:attribute_key]
+    data_type = @filters.dig('conversations', attribute_key, 'data_type')
+    return data_type.to_s.downcase if data_type.present?
+
+    custom_attribute_data_type(query_hash)
+  end
+
+  def custom_attribute_data_type(query_hash)
+    custom_attribute_type = query_hash[:custom_attribute_type].presence || self.class::ATTRIBUTE_MODEL
+    custom_attribute = @account.custom_attribute_definitions.where(
+      attribute_model: custom_attribute_type
+    ).find_by(attribute_key: query_hash[:attribute_key])
+
+    self.class::ATTRIBUTE_TYPES[custom_attribute&.attribute_display_type].to_s
+  end
+
+  def valid_typed_values_for?(values, data_type, filter_operator)
+    Array.wrap(values).all? do |value|
+      valid_typed_value?(value, data_type, filter_operator)
+    end
+  end
+
+  def text_filter_operator?(query_hash)
+    TEXT_FILTER_OPERATORS.include?(query_hash[:filter_operator])
+  end
+
+  def valid_typed_value?(value, data_type, filter_operator)
+    case data_type
+    when 'boolean'
+      BOOLEAN_VALUES.include?(value.to_s.downcase)
+    when 'date'
+      return Integer(value.to_s, exception: false).present? if filter_operator == DAYS_BEFORE_FILTER_OPERATOR
+
+      Date.iso8601(value.to_s).present?
+    when 'numeric'
+      BigDecimal(value.to_s, exception: false).present?
+    when *TEXT_DATA_TYPES
+      value.is_a?(String)
+    else
+      Integer(value.to_s, exception: false).present?
+    end
+  rescue ArgumentError
+    false
+  end
+
+  def unread_conversations
+    @account.conversations
+            .joins(:messages)
+            .merge(Message.incoming.reorder(nil))
+            .where(messages: { account_id: @account.id })
+            .where(unread_since_last_seen_condition)
+            .distinct
+  end
+
+  def unread_since_last_seen_condition
+    conversations = Conversation.arel_table
+    messages = Message.arel_table
+
+    conversations[:agent_last_seen_at].eq(nil).or(messages[:created_at].gt(conversations[:agent_last_seen_at]))
+  end
+end
diff --git a/app/services/conversations/unread_counts/filtered_count_instrumentation.rb b/app/services/conversations/unread_counts/filtered_count_instrumentation.rb
new file mode 100644
index 000000000..707c63f33
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_count_instrumentation.rb
@@ -0,0 +1,188 @@
+class Conversations::UnreadCounts::FilteredCountInstrumentation
+  # Centralizes the rollout-critical filtered unread count signals:
+  # API response duration, counter duration, snapshot build duration, snapshot state distribution,
+  # refresh claim rate, build lock acquisition rate, and invalidation/version bump rate.
+  EVENT_NAME = 'FilteredUnreadCounts'.freeze
+  METRIC_PREFIX = 'Custom/Conversations/UnreadCounts/Filtered'.freeze
+  SUMMARY_KEY = :filtered_unread_counts_request_summary
+  AGGREGATED_INCREMENT_OPERATIONS = %i[snapshot_state refresh_claim build_lock].freeze
+  SNAPSHOT_STATUSES = %i[fresh stale missing expired].freeze
+  SNAPSHOT_SCOPES = %i[built_in_filter folder_index filter].freeze
+  SUMMARY_DEFAULTS = begin
+    defaults = {
+      snapshot_total_count: 0,
+      refresh_claimed_count: 0,
+      refresh_skipped_count: 0,
+      build_lock_acquired_count: 0,
+      build_lock_missed_count: 0,
+      snapshot_build_success_count: 0,
+      snapshot_build_error_count: 0
+    }
+
+    SNAPSHOT_STATUSES.each { |status| defaults[:"snapshot_#{status}_count"] = 0 }
+    SNAPSHOT_SCOPES.each do |scope|
+      defaults[:"#{scope}_snapshot_count"] = 0
+      defaults[:"#{scope}_refresh_claimed_count"] = 0
+      defaults[:"#{scope}_refresh_skipped_count"] = 0
+      defaults[:"#{scope}_build_lock_acquired_count"] = 0
+      defaults[:"#{scope}_build_lock_missed_count"] = 0
+      defaults[:"#{scope}_snapshot_build_success_count"] = 0
+      defaults[:"#{scope}_snapshot_build_error_count"] = 0
+    end
+
+    defaults.freeze
+  end
+  private_constant :SUMMARY_KEY, :AGGREGATED_INCREMENT_OPERATIONS, :SNAPSHOT_STATUSES, :SNAPSHOT_SCOPES, :SUMMARY_DEFAULTS
+
+  class << self
+    def summarize_request(account_id:)
+      previous_summary = current_summary
+      summary = request_summary(account_id)
+      Thread.current[SUMMARY_KEY] = summary
+      started_at = monotonic_time
+      status = :success
+
+      yield
+    rescue StandardError => e
+      status = :error
+      summary[:error_class] = e.class.name
+      raise
+    ensure
+      record_request_summary(summary, status, started_at)
+      Thread.current[SUMMARY_KEY] = previous_summary
+    end
+
+    def observe(operation, attributes = {})
+      started_at = monotonic_time
+
+      yield.tap do
+        record_observation(operation, attributes, started_at, status: :success)
+      end
+    rescue StandardError => e
+      record_observation(operation, attributes.merge(error_class: e.class.name), started_at, status: :error)
+      raise
+    end
+
+    def increment(operation, attributes = {})
+      record_increment_summary(operation, attributes) if aggregated_increment?(operation)
+      record_event(operation, attributes) unless aggregated_increment?(operation)
+      record_metric("#{metric_name(operation)}/count", 1)
+    end
+
+    def record_event(operation, attributes = {})
+      agent = new_relic_agent
+      return unless agent.respond_to?(:record_custom_event)
+
+      agent.record_custom_event(EVENT_NAME, sanitized_attributes(attributes.merge(operation: operation)))
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def record_observation(operation, attributes, started_at, status:)
+      duration_ms = elapsed_ms_since(started_at)
+      record_observation_summary(operation, attributes, status: status)
+      record_metric("#{metric_name(operation)}/duration_ms", duration_ms)
+    end
+
+    def record_request_summary(summary, status, started_at)
+      duration_ms = elapsed_ms_since(started_at)
+      summary[:status] = status
+      summary[:duration_ms] = duration_ms
+      record_metric("#{metric_name(:api_response)}/duration_ms", duration_ms)
+      record_event(:request_summary, summary)
+    end
+
+    def record_metric(name, value)
+      agent = new_relic_agent
+      return unless agent.respond_to?(:record_metric)
+
+      agent.record_metric(name, value)
+    rescue StandardError
+      nil
+    end
+
+    def metric_name(operation)
+      "#{METRIC_PREFIX}/#{operation}"
+    end
+
+    def request_summary(account_id)
+      SUMMARY_DEFAULTS.dup.merge(account_id: account_id)
+    end
+
+    def current_summary
+      Thread.current[SUMMARY_KEY]
+    end
+
+    def aggregated_increment?(operation)
+      operation.in?(AGGREGATED_INCREMENT_OPERATIONS)
+    end
+
+    def record_increment_summary(operation, attributes)
+      case operation
+      when :snapshot_state
+        record_snapshot_state_summary(attributes)
+      when :refresh_claim
+        result = attributes[:claimed] ? :claimed : :skipped
+        increment_summary_count(:"refresh_#{result}_count")
+        increment_scoped_summary_count(attributes[:snapshot_scope], :"refresh_#{result}_count")
+      when :build_lock
+        result = attributes[:acquired] ? :acquired : :missed
+        increment_summary_count(:"build_lock_#{result}_count")
+        increment_scoped_summary_count(attributes[:snapshot_scope], :"build_lock_#{result}_count")
+      end
+    end
+
+    def record_snapshot_state_summary(attributes)
+      increment_summary_count(:snapshot_total_count)
+      increment_summary_count(:"snapshot_#{attributes[:snapshot_status]}_count")
+      increment_scoped_summary_count(attributes[:snapshot_scope], :snapshot_count)
+    end
+
+    def record_observation_summary(operation, attributes, status:)
+      return unless operation == :snapshot_build
+
+      result = status == :success ? :success : :error
+      increment_summary_count(:"snapshot_build_#{result}_count")
+      increment_scoped_summary_count(attributes[:snapshot_scope], :"snapshot_build_#{result}_count")
+    end
+
+    def increment_scoped_summary_count(scope, suffix)
+      return if scope.blank?
+
+      increment_summary_count(:"#{scope}_#{suffix}")
+    end
+
+    def increment_summary_count(key)
+      return if current_summary.blank?
+
+      current_summary[key] = current_summary.fetch(key, 0) + 1
+    end
+
+    def sanitized_attributes(attributes)
+      attributes.compact.transform_values do |value|
+        case value
+        when String, Integer, Float, TrueClass, FalseClass
+          value
+        else
+          value.to_s
+        end
+      end
+    end
+
+    def elapsed_ms_since(started_at)
+      ((monotonic_time - started_at) * 1000).round(2)
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def new_relic_agent
+      return unless defined?(::NewRelic::Agent)
+
+      ::NewRelic::Agent
+    end
+  end
+end
diff --git a/app/services/conversations/unread_counts/filtered_count_invalidator.rb b/app/services/conversations/unread_counts/filtered_count_invalidator.rb
new file mode 100644
index 000000000..6546bb58f
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_count_invalidator.rb
@@ -0,0 +1,184 @@
+class Conversations::UnreadCounts::FilteredCountInvalidator
+  FEATURE_FLAG = 'unread_count_for_filters'.freeze
+
+  attr_reader :account
+
+  def initialize(account)
+    @account = account
+  end
+
+  def conversation_changed!
+    return false unless enabled?
+
+    version = store.bump_conversation_version!(account.id)
+    record_invalidation(:conversation, reason: :conversation_changed, version: version)
+    true
+  end
+
+  def user_visibility_changed!(user_id:)
+    return false unless enabled? && user_id.present?
+
+    version = store.bump_built_in_filter_version!(account_id: account.id, user_id: user_id)
+    record_invalidation(:built_in_filter, reason: :user_visibility_changed, version: version)
+    true
+  end
+
+  def users_visibility_changed!(user_ids:)
+    return false unless enabled?
+
+    user_ids = Array(user_ids).compact_blank.uniq
+    return false if user_ids.blank?
+
+    bump_built_in_filter_versions(user_ids).each_value do |version|
+      record_invalidation(:built_in_filter, reason: :user_visibility_changed, version: version)
+    end
+    true
+  end
+
+  def custom_filter_created!(custom_filter)
+    return false unless conversation_filter?(custom_filter)
+
+    bump_folder_index_version!(custom_filter, reason: :custom_filter_created)
+    bump_filter_version!(custom_filter, reason: :custom_filter_created)
+    true
+  end
+
+  def custom_filter_updated!(custom_filter)
+    return false unless enabled? && conversation_filter_before_or_after?(custom_filter)
+
+    filter_type_changed = filter_type_changed?(custom_filter)
+    query_changed = query_changed?(custom_filter)
+    return false unless filter_type_changed || query_changed
+
+    bump_folder_index_version!(custom_filter, reason: :custom_filter_updated) if filter_type_changed
+    bump_filter_version!(custom_filter, reason: :custom_filter_updated)
+    store.delete_filter_count!(account_id: account.id, filter_id: custom_filter.id) if moved_out_of_conversation_filters?(custom_filter)
+    true
+  end
+
+  def custom_filter_destroyed!(custom_filter)
+    return false unless conversation_filter?(custom_filter)
+
+    bump_folder_index_version!(custom_filter, reason: :custom_filter_destroyed)
+    store.delete_filter_count!(account_id: account.id, filter_id: custom_filter.id)
+    true
+  end
+
+  def custom_attribute_definition_changed!(custom_attribute_definition)
+    return false unless enabled? && conversation_attribute_before_or_after?(custom_attribute_definition)
+
+    affected_filters = affected_custom_attribute_filters(custom_attribute_definition)
+    return false if affected_filters.blank?
+
+    affected_filters.each { |custom_filter| bump_filter_version!(custom_filter, reason: :custom_attribute_definition_changed) }
+    true
+  end
+
+  private
+
+  def bump_built_in_filter_versions(user_ids)
+    results = Redis::Alfred.pipelined do |pipeline|
+      user_ids.each do |user_id|
+        key = store.built_in_filter_version_key(account.id, user_id)
+        pipeline.incr(key)
+        pipeline.expire(key, Conversations::UnreadCounts::FILTERED_COUNT_VERSION_TTL)
+      end
+    end
+
+    user_ids.zip(results.each_slice(2).map(&:first)).to_h
+  end
+
+  def enabled?
+    account&.feature_enabled?(FEATURE_FLAG)
+  end
+
+  def conversation_filter?(custom_filter)
+    enabled? && custom_filter.conversation?
+  end
+
+  def conversation_filter_before_or_after?(custom_filter)
+    custom_filter.conversation? || previous_filter_type(custom_filter) == 'conversation'
+  end
+
+  def moved_out_of_conversation_filters?(custom_filter)
+    filter_type_changed?(custom_filter) && previous_filter_type(custom_filter) == 'conversation' && !custom_filter.conversation?
+  end
+
+  def filter_type_changed?(custom_filter)
+    custom_filter.previous_changes.key?('filter_type')
+  end
+
+  def query_changed?(custom_filter)
+    custom_filter.previous_changes.key?('query')
+  end
+
+  def previous_filter_type(custom_filter)
+    raw_filter_type = custom_filter.previous_changes.dig('filter_type', 0)
+    return if raw_filter_type.blank?
+    return raw_filter_type if CustomFilter.filter_types.key?(raw_filter_type)
+    return CustomFilter.filter_types.key(raw_filter_type) if raw_filter_type.is_a?(Integer)
+
+    CustomFilter.filter_types.key(raw_filter_type.to_i) || raw_filter_type.to_s
+  end
+
+  def conversation_attribute_before_or_after?(custom_attribute_definition)
+    custom_attribute_definition.conversation_attribute? || previous_attribute_model(custom_attribute_definition) == 'conversation_attribute'
+  end
+
+  def previous_attribute_model(custom_attribute_definition)
+    raw_attribute_model = custom_attribute_definition.previous_changes.dig('attribute_model', 0)
+    return if raw_attribute_model.blank?
+    return raw_attribute_model if CustomAttributeDefinition.attribute_models.key?(raw_attribute_model)
+    return CustomAttributeDefinition.attribute_models.key(raw_attribute_model) if raw_attribute_model.is_a?(Integer)
+
+    CustomAttributeDefinition.attribute_models.key(raw_attribute_model.to_i) || raw_attribute_model.to_s
+  end
+
+  def affected_custom_attribute_filters(custom_attribute_definition)
+    attribute_keys = custom_attribute_keys(custom_attribute_definition)
+    account.custom_filters.conversation.select do |custom_filter|
+      custom_filter_references_conversation_attribute?(custom_filter, attribute_keys)
+    end
+  end
+
+  def custom_attribute_keys(custom_attribute_definition)
+    [custom_attribute_definition.attribute_key, custom_attribute_definition.previous_changes.dig('attribute_key', 0)].compact_blank.map(&:to_s).uniq
+  end
+
+  def custom_filter_references_conversation_attribute?(custom_filter, attribute_keys)
+    payload = custom_filter.query.with_indifferent_access[:payload]
+    Array(payload).any? do |condition|
+      condition = condition.with_indifferent_access
+      condition[:attribute_key].to_s.in?(attribute_keys) &&
+        (condition[:custom_attribute_type].presence || 'conversation_attribute') == 'conversation_attribute'
+    end
+  end
+
+  def bump_folder_index_version!(custom_filter, reason:)
+    version = store.bump_folder_index_version!(account_id: account.id, user_id: custom_filter.user_id)
+    record_invalidation(:folder_index, reason: reason, version: version)
+  end
+
+  def bump_filter_version!(custom_filter, reason:)
+    version = store.bump_filter_version!(account_id: account.id, filter_id: custom_filter.id)
+    record_invalidation(:filter, reason: reason, version: version)
+  end
+
+  def record_invalidation(scope, reason:, version:)
+    instrumentation.increment(
+      :invalidation,
+      account_id: account.id,
+      invalidation_scope: scope,
+      reason: reason,
+      version: version
+    )
+  end
+
+  def store
+    ::Conversations::UnreadCounts::FilteredCountStore
+  end
+
+  def instrumentation
+    ::Conversations::UnreadCounts::FilteredCountInstrumentation
+  end
+end
diff --git a/app/services/conversations/unread_counts/filtered_count_snapshot_resolver.rb b/app/services/conversations/unread_counts/filtered_count_snapshot_resolver.rb
new file mode 100644
index 000000000..8685aa891
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_count_snapshot_resolver.rb
@@ -0,0 +1,67 @@
+class Conversations::UnreadCounts::FilteredCountSnapshotResolver
+  BUILD_LOCK_TTL = 15.minutes.to_i
+
+  attr_reader :account, :now, :store, :lock_manager
+
+  def initialize(account:, now:, store:, lock_manager:)
+    @account = account
+    @now = now
+    @store = store
+    @lock_manager = lock_manager
+  end
+
+  # Version mismatches make a snapshot stale immediately, but refresh_after keeps DB rebuilds throttled.
+  def resolve(scope:, state:, lock_key:, claim_refresh:, &)
+    record_snapshot_state(scope, state)
+    return state.payload if state.fresh?
+
+    stale_payload = state.payload if state.stale?
+    return stale_payload if refresh_not_due?(stale_payload)
+    return stale_payload unless refresh_claimed?(scope, claim_refresh)
+
+    build_with_lock(scope, lock_key, stale_payload, &)
+  end
+
+  private
+
+  def record_snapshot_state(scope, state)
+    instrumentation.increment(
+      :snapshot_state,
+      account_id: account.id,
+      snapshot_scope: scope,
+      snapshot_status: state.status
+    )
+  end
+
+  def refresh_not_due?(stale_payload)
+    stale_payload.present? && !store.refresh_due?(stale_payload, now: now)
+  end
+
+  def refresh_claimed?(scope, claim_refresh)
+    claimed = claim_refresh.call
+    instrumentation.increment(:refresh_claim, account_id: account.id, snapshot_scope: scope, claimed: claimed)
+    claimed
+  end
+
+  def build_with_lock(scope, lock_key, stale_payload, &)
+    built_payload = nil
+    lock_acquired = false
+
+    begin
+      lock_manager.with_lock(lock_key, BUILD_LOCK_TTL) do
+        lock_acquired = true
+        built_payload = instrumentation.observe(:snapshot_build, account_id: account.id, snapshot_scope: scope, &)
+      rescue ActiveRecord::StatementInvalid
+        built_payload = stale_payload
+      end
+    ensure
+      instrumentation.increment(:build_lock, account_id: account.id, snapshot_scope: scope, acquired: lock_acquired)
+    end
+
+    lock_acquired ? built_payload : stale_payload
+  end
+
+  def instrumentation
+    ::Conversations::UnreadCounts::FilteredCountInstrumentation
+  end
+end
diff --git a/app/services/conversations/unread_counts/filtered_count_store.rb b/app/services/conversations/unread_counts/filtered_count_store.rb
new file mode 100644
index 000000000..b88e01627
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_count_store.rb
@@ -0,0 +1,214 @@
+class Conversations::UnreadCounts::FilteredCountStore
+  extend Conversations::UnreadCounts::FilteredCountStoreKeys
+
+  SnapshotResult = Struct.new(:status, :payload, keyword_init: true) do
+    def fresh? = status == :fresh
+    def stale? = status == :stale
+    def expired? = status == :expired
+    def missing? = status == :missing
+  end
+
+  VERSION_KEY_METHODS = {
+    conversation: :conversation_version_key,
+    built_in_filter: :built_in_filter_version_key,
+    folder_index: :folder_index_version_key,
+    filter: :filter_version_key
+  }.freeze
+  REFRESH_THROTTLE_KEY_METHODS = {
+    built_in_filter: :built_in_filter_refresh_throttle_key,
+    folder_index: :folder_index_refresh_throttle_key,
+    filter: :filter_refresh_throttle_key
+  }.freeze
+  private_constant :VERSION_KEY_METHODS, :REFRESH_THROTTLE_KEY_METHODS
+
+  class << self
+    def conversation_version(account_id) = current_version_for(:conversation, account_id)
+    def built_in_filter_version(account_id:, user_id:) = current_version_for(:built_in_filter, account_id, user_id)
+    def folder_index_version(account_id:, user_id:) = current_version_for(:folder_index, account_id, user_id)
+    def filter_version(account_id:, filter_id:) = current_version_for(:filter, account_id, filter_id)
+
+    def bump_conversation_version!(account_id) = bump_version_for!(:conversation, account_id)
+    def bump_built_in_filter_version!(account_id:, user_id:) = bump_version_for!(:built_in_filter, account_id, user_id)
+    def bump_folder_index_version!(account_id:, user_id:) = bump_version_for!(:folder_index, account_id, user_id)
+    def bump_filter_version!(account_id:, filter_id:) = bump_version_for!(:filter, account_id, filter_id)
+
+    # Keep version dimensions explicit so callers cannot write a snapshot without the freshness contract it depends on.
+    def write_built_in_filter_counts!(account_id:, user_id:, counts:, account_version:, built_in_filter_version:, built_at: Time.current, meta: {}) # rubocop:disable Metrics/ParameterLists
+      payload = snapshot_payload(built_at).merge(
+        account_version: account_version,
+        built_in_filter_version: built_in_filter_version,
+        user_id: user_id,
+        counts: counts,
+        meta: meta
+      )
+      write_snapshot(built_in_filter_counts_key(account_id, user_id), payload)
+    end
+
+    def built_in_filter_counts(account_id:, user_id:)
+      read_snapshot(built_in_filter_counts_key(account_id, user_id))
+    end
+
+    def built_in_filter_counts_state(account_id:, user_id:, versions: nil, now: Time.current)
+      snapshot_state(
+        built_in_filter_counts(account_id: account_id, user_id: user_id),
+        versions: versions || {
+          account_version: conversation_version(account_id),
+          built_in_filter_version: built_in_filter_version(account_id: account_id, user_id: user_id)
+        },
+        now: now
+      )
+    end
+
+    def write_folder_index!(account_id:, user_id:, filter_ids:, folder_index_version:, built_at: Time.current)
+      payload = snapshot_payload(built_at).merge(
+        folder_index_version: folder_index_version,
+        user_id: user_id,
+        filter_ids: Array(filter_ids).map(&:to_i)
+      )
+      write_snapshot(folder_index_key(account_id, user_id), payload)
+    end
+
+    def folder_index(account_id:, user_id:)
+      read_snapshot(folder_index_key(account_id, user_id))
+    end
+
+    def folder_index_state(account_id:, user_id:, versions: nil, now: Time.current)
+      snapshot_state(
+        folder_index(account_id: account_id, user_id: user_id),
+        versions: versions || { folder_index_version: folder_index_version(account_id: account_id, user_id: user_id) },
+        now: now
+      )
+    end
+
+    # Saved folder snapshots depend on account, filter, and owner visibility versions; keep all three visible at the callsite.
+    def write_filter_count!(account_id:, filter_id:, user_id:, count:, account_version:, filter_version:, owner_built_in_filter_version:, # rubocop:disable Metrics/ParameterLists
+                            built_at: Time.current, meta: {})
+      payload = snapshot_payload(built_at).merge(
+        account_version: account_version,
+        filter_version: filter_version,
+        owner_built_in_filter_version: owner_built_in_filter_version,
+        filter_id: filter_id,
+        user_id: user_id,
+        count: count,
+        meta: meta
+      )
+      write_snapshot(filter_count_key(account_id, filter_id), payload)
+    end
+
+    def filter_count(account_id:, filter_id:)
+      read_snapshot(filter_count_key(account_id, filter_id))
+    end
+
+    def filter_count_state(account_id:, filter_id:, owner_user_id: nil, versions: nil, now: Time.current)
+      snapshot = filter_count(account_id: account_id, filter_id: filter_id)
+      return SnapshotResult.new(status: :missing, payload: nil) if snapshot.blank?
+
+      owner_user_id ||= snapshot[:user_id]
+      snapshot_state(
+        snapshot,
+        versions: versions || {
+          account_version: conversation_version(account_id),
+          filter_version: filter_version(account_id: account_id, filter_id: filter_id),
+          owner_built_in_filter_version: built_in_filter_version(account_id: account_id, user_id: owner_user_id)
+        },
+        now: now
+      )
+    end
+
+    def refresh_due?(snapshot, now: Time.current)
+      return true if snapshot.blank?
+
+      refresh_after = parse_time(snapshot[:refresh_after])
+      refresh_after.blank? || now >= refresh_after
+    end
+
+    def claim_built_in_filter_refresh!(account_id:, user_id:) = claim_refresh_for!(:built_in_filter, account_id, user_id)
+    def claim_folder_index_refresh!(account_id:, user_id:) = claim_refresh_for!(:folder_index, account_id, user_id)
+    def claim_filter_refresh!(account_id:, filter_id:) = claim_refresh_for!(:filter, account_id, filter_id)
+
+    def delete_filter_count!(account_id:, filter_id:)
+      Redis::Alfred.delete(filter_count_key(account_id, filter_id))
+    end
+
+    private
+
+    # Keep the public API domain-specific while centralizing direct Redis version/throttle operations.
+    def current_version_for(scope, *key_args)
+      current_version(public_send(VERSION_KEY_METHODS.fetch(scope), *key_args))
+    end
+
+    def bump_version_for!(scope, *key_args)
+      key = public_send(VERSION_KEY_METHODS.fetch(scope), *key_args)
+
+      Redis::Alfred.with do |conn|
+        conn.multi do |transaction|
+          transaction.incr(key)
+          transaction.expire(key, Conversations::UnreadCounts::FILTERED_COUNT_VERSION_TTL)
+        end.first
+      end
+    end
+
+    def claim_refresh_for!(scope, *key_args)
+      claim_refresh_throttle(public_send(REFRESH_THROTTLE_KEY_METHODS.fetch(scope), *key_args))
+    end
+
+    def current_version(key)
+      Redis::Alfred.get(key).to_i
+    end
+
+    def snapshot_payload(built_at)
+      # expires_at marks the end of the fresh window. Redis keeps the snapshot for the additional stale window.
+      {
+        built_at: built_at.iso8601,
+        refresh_after: (built_at + Conversations::UnreadCounts::FILTERED_COUNT_MIN_REFRESH_INTERVAL).iso8601,
+        expires_at: (built_at + Conversations::UnreadCounts::FILTERED_COUNT_FRESH_TTL).iso8601
+      }
+    end
+
+    def write_snapshot(key, payload)
+      Redis::Alfred.setex(key, JSON.generate(payload), Conversations::UnreadCounts::FILTERED_COUNT_REDIS_TTL)
+    end
+
+    def read_snapshot(key)
+      value = Redis::Alfred.get(key)
+      return if value.blank?
+
+      JSON.parse(value, symbolize_names: true)
+    end
+
+    def snapshot_state(snapshot, versions:, now:)
+      return SnapshotResult.new(status: :missing, payload: nil) if snapshot.blank?
+      return SnapshotResult.new(status: :expired, payload: snapshot) unless inside_stale_window?(snapshot, now)
+      return SnapshotResult.new(status: :fresh, payload: snapshot) if versions_match?(snapshot, versions) && inside_fresh_window?(snapshot, now)
+
+      SnapshotResult.new(status: :stale, payload: snapshot)
+    end
+
+    def versions_match?(snapshot, versions)
+      versions.all? { |key, value| snapshot[key].to_i == value.to_i }
+    end
+
+    def inside_fresh_window?(snapshot, now)
+      expires_at = parse_time(snapshot[:expires_at])
+      expires_at.present? && now <= expires_at
+    end
+
+    def inside_stale_window?(snapshot, now)
+      expires_at = parse_time(snapshot[:expires_at])
+      expires_at.present? && now <= expires_at + Conversations::UnreadCounts::FILTERED_COUNT_STALE_WINDOW
+    end
+
+    def parse_time(value)
+      return value if value.is_a?(Time) || value.is_a?(ActiveSupport::TimeWithZone)
+      return value.to_time if value.respond_to?(:to_time) && !value.is_a?(String)
+
+      Time.zone.parse(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def claim_refresh_throttle(key)
+      Redis::Alfred.set(key, Time.current.to_i, nx: true, ex: Conversations::UnreadCounts::FILTERED_COUNT_MIN_REFRESH_INTERVAL) ? true : false
+    end
+  end
+end
diff --git a/app/services/conversations/unread_counts/filtered_count_store_keys.rb b/app/services/conversations/unread_counts/filtered_count_store_keys.rb
new file mode 100644
index 000000000..5072503eb
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_count_store_keys.rb
@@ -0,0 +1,67 @@
+module Conversations::UnreadCounts::FilteredCountStoreKeys
+  def conversation_version_key(account_id)
+    account_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_CONVERSATION_VERSION, account_id)
+  end
+
+  def built_in_filter_version_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_VERSION, account_id, user_id)
+  end
+
+  def built_in_filter_counts_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_COUNTS, account_id, user_id)
+  end
+
+  def built_in_filter_build_lock_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_BUILD_LOCK, account_id, user_id)
+  end
+
+  def built_in_filter_refresh_throttle_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_REFRESH_THROTTLE, account_id, user_id)
+  end
+
+  def folder_index_version_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FOLDER_INDEX_VERSION, account_id, user_id)
+  end
+
+  def folder_index_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FOLDER_INDEX, account_id, user_id)
+  end
+
+  def folder_index_build_lock_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FOLDER_INDEX_BUILD_LOCK, account_id, user_id)
+  end
+
+  def folder_index_refresh_throttle_key(account_id, user_id)
+    user_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FOLDER_INDEX_REFRESH_THROTTLE, account_id, user_id)
+  end
+
+  def filter_version_key(account_id, filter_id)
+    filter_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FILTER_VERSION, account_id, filter_id)
+  end
+
+  def filter_count_key(account_id, filter_id)
+    filter_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FILTER_COUNT, account_id, filter_id)
+  end
+
+  def filter_build_lock_key(account_id, filter_id)
+    filter_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FILTER_BUILD_LOCK, account_id, filter_id)
+  end
+
+  def filter_refresh_throttle_key(account_id, filter_id)
+    filter_key(Redis::Alfred::UNREAD_CONVERSATIONS_V2_FILTER_REFRESH_THROTTLE, account_id, filter_id)
+  end
+
+  private
+
+  def account_key(format_string, account_id)
+    format(format_string, account_id: account_id)
+  end
+
+  def user_key(format_string, account_id, user_id)
+    format(format_string, account_id: account_id, user_id: user_id)
+  end
+
+  def filter_key(format_string, account_id, filter_id)
+    format(format_string, account_id: account_id, filter_id: filter_id)
+  end
+end
diff --git a/app/services/conversations/unread_counts/filtered_count_version_cache.rb b/app/services/conversations/unread_counts/filtered_count_version_cache.rb
new file mode 100644
index 000000000..5aa73269a
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_count_version_cache.rb
@@ -0,0 +1,29 @@
+class Conversations::UnreadCounts::FilteredCountVersionCache
+  attr_reader :account, :user, :store
+
+  def initialize(account:, user:, store:)
+    @account = account
+    @user = user
+    @store = store
+  end
+
+  def built_in_filter = { account_version: account_version, built_in_filter_version: built_in_filter_version }
+
+  def folder_index = { folder_index_version: store.folder_index_version(account_id: account.id, user_id: user.id) }
+
+  def filter(filter_id)
+    {
+      account_version: account_version,
+      filter_version: filter_version(filter_id),
+      owner_built_in_filter_version: built_in_filter_version
+    }
+  end
+
+  private
+
+  def account_version = @account_version ||= store.conversation_version(account.id)
+
+  def built_in_filter_version = @built_in_filter_version ||= store.built_in_filter_version(account_id: account.id, user_id: user.id)
+
+  def filter_version(filter_id) = (@filter_versions ||= {})[filter_id] ||= store.filter_version(account_id: account.id, filter_id: filter_id)
+end
diff --git a/app/services/conversations/unread_counts/filtered_counter.rb b/app/services/conversations/unread_counts/filtered_counter.rb
new file mode 100644
index 000000000..1194951b6
--- /dev/null
+++ b/app/services/conversations/unread_counts/filtered_counter.rb
@@ -0,0 +1,216 @@
+class Conversations::UnreadCounts::FilteredCounter
+  FEATURE_FLAG = 'unread_count_for_filters'.freeze
+  EMPTY_COUNTS = {
+    mentions_count: 0,
+    participating_count: 0,
+    unattended_count: 0,
+    folders: {}
+  }.freeze
+
+  attr_reader :account, :user, :now
+
+  def self.empty_counts = EMPTY_COUNTS.deep_dup
+
+  def initialize(account:, user:, now: Time.current)
+    @account = account
+    @user = user
+    @now = now
+  end
+
+  def perform = instrumentation.observe(:counter_perform, account_id: account.id) { built_in_counts.merge(folders: folder_counts) }
+
+  private
+
+  def built_in_counts = counts_from_built_in_snapshot(built_in_counts_snapshot) || self.class.empty_counts.except(:folders)
+
+  def built_in_counts_snapshot
+    versions = version_cache.built_in_filter
+    snapshot_or_build(
+      scope: :built_in_filter,
+      state: store.built_in_filter_counts_state(account_id: account.id, user_id: user.id, versions: versions, now: now),
+      lock_key: store.built_in_filter_build_lock_key(account.id, user.id),
+      claim_refresh: -> { store.claim_built_in_filter_refresh!(account_id: account.id, user_id: user.id) }
+    ) { build_built_in_counts!(versions) }
+  end
+
+  def counts_from_built_in_snapshot(snapshot) = snapshot&.fetch(:counts, nil)&.slice(:mentions_count, :participating_count, :unattended_count)
+
+  def folder_counts
+    folder_index = folder_index_snapshot
+    return {} if folder_index.blank?
+
+    @inline_filter_builds = 0
+    folder_index[:filter_ids].each_with_object({}) do |filter_id, counts|
+      count = filter_count(filter_id)
+      counts[filter_id.to_s] = count if count.to_i.positive?
+    end
+  end
+
+  def folder_index_snapshot
+    versions = version_cache.folder_index
+    snapshot_or_build(
+      scope: :folder_index,
+      state: store.folder_index_state(account_id: account.id, user_id: user.id, versions: versions, now: now),
+      lock_key: store.folder_index_build_lock_key(account.id, user.id),
+      claim_refresh: -> { store.claim_folder_index_refresh!(account_id: account.id, user_id: user.id) }
+    ) { build_folder_index!(versions) }
+  end
+
+  def filter_count(filter_id)
+    versions = version_cache.filter(filter_id)
+    snapshot = snapshot_or_build(
+      scope: :filter,
+      state: store.filter_count_state(account_id: account.id, filter_id: filter_id, owner_user_id: user.id, versions: versions, now: now),
+      lock_key: store.filter_build_lock_key(account.id, filter_id),
+      claim_refresh: -> { filter_build_available? && store.claim_filter_refresh!(account_id: account.id, filter_id: filter_id) }
+    ) do
+      track_filter_build!
+      build_filter_count!(filter_id, versions)
+    end
+
+    snapshot&.fetch(:count, nil)
+  end
+
+  def snapshot_or_build(scope:, state:, lock_key:, claim_refresh:, &)
+    snapshot_resolver.resolve(scope: scope, state: state, lock_key: lock_key, claim_refresh: claim_refresh, &)
+  end
+
+  def filter_build_available? = @inline_filter_builds.to_i < Conversations::UnreadCounts::MAX_INLINE_FILTER_BUILDS
+
+  def track_filter_build! = @inline_filter_builds = @inline_filter_builds.to_i + 1
+
+  def build_built_in_counts!(versions)
+    store.write_built_in_filter_counts!(**built_in_count_snapshot_payload(versions))
+    store.built_in_filter_counts(account_id: account.id, user_id: user.id)
+  end
+
+  def built_in_count_snapshot_payload(versions)
+    {
+      account_id: account.id,
+      user_id: user.id,
+      counts: built_in_counts_from_database,
+      account_version: versions.fetch(:account_version),
+      built_in_filter_version: versions.fetch(:built_in_filter_version),
+      built_at: now
+    }
+  end
+
+  def built_in_counts_from_database
+    {
+      mentions_count: count_relation(mentioned_unread_conversations),
+      participating_count: count_relation(participating_unread_conversations),
+      unattended_count: count_relation(unread_open_accessible_conversations.unattended)
+    }
+  end
+
+  def mentioned_unread_conversations
+    unread_open_accessible_conversations
+      .joins(:mentions)
+      .where(mentions: { account_id: account.id, user_id: user.id })
+  end
+
+  def participating_unread_conversations
+    unread_open_accessible_conversations
+      .joins(:conversation_participants)
+      .where(conversation_participants: { user_id: user.id })
+  end
+
+  def build_folder_index!(versions)
+    store.write_folder_index!(
+      account_id: account.id,
+      user_id: user.id,
+      filter_ids: folder_filter_ids_from_database,
+      folder_index_version: versions.fetch(:folder_index_version),
+      built_at: now
+    )
+    store.folder_index(account_id: account.id, user_id: user.id)
+  end
+
+  def folder_filter_ids_from_database = account.custom_filters.where(user_id: user.id, filter_type: :conversation).pluck(:id)
+
+  def build_filter_count!(filter_id, versions)
+    custom_filter = account.custom_filters.find_by(id: filter_id, user_id: user.id, filter_type: :conversation)
+    return delete_filter_count!(filter_id) if custom_filter.blank?
+
+    count = filter_query_count(custom_filter)
+    return delete_filter_count!(filter_id) if count.nil?
+
+    write_filter_count!(filter_id, count, versions)
+    store.filter_count(account_id: account.id, filter_id: filter_id)
+  rescue CustomExceptions::CustomFilter::InvalidAttribute,
+         CustomExceptions::CustomFilter::InvalidOperator,
+         CustomExceptions::CustomFilter::InvalidQueryOperator,
+         CustomExceptions::CustomFilter::InvalidValue
+    delete_filter_count!(filter_id)
+  end
+
+  def filter_query_count(custom_filter)
+    ::Conversations::UnreadCounts::FilterQueryCounter.new(
+      account: account,
+      user: user,
+      query: custom_filter.query
+    ).perform
+  end
+
+  def write_filter_count!(filter_id, count, versions)
+    store.write_filter_count!(
+      account_id: account.id,
+      filter_id: filter_id,
+      user_id: user.id,
+      count: count,
+      account_version: versions.fetch(:account_version),
+      filter_version: versions.fetch(:filter_version),
+      owner_built_in_filter_version: versions.fetch(:owner_built_in_filter_version),
+      built_at: now
+    )
+  end
+
+  def version_cache = @version_cache ||= ::Conversations::UnreadCounts::FilteredCountVersionCache.new(account: account, user: user, store: store)
+
+  def delete_filter_count!(filter_id) = store.delete_filter_count!(account_id: account.id, filter_id: filter_id).then { nil }
+
+  def unread_open_accessible_conversations
+    @unread_open_accessible_conversations ||= Conversations::PermissionFilterService.new(
+      unread_conversations.open,
+      user,
+      account
+    ).perform
+  end
+
+  def unread_conversations
+    account.conversations
+           .joins(:messages)
+           .merge(Message.incoming.reorder(nil))
+           .where(messages: { account_id: account.id })
+           .where(unread_since_last_seen_condition)
+           .distinct
+  end
+
+  def unread_since_last_seen_condition
+    conversations = Conversation.arel_table
+    messages = Message.arel_table
+
+    conversations[:agent_last_seen_at].eq(nil).or(messages[:created_at].gt(conversations[:agent_last_seen_at]))
+  end
+
+  def count_relation(relation) = relation.unscope(:order).count
+
+  def lock_manager = @lock_manager ||= Redis::LockManager.new
+
+  def snapshot_resolver
+    @snapshot_resolver ||= ::Conversations::UnreadCounts::FilteredCountSnapshotResolver.new(
+      account: account,
+      now: now,
+      store: store,
+      lock_manager: lock_manager
+    )
+  end
+
+  def store
+    ::Conversations::UnreadCounts::FilteredCountStore
+  end
+
+  def instrumentation
+    ::Conversations::UnreadCounts::FilteredCountInstrumentation
+  end
+end
diff --git a/app/services/conversations/unread_counts/listener.rb b/app/services/conversations/unread_counts/listener.rb
index 28792d884..59f15f5bc 100644
--- a/app/services/conversations/unread_counts/listener.rb
+++ b/app/services/conversations/unread_counts/listener.rb
@@ -1,34 +1,59 @@
 class Conversations::UnreadCounts::Listener < BaseListener
   include Events::Types
 
+  FILTERED_CONVERSATION_UPDATE_KEYS = %w[
+    additional_attributes cached_label_list campaign_id custom_attributes first_reply_created_at label_list last_activity_at priority snoozed_until
+    waiting_since
+  ].freeze
+  private_constant :FILTERED_CONVERSATION_UPDATE_KEYS
+
   def message_created(event)
     message, = extract_message_and_account(event)
-    return unless message.incoming?
-    return unless message.account.feature_enabled?('conversation_unread_counts')
+    account = message.account
+    return unless account.feature_enabled?('conversation_unread_counts') || account.feature_enabled?(filtered_count_feature_flag)
 
-    refresh(message.conversation)
+    conversation = message.conversation
+    refreshed = refresh(conversation) if message.incoming? && account.feature_enabled?('conversation_unread_counts')
+
+    invalidate_filtered_conversation(conversation)
+
+    notify_filtered_count_change(conversation) unless message.incoming? && refreshed
   end
 
   def conversation_status_changed(event)
     conversation, = extract_conversation_and_account(event)
-    refresh(conversation, event.data[:changed_attributes])
+    refresh_then_invalidate(conversation, event.data[:changed_attributes])
   end
 
   def conversation_updated(event)
-    return unless label_changed?(event.data[:changed_attributes])
-
     conversation, = extract_conversation_and_account(event)
-    refresh(conversation, event.data[:changed_attributes])
+    changed_attributes = event.data[:changed_attributes]
+    notify_filtered_count_change(conversation) if filtered_conversation_update_changed?(changed_attributes) && !label_changed?(changed_attributes)
+    return unless label_changed?(changed_attributes)
+
+    refresh(conversation, changed_attributes)
+  end
+
+  def conversation_contact_changed(event)
+    conversation, = extract_conversation_and_account(event)
+    invalidate_filtered_conversation(conversation)
+    notify_filtered_count_change(conversation)
   end
 
   def assignee_changed(event)
     conversation, = extract_conversation_and_account(event)
-    refresh(conversation, event.data[:changed_attributes])
+    refresh_then_invalidate(conversation, event.data[:changed_attributes])
   end
 
   def team_changed(event)
     conversation, = extract_conversation_and_account(event)
-    refresh(conversation, event.data[:changed_attributes])
+    refresh_then_invalidate(conversation, event.data[:changed_attributes])
+  end
+
+  def conversation_mentioned(event)
+    conversation, = extract_conversation_and_account(event)
+    user = event.data[:user]
+    filtered_count_invalidator(conversation.account).user_visibility_changed!(user_id: user&.id)
   end
 
   def conversation_deleted(event)
@@ -36,14 +61,23 @@ class Conversations::UnreadCounts::Listener < BaseListener
     return if conversation_data.blank?
 
     account = Account.find_by(id: conversation_data[:account_id])
-    return unless account&.feature_enabled?('conversation_unread_counts')
-    return unless remove_deleted_conversation(account, conversation_data)
+    return if account.blank?
+
+    removed = account.feature_enabled?('conversation_unread_counts') && remove_deleted_conversation(account, conversation_data)
+    filtered_count_invalidator(account).conversation_changed!
+    return notify_deleted_filtered_count_change(account, conversation_data) unless removed
 
     Rails.configuration.dispatcher.dispatch(CONVERSATION_UNREAD_COUNT_CHANGED, Time.zone.now, conversation_data: conversation_data.to_h)
   end
 
   private
 
+  def refresh_then_invalidate(conversation, changed_attributes = nil)
+    refreshed = refresh(conversation, changed_attributes)
+    invalidate_filtered_conversation(conversation)
+    notify_filtered_count_change(conversation) unless refreshed
+  end
+
   def refresh(conversation, changed_attributes = nil)
     ::Conversations::UnreadCounts::Notifier.new(conversation, changed_attributes: changed_attributes).perform
   end
@@ -90,6 +124,37 @@ class Conversations::UnreadCounts::Listener < BaseListener
       changed_attributes.key?('cached_label_list') || changed_attributes.key?(:cached_label_list)
   end
 
+  def filtered_conversation_update_changed?(changed_attributes)
+    return false if changed_attributes.blank?
+
+    changed_attributes.keys.map(&:to_s).intersect?(FILTERED_CONVERSATION_UPDATE_KEYS)
+  end
+
+  def invalidate_filtered_conversation(conversation)
+    filtered_count_invalidator(conversation.account).conversation_changed!
+  end
+
+  def notify_filtered_count_change(conversation)
+    return unless conversation.account.feature_enabled?('conversation_unread_counts')
+    return unless conversation.account.feature_enabled?(filtered_count_feature_flag)
+
+    Rails.configuration.dispatcher.dispatch(CONVERSATION_UNREAD_COUNT_CHANGED, Time.zone.now, conversation: conversation)
+  end
+
+  def notify_deleted_filtered_count_change(account, conversation_data)
+    return unless account.feature_enabled?(filtered_count_feature_flag)
+
+    Rails.configuration.dispatcher.dispatch(CONVERSATION_UNREAD_COUNT_CHANGED, Time.zone.now, conversation_data: conversation_data.to_h)
+  end
+
+  def filtered_count_invalidator(account)
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account)
+  end
+
+  def filtered_count_feature_flag
+    ::Conversations::UnreadCounts::FilteredCountInvalidator::FEATURE_FLAG
+  end
+
   def store
     ::Conversations::UnreadCounts::Store
   end
diff --git a/app/services/conversations/unread_counts/notifier.rb b/app/services/conversations/unread_counts/notifier.rb
index 652fbde3a..6075b4abc 100644
--- a/app/services/conversations/unread_counts/notifier.rb
+++ b/app/services/conversations/unread_counts/notifier.rb
@@ -10,10 +10,20 @@ class Conversations::UnreadCounts::Notifier
 
   def perform
     return false unless conversation.account.feature_enabled?('conversation_unread_counts')
+    return dispatch_unread_count_changed if ::Conversations::UnreadCounts::Refresher.new(conversation, changed_attributes: changed_attributes).perform
+    return false unless conversation.account.feature_enabled?(filtered_count_feature_flag)
 
-    return false unless ::Conversations::UnreadCounts::Refresher.new(conversation, changed_attributes: changed_attributes).perform
+    dispatch_unread_count_changed
+  end
 
+  private
+
+  def dispatch_unread_count_changed
     Rails.configuration.dispatcher.dispatch(CONVERSATION_UNREAD_COUNT_CHANGED, Time.zone.now, conversation: conversation)
     true
   end
+
+  def filtered_count_feature_flag
+    ::Conversations::UnreadCounts::FilteredCountInvalidator::FEATURE_FLAG
+  end
 end
diff --git a/app/services/labels/destroy_service.rb b/app/services/labels/destroy_service.rb
index 080e708e7..b5d7add33 100644
--- a/app/services/labels/destroy_service.rb
+++ b/app/services/labels/destroy_service.rb
@@ -2,19 +2,25 @@ class Labels::DestroyService
   pattr_initialize [:label_title!, :account_id!, :label_deleted_at!]
 
   def perform
-    remove_conversation_labels
+    conversation_labels_removed = remove_conversation_labels
     remove_contact_labels
+    invalidate_filtered_unread_count_conversations if conversation_labels_removed
   end
 
   private
 
   def remove_conversation_labels
+    conversation_labels_removed = false
+
     tagged_conversations.find_in_batches do |conversation_batch|
       conversation_batch.each do |conversation|
         update_conversation_cached_labels(conversation)
       end
       delete_label_taggings('Conversation', conversation_batch.map(&:id))
+      conversation_labels_removed = true
     end
+
+    conversation_labels_removed
   end
 
   def remove_contact_labels
@@ -57,4 +63,8 @@ class Labels::DestroyService
   def account
     @account ||= Account.find(account_id)
   end
+
+  def invalidate_filtered_unread_count_conversations
+    ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account).conversation_changed!
+  end
 end
diff --git a/config/features.yml b/config/features.yml
index 55a1e815d..fe2ef2122 100644
--- a/config/features.yml
+++ b/config/features.yml
@@ -223,10 +223,10 @@
   display_name: Reply Mailer Migration
   enabled: false
   chatwoot_internal: true
-- name: quoted_email_reply
-  display_name: Quoted Email Reply
+- name: unread_count_for_filters
+  display_name: Unread Count For Filters
   enabled: false
-  deprecated: true
+  chatwoot_internal: true
 - name: companies
   display_name: Companies
   enabled: false
diff --git a/db/migrate/20260629000000_repurpose_quoted_email_reply_flag_for_unread_count_for_filters.rb b/db/migrate/20260629000000_repurpose_quoted_email_reply_flag_for_unread_count_for_filters.rb
new file mode 100644
index 000000000..82f15a964
--- /dev/null
+++ b/db/migrate/20260629000000_repurpose_quoted_email_reply_flag_for_unread_count_for_filters.rb
@@ -0,0 +1,22 @@
+class RepurposeQuotedEmailReplyFlagForUnreadCountForFilters < ActiveRecord::Migration[7.1]
+  def up
+    # The quoted_email_reply flag (deprecated) has been renamed to unread_count_for_filters.
+    # Disable it on any accounts that had quoted_email_reply enabled so the repurposed
+    # flag starts in its intended default-off state.
+    Account.feature_unread_count_for_filters.find_each(batch_size: 100) do |account|
+      account.disable_features(:unread_count_for_filters)
+      account.save!(validate: false)
+    end
+
+    # Remove the stale quoted_email_reply entry from ACCOUNT_LEVEL_FEATURE_DEFAULTS.
+    # ConfigLoader only adds new flags; it never removes renamed ones.
+    # Leaving it would cause NoMethodError in enable_default_features when
+    # creating new accounts (feature_quoted_email_reply= no longer exists).
+    config = InstallationConfig.find_by(name: 'ACCOUNT_LEVEL_FEATURE_DEFAULTS')
+    return if config&.value.blank?
+
+    config.value = config.value.reject { |feature| feature['name'] == 'quoted_email_reply' }
+    config.save!
+    GlobalConfig.clear_cache
+  end
+end
diff --git a/enterprise/app/models/custom_role.rb b/enterprise/app/models/custom_role.rb
index 666f91378..1eb39d1f7 100644
--- a/enterprise/app/models/custom_role.rb
+++ b/enterprise/app/models/custom_role.rb
@@ -28,6 +28,10 @@ class CustomRole < ApplicationRecord
   belongs_to :account
   has_many :account_users, dependent: :nullify
 
+  before_destroy :capture_filtered_unread_count_user_ids, prepend: true
+  after_update_commit :invalidate_filtered_unread_count_visibility_update, if: :filtered_unread_count_permissions_changed?
+  after_destroy_commit :invalidate_filtered_unread_count_visibility_destroy
+
   PERMISSIONS = %w[
     conversation_manage
     conversation_unassigned_manage
@@ -39,4 +43,33 @@ class CustomRole < ApplicationRecord
 
   validates :name, presence: true
   validates :permissions, inclusion: { in: PERMISSIONS }
+
+  private
+
+  def filtered_unread_count_permissions_changed?
+    previous_changes.key?('permissions')
+  end
+
+  def capture_filtered_unread_count_user_ids
+    @filtered_unread_count_user_ids = account_users.pluck(:user_id)
+  end
+
+  def invalidate_filtered_unread_count_visibility_update
+    invalidate_filtered_unread_count_visibility(account_users.pluck(:user_id))
+  end
+
+  def invalidate_filtered_unread_count_visibility_destroy
+    invalidate_filtered_unread_count_visibility(@filtered_unread_count_user_ids)
+  end
+
+  def invalidate_filtered_unread_count_visibility(user_ids)
+    invalidator = ::Conversations::UnreadCounts::FilteredCountInvalidator.new(account)
+    visibility_changed = invalidator.users_visibility_changed!(user_ids: user_ids)
+
+    dispatch_account_cache_invalidated if visibility_changed
+  end
+
+  def dispatch_account_cache_invalidated
+    Rails.configuration.dispatcher.dispatch(ACCOUNT_CACHE_INVALIDATED, Time.zone.now, account: account, cache_keys: account.cache_keys)
+  end
 end
diff --git a/enterprise/app/services/enterprise/conversations/permission_filter_service.rb b/enterprise/app/services/enterprise/conversations/permission_filter_service.rb
index f55265a90..118ae3d14 100644
--- a/enterprise/app/services/enterprise/conversations/permission_filter_service.rb
+++ b/enterprise/app/services/enterprise/conversations/permission_filter_service.rb
@@ -23,17 +23,22 @@ module Enterprise::Conversations::PermissionFilterService
     elsif permissions.include?('conversation_unassigned_manage')
       filter_unassigned_and_mine
     elsif permissions.include?('conversation_participating_manage')
-      accessible_conversations.assigned_to(user)
+      filter_participating_and_mine
     else
       Conversation.none
     end
   end
 
-  def filter_unassigned_and_mine
-    mine = accessible_conversations.assigned_to(user)
-    unassigned = accessible_conversations.unassigned
+  def filter_participating_and_mine
+    conversations = accessible_conversations
+    participant_conversation_ids = ConversationParticipant.where(account_id: account.id, user_id: user.id).select(:conversation_id)
 
-    Conversation.from("(#{mine.to_sql} UNION #{unassigned.to_sql}) as conversations")
-                .where(account_id: account.id)
+    conversations
+      .where(assignee_id: user.id)
+      .or(conversations.where(id: participant_conversation_ids))
+  end
+
+  def filter_unassigned_and_mine
+    accessible_conversations.where(assignee_id: [nil, user.id])
   end
 end
diff --git a/lib/redis/redis_keys.rb b/lib/redis/redis_keys.rb
index 6d503df22..b782270ef 100644
--- a/lib/redis/redis_keys.rb
+++ b/lib/redis/redis_keys.rb
@@ -33,6 +33,23 @@ module Redis::RedisKeys
     'UNREAD_CONVERSATIONS::V1::ACCOUNT::%<account_id>d::TEAM::%<team_id>d::INBOX::%<inbox_id>d::UNASSIGNED'.freeze
   UNREAD_CONVERSATIONS_TEAM_INBOX_ASSIGNEE =
     'UNREAD_CONVERSATIONS::V1::ACCOUNT::%<account_id>d::TEAM::%<team_id>d::INBOX::%<inbox_id>d::ASSIGNEE::%<user_id>d'.freeze
+  UNREAD_CONVERSATIONS_V2_ACCOUNT_PREFIX = 'UNREAD_CONVERSATIONS::V2::ACCOUNT::%<account_id>d'.freeze
+  UNREAD_CONVERSATIONS_V2_USER_PREFIX = "#{UNREAD_CONVERSATIONS_V2_ACCOUNT_PREFIX}::USER::%<user_id>d".freeze
+  UNREAD_CONVERSATIONS_V2_FILTER_PREFIX = "#{UNREAD_CONVERSATIONS_V2_ACCOUNT_PREFIX}::FILTER::%<filter_id>d".freeze
+  UNREAD_CONVERSATIONS_V2_CONVERSATION_VERSION = "#{UNREAD_CONVERSATIONS_V2_ACCOUNT_PREFIX}::CONVERSATION_VERSION".freeze
+  UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_VERSION = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::BUILT_IN_FILTER_VERSION".freeze
+  UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_COUNTS = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::BUILT_IN_FILTER_COUNTS".freeze
+  UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_BUILD_LOCK = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::BUILT_IN_FILTER_BUILD_LOCK".freeze
+  UNREAD_CONVERSATIONS_V2_BUILT_IN_FILTER_REFRESH_THROTTLE =
+    "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::BUILT_IN_FILTER_REFRESH_THROTTLE".freeze
+  UNREAD_CONVERSATIONS_V2_FOLDER_INDEX_VERSION = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::FOLDER_INDEX_VERSION".freeze
+  UNREAD_CONVERSATIONS_V2_FOLDER_INDEX = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::FOLDER_INDEX".freeze
+  UNREAD_CONVERSATIONS_V2_FOLDER_INDEX_BUILD_LOCK = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::FOLDER_INDEX_BUILD_LOCK".freeze
+  UNREAD_CONVERSATIONS_V2_FOLDER_INDEX_REFRESH_THROTTLE = "#{UNREAD_CONVERSATIONS_V2_USER_PREFIX}::FOLDER_INDEX_REFRESH_THROTTLE".freeze
+  UNREAD_CONVERSATIONS_V2_FILTER_VERSION = "#{UNREAD_CONVERSATIONS_V2_FILTER_PREFIX}::VERSION".freeze
+  UNREAD_CONVERSATIONS_V2_FILTER_COUNT = "#{UNREAD_CONVERSATIONS_V2_FILTER_PREFIX}::COUNT".freeze
+  UNREAD_CONVERSATIONS_V2_FILTER_BUILD_LOCK = "#{UNREAD_CONVERSATIONS_V2_FILTER_PREFIX}::BUILD_LOCK".freeze
+  UNREAD_CONVERSATIONS_V2_FILTER_REFRESH_THROTTLE = "#{UNREAD_CONVERSATIONS_V2_FILTER_PREFIX}::REFRESH_THROTTLE".freeze
 
   ## User Keys
   # SSO Auth Tokens
diff --git a/spec/controllers/api/v1/accounts/conversations/participants_controller_spec.rb b/spec/controllers/api/v1/accounts/conversations/participants_controller_spec.rb
index 6238314ab..33d3f64be 100644
--- a/spec/controllers/api/v1/accounts/conversations/participants_controller_spec.rb
+++ b/spec/controllers/api/v1/accounts/conversations/participants_controller_spec.rb
@@ -68,6 +68,23 @@ RSpec.describe 'Conversation Participants API', type: :request do
         expect(response.body).to include(participant.email)
         expect(conversation.conversation_participants.count).to eq(1)
       end
+
+      it 'notifies unread counts when a participant is added' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        allow(Rails.configuration.dispatcher).to receive(:dispatch)
+        params = { user_ids: [participant.id] }
+
+        post api_v1_account_conversation_participants_url(account_id: account.id, conversation_id: conversation.display_id),
+             params: params,
+             headers: agent.create_new_auth_token,
+             as: :json
+
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'conversation.unread_count_changed',
+          kind_of(ActiveSupport::TimeWithZone),
+          conversation: conversation
+        )
+      end
     end
   end
 
@@ -106,6 +123,25 @@ RSpec.describe 'Conversation Participants API', type: :request do
         expect(response.body).to include(participant_to_be_added.email)
         expect(conversation.conversation_participants.count).to eq(2)
       end
+
+      it 'notifies unread counts when participant membership changes' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        allow(Rails.configuration.dispatcher).to receive(:dispatch)
+        params = { user_ids: [participant.id, participant_to_be_added.id] }
+        create(:conversation_participant, conversation: conversation, user: participant)
+        create(:conversation_participant, conversation: conversation, user: participant_to_be_removed)
+
+        put api_v1_account_conversation_participants_url(account_id: account.id, conversation_id: conversation.display_id),
+            params: params,
+            headers: agent.create_new_auth_token,
+            as: :json
+
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'conversation.unread_count_changed',
+          kind_of(ActiveSupport::TimeWithZone),
+          conversation: conversation
+        )
+      end
     end
   end
 
@@ -137,6 +173,24 @@ RSpec.describe 'Conversation Participants API', type: :request do
         expect(response).to have_http_status(:success)
         expect(conversation.conversation_participants.count).to eq(0)
       end
+
+      it 'notifies unread counts when a participant is removed' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        allow(Rails.configuration.dispatcher).to receive(:dispatch)
+        params = { user_ids: [participant.id] }
+        create(:conversation_participant, conversation: conversation, user: participant)
+
+        delete api_v1_account_conversation_participants_url(account_id: account.id, conversation_id: conversation.display_id),
+               params: params,
+               headers: agent.create_new_auth_token,
+               as: :json
+
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'conversation.unread_count_changed',
+          kind_of(ActiveSupport::TimeWithZone),
+          conversation: conversation
+        )
+      end
     end
   end
 end
diff --git a/spec/controllers/api/v1/accounts/conversations_controller_spec.rb b/spec/controllers/api/v1/accounts/conversations_controller_spec.rb
index bdb8117ac..b0eddd639 100644
--- a/spec/controllers/api/v1/accounts/conversations_controller_spec.rb
+++ b/spec/controllers/api/v1/accounts/conversations_controller_spec.rb
@@ -159,6 +159,28 @@ RSpec.describe 'Conversations API', type: :request do
           expect(response).to have_http_status(:success)
           expect(response.parsed_body['payload']['teams']).to eq(team.id.to_s => 1)
         end
+
+        it 'returns filtered unread counts when the filtered count feature is enabled' do
+          account.enable_features!(:unread_count_for_filters)
+          allow(Conversations::UnreadCounts::FilteredCountInstrumentation).to receive(:summarize_request) do |**_attributes, &block|
+            block.call
+          end
+          mentioned = create_unread_conversation(account: account, inbox: visible_inbox)
+          create(:mention, account: account, conversation: mentioned, user: agent)
+
+          get "/api/v1/accounts/#{account.id}/conversations/unread_counts",
+              headers: agent.create_new_auth_token,
+              as: :json
+
+          expect(response).to have_http_status(:success)
+          expect(response.parsed_body['payload']).to include(
+            'mentions_count' => 1,
+            'participating_count' => 0,
+            'unattended_count' => 1,
+            'folders' => {}
+          )
+          expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:summarize_request).with(account_id: account.id)
+        end
       end
 
       it 'returns forbidden when conversation unread counts feature is disabled' do
@@ -865,6 +887,59 @@ RSpec.describe 'Conversations API', type: :request do
         Conversations::UnreadCounts::Store.clear_account!(account.id)
       end
 
+      it 'refreshes unread count cache before invalidating filtered counts when conversation is marked read' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        conversation.update!(agent_last_seen_at: 1.hour.ago)
+        create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :incoming, created_at: 5.minutes.ago)
+        notifier = instance_double(Conversations::UnreadCounts::Notifier)
+        invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator)
+
+        allow(Conversations::UnreadCounts::Notifier).to receive(:new).with(conversation).and_return(notifier)
+        allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+        expect(notifier).to receive(:perform).ordered.and_return(true)
+        expect(invalidator).to receive(:conversation_changed!).ordered.and_return(true)
+
+        post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/update_last_seen",
+             headers: agent.create_new_auth_token,
+             as: :json
+
+        expect(response).to have_http_status(:success)
+      end
+
+      it 'invalidates filtered unread counts when conversation is marked read' do
+        conversation.update!(agent_last_seen_at: 1.hour.ago)
+        create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :incoming, created_at: 5.minutes.ago)
+        account.enable_features!(:unread_count_for_filters)
+
+        expect do
+          post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/update_last_seen",
+               headers: agent.create_new_auth_token,
+               as: :json
+        end.to change { Conversations::UnreadCounts::FilteredCountStore.conversation_version(account.id) }.by(1)
+        expect(response).to have_http_status(:success)
+      end
+
+      it 'notifies clients when marking read only affects filtered counts' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        conversation.update!(agent_last_seen_at: 1.hour.ago)
+        create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :incoming, created_at: 5.minutes.ago)
+        allow(Conversations::UnreadCounts::Refresher).to receive(:new).and_return(
+          instance_double(Conversations::UnreadCounts::Refresher, perform: false)
+        )
+        allow(Rails.configuration.dispatcher).to receive(:dispatch)
+
+        post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/update_last_seen",
+             headers: agent.create_new_auth_token,
+             as: :json
+
+        expect(response).to have_http_status(:success)
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'conversation.unread_count_changed',
+          kind_of(Time),
+          conversation: conversation
+        )
+      end
+
       it 'updates both if one timestamp is old even when the other is recent' do
         conversation.update!(assignee_id: agent.id, agent_last_seen_at: 2.hours.ago, assignee_last_seen_at: 30.minutes.ago)
         # Ensure all messages are older than assignee_last_seen_at (no unread messages)
@@ -951,6 +1026,56 @@ RSpec.describe 'Conversations API', type: :request do
       ensure
         Conversations::UnreadCounts::Store.clear_account!(account.id)
       end
+
+      it 'refreshes unread count cache before invalidating filtered counts when conversation is marked unread' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        conversation.update!(agent_last_seen_at: 1.minute.from_now, assignee_last_seen_at: 1.minute.from_now)
+        notifier = instance_double(Conversations::UnreadCounts::Notifier)
+        invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator)
+
+        allow(Conversations::UnreadCounts::Notifier).to receive(:new).with(conversation).and_return(notifier)
+        allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+        expect(notifier).to receive(:perform).ordered.and_return(true)
+        expect(invalidator).to receive(:conversation_changed!).ordered.and_return(true)
+
+        post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/unread",
+             headers: agent.create_new_auth_token,
+             as: :json
+
+        expect(response).to have_http_status(:success)
+      end
+
+      it 'invalidates filtered unread counts when conversation is marked unread' do
+        conversation.update!(agent_last_seen_at: 1.minute.from_now, assignee_last_seen_at: 1.minute.from_now)
+        account.enable_features!(:unread_count_for_filters)
+
+        expect do
+          post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/unread",
+               headers: agent.create_new_auth_token,
+               as: :json
+        end.to change { Conversations::UnreadCounts::FilteredCountStore.conversation_version(account.id) }.by(1)
+        expect(response).to have_http_status(:success)
+      end
+
+      it 'notifies clients when marking unread only affects filtered counts' do
+        account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+        conversation.update!(agent_last_seen_at: 1.minute.from_now, assignee_last_seen_at: 1.minute.from_now)
+        allow(Conversations::UnreadCounts::Refresher).to receive(:new).and_return(
+          instance_double(Conversations::UnreadCounts::Refresher, perform: false)
+        )
+        allow(Rails.configuration.dispatcher).to receive(:dispatch)
+
+        post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/unread",
+             headers: agent.create_new_auth_token,
+             as: :json
+
+        expect(response).to have_http_status(:success)
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'conversation.unread_count_changed',
+          kind_of(Time),
+          conversation: conversation
+        )
+      end
     end
   end
 
diff --git a/spec/enterprise/finders/conversation_finder_spec.rb b/spec/enterprise/finders/conversation_finder_spec.rb
new file mode 100644
index 000000000..f415ac473
--- /dev/null
+++ b/spec/enterprise/finders/conversation_finder_spec.rb
@@ -0,0 +1,41 @@
+require 'rails_helper'
+
+RSpec.describe ConversationFinder do
+  describe '#perform_meta_only' do
+    let(:account) { create(:account) }
+    let(:agent) { create(:user, account: account, role: :agent) }
+    let(:other_agent) { create(:user, account: account, role: :agent) }
+    let(:inbox) { create(:inbox, account: account) }
+
+    before do
+      Current.account = account
+      create(:inbox_member, user: agent, inbox: inbox)
+      account.account_users.find_by(user: agent).update!(
+        role: :agent,
+        custom_role: create(:custom_role, account: account, permissions: %w[conversation_participating_manage])
+      )
+    end
+
+    it 'counts participant-filtered conversations once when assigned conversations have multiple participants' do
+      assigned_conversation = create(:conversation, account: account, inbox: inbox, assignee: agent)
+      participating_conversation = create(:conversation, account: account, inbox: inbox, assignee: other_agent)
+      create(:conversation, account: account, inbox: inbox, assignee: other_agent)
+
+      2.times do
+        participant = create(:user, account: account, role: :agent)
+        create(:inbox_member, user: participant, inbox: inbox)
+        create(:conversation_participant, account: account, conversation: assigned_conversation, user: participant)
+      end
+      create(:conversation_participant, account: account, conversation: participating_conversation, user: agent)
+
+      result = described_class.new(agent, { status: 'open' }).perform_meta_only
+
+      expect(result[:count]).to eq({
+                                     mine_count: 1,
+                                     assigned_count: 2,
+                                     unassigned_count: 0,
+                                     all_count: 2
+                                   })
+    end
+  end
+end
diff --git a/spec/enterprise/models/account_user_spec.rb b/spec/enterprise/models/account_user_spec.rb
index fb572e86a..c79cfb4b6 100644
--- a/spec/enterprise/models/account_user_spec.rb
+++ b/spec/enterprise/models/account_user_spec.rb
@@ -29,6 +29,29 @@ RSpec.describe AccountUser, type: :model do
     end
   end
 
+  describe 'filtered unread count invalidation' do
+    it 'invalidates filtered counts when the custom role assignment changes' do
+      account = create(:account)
+      user = create(:user)
+      account_user = create(:account_user, account: account, user: user)
+      custom_role = create(:custom_role, account: account)
+      invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator, user_visibility_changed!: true)
+
+      allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).and_return(invalidator)
+      allow(Rails.configuration.dispatcher).to receive(:dispatch)
+
+      account_user.update!(custom_role_id: custom_role.id)
+
+      expect(invalidator).to have_received(:user_visibility_changed!).with(user_id: user.id)
+      expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+        'account.cache_invalidated',
+        kind_of(Time),
+        account: account,
+        cache_keys: account.cache_keys
+      )
+    end
+  end
+
   describe 'audit log' do
     context 'when account user is created' do
       it 'has associated audit log created' do
diff --git a/spec/enterprise/models/custom_role_spec.rb b/spec/enterprise/models/custom_role_spec.rb
index f63f3c2dd..5ee3353b3 100644
--- a/spec/enterprise/models/custom_role_spec.rb
+++ b/spec/enterprise/models/custom_role_spec.rb
@@ -9,4 +9,49 @@ RSpec.describe CustomRole, type: :model do
   describe 'validations' do
     it { is_expected.to validate_presence_of(:name) }
   end
+
+  describe 'filtered unread count invalidation' do
+    let(:account) { create(:account) }
+    let(:custom_role) { create(:custom_role, account: account, permissions: ['conversation_manage']) }
+    let(:user) { create(:user) }
+    let(:other_user) { create(:user) }
+    let(:invalidator) { instance_double(Conversations::UnreadCounts::FilteredCountInvalidator, users_visibility_changed!: true) }
+
+    before do
+      create(:account_user, account: account, user: user, custom_role: custom_role)
+      create(:account_user, account: account, user: other_user, custom_role: custom_role)
+      allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+      allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    end
+
+    it 'invalidates filtered counts for assigned users when permissions change' do
+      custom_role.update!(permissions: ['conversation_participating_manage'])
+
+      expect(invalidator).to have_received(:users_visibility_changed!).with(user_ids: contain_exactly(user.id, other_user.id))
+      expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+        'account.cache_invalidated',
+        kind_of(Time),
+        account: account,
+        cache_keys: account.cache_keys
+      )
+    end
+
+    it 'does not invalidate filtered counts when permissions are unchanged' do
+      custom_role.update!(name: 'Support manager')
+
+      expect(invalidator).not_to have_received(:users_visibility_changed!)
+    end
+
+    it 'invalidates filtered counts for assigned users when the role is deleted' do
+      custom_role.destroy!
+
+      expect(invalidator).to have_received(:users_visibility_changed!).with(user_ids: contain_exactly(user.id, other_user.id))
+      expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+        'account.cache_invalidated',
+        kind_of(Time),
+        account: account,
+        cache_keys: account.cache_keys
+      )
+    end
+  end
 end
diff --git a/spec/enterprise/services/conversations/unread_counts/filtered_counter_spec.rb b/spec/enterprise/services/conversations/unread_counts/filtered_counter_spec.rb
new file mode 100644
index 000000000..81c9ae4d0
--- /dev/null
+++ b/spec/enterprise/services/conversations/unread_counts/filtered_counter_spec.rb
@@ -0,0 +1,58 @@
+require 'rails_helper'
+
+RSpec.describe Conversations::UnreadCounts::FilteredCounter do
+  let(:account) { create(:account) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:other_agent) { create(:user, account: account, role: :agent) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:account_user) { account.account_users.find_by(user: agent) }
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+  before do
+    create(:inbox_member, user: agent, inbox: inbox)
+    account_user.update!(custom_role: create(:custom_role, account: account, permissions: ['conversation_participating_manage']))
+  end
+
+  after do
+    redis_keys.each { |key| Redis::Alfred.delete(key) }
+  end
+
+  it 'counts participating conversations inside the permission-filtered accessible set' do
+    assigned_participating = create_unread_conversation(account: account, inbox: inbox, assignee: agent)
+    unassigned_participating = create_unread_conversation(account: account, inbox: inbox)
+    assigned_to_other_participating = create_unread_conversation(account: account, inbox: inbox, assignee: other_agent)
+    assigned_not_participating = create_unread_conversation(account: account, inbox: inbox, assignee: agent)
+    create(:conversation_participant, account: account, conversation: assigned_participating, user: agent)
+    create(:conversation_participant, account: account, conversation: unassigned_participating, user: agent)
+    create(:conversation_participant, account: account, conversation: assigned_to_other_participating, user: agent)
+
+    result = described_class.new(account: account, user: agent).perform
+
+    expect(result[:participating_count]).to eq(3)
+    expect(result[:mentions_count]).to eq(0)
+    expect(result[:folders]).to eq({})
+    expect(assigned_not_participating.assignee).to eq(agent)
+  end
+
+  def redis_keys
+    [store.conversation_version_key(account.id)] + built_in_filter_keys + folder_index_keys
+  end
+
+  def built_in_filter_keys
+    [
+      store.built_in_filter_version_key(account.id, agent.id),
+      store.built_in_filter_counts_key(account.id, agent.id),
+      store.built_in_filter_build_lock_key(account.id, agent.id),
+      store.built_in_filter_refresh_throttle_key(account.id, agent.id)
+    ]
+  end
+
+  def folder_index_keys
+    [
+      store.folder_index_version_key(account.id, agent.id),
+      store.folder_index_key(account.id, agent.id),
+      store.folder_index_build_lock_key(account.id, agent.id),
+      store.folder_index_refresh_throttle_key(account.id, agent.id)
+    ]
+  end
+end
diff --git a/spec/enterprise/services/enterprise/conversations/permission_filter_service_spec.rb b/spec/enterprise/services/enterprise/conversations/permission_filter_service_spec.rb
index 0cfec97eb..08d900b6e 100644
--- a/spec/enterprise/services/enterprise/conversations/permission_filter_service_spec.rb
+++ b/spec/enterprise/services/enterprise/conversations/permission_filter_service_spec.rb
@@ -86,7 +86,7 @@ RSpec.describe Enterprise::Conversations::PermissionFilterService do
     end
 
     context 'when user has conversation_participating_manage permission' do
-      it 'returns only conversations assigned to the agent' do
+      it 'returns conversations assigned to the agent or where the agent is a participant' do
         # Create a new isolated test environment
         test_account = create(:account)
         test_inbox = create(:inbox, account: test_account)
@@ -105,7 +105,9 @@ RSpec.describe Enterprise::Conversations::PermissionFilterService do
         # Create some conversations
         other_conversation = create(:conversation, account: test_account, inbox: test_inbox)
         assigned_conversation = create(:conversation, account: test_account, inbox: test_inbox, assignee: test_agent)
+        participating_conversation = create(:conversation, account: test_account, inbox: test_inbox, assignee: create(:user, account: test_account))
         other_inbox_conversation = create(:conversation, account: test_account, inbox: test_inbox2, assignee: nil)
+        create(:conversation_participant, account: test_account, conversation: participating_conversation, user: test_agent)
 
         # Run the test
         result = Conversations::PermissionFilterService.new(
@@ -114,10 +116,10 @@ RSpec.describe Enterprise::Conversations::PermissionFilterService do
           test_account
         ).perform
 
-        # Should only see conversations assigned to this agent
-        expect(result.count).to eq(1)
-        expect(result.first.assignee).to eq(test_agent)
+        # Should only see conversations assigned to this agent or where the agent participates
+        expect(result.count).to eq(2)
         expect(result).to include(assigned_conversation)
+        expect(result).to include(participating_conversation)
         expect(result).not_to include(other_conversation)
         expect(result).not_to include(other_inbox_conversation)
       end
diff --git a/spec/jobs/agents/destroy_job_spec.rb b/spec/jobs/agents/destroy_job_spec.rb
index cf6bb2ffa..7c1c16e0c 100644
--- a/spec/jobs/agents/destroy_job_spec.rb
+++ b/spec/jobs/agents/destroy_job_spec.rb
@@ -7,6 +7,7 @@ RSpec.describe Agents::DestroyJob do
   let(:user) { create(:user, account: account) }
   let(:team1) { create(:team, account: account) }
   let!(:inbox) { create(:inbox, account: account) }
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
 
   before do
     create(:team_member, team: team1, user: user)
@@ -30,5 +31,13 @@ RSpec.describe Agents::DestroyJob do
       expect(user.notification_settings.length).to eq 0
       expect(user.assigned_conversations.where(account: account).length).to eq 0
     end
+
+    it 'invalidates saved filter snapshots when assigned conversations are unassigned' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        described_class.perform_now(account, user)
+      end.to change { store.conversation_version(account.id) }.by(1)
+    end
   end
 end
diff --git a/spec/lib/captain/reply_suggestion_service_spec.rb b/spec/lib/captain/reply_suggestion_service_spec.rb
index 608db43a2..9b5cbfa9e 100644
--- a/spec/lib/captain/reply_suggestion_service_spec.rb
+++ b/spec/lib/captain/reply_suggestion_service_spec.rb
@@ -12,6 +12,7 @@ RSpec.describe Captain::ReplySuggestionService do
   before do
     create(:installation_config, name: 'CAPTAIN_OPEN_AI_API_KEY', value: 'test-key')
     create(:message, conversation: conversation, message_type: :incoming, content: 'I need help')
+    allow(account).to receive(:feature_enabled?).and_call_original
     allow(account).to receive(:feature_enabled?).with('captain_tasks').and_return(true)
 
     mock_response = instance_double(RubyLLM::Message, content: 'Sure, I can help!', input_tokens: 50, output_tokens: 20)
diff --git a/spec/listeners/action_cable_listener_spec.rb b/spec/listeners/action_cable_listener_spec.rb
index cdb9a93cb..db387c5dc 100644
--- a/spec/listeners/action_cable_listener_spec.rb
+++ b/spec/listeners/action_cable_listener_spec.rb
@@ -13,6 +13,30 @@ describe ActionCableListener do
     Current.account = nil
   end
 
+  describe '#account_cache_invalidated' do
+    let!(:event) do
+      Events::Base.new(
+        :'account.cache_invalidated',
+        Time.zone.now,
+        account: account,
+        cache_keys: account.cache_keys
+      )
+    end
+
+    it 'sends cache invalidation to account agents and admins' do
+      expect(ActionCableBroadcastJob).to receive(:perform_later).with(
+        a_collection_containing_exactly(agent.pubsub_token, admin.pubsub_token),
+        'account.cache_invalidated',
+        {
+          cache_keys: account.cache_keys,
+          account_id: account.id
+        }
+      )
+
+      listener.account_cache_invalidated(event)
+    end
+  end
+
   describe '#message_created' do
     let(:event_name) { :'message.created' }
     let!(:message) do
diff --git a/spec/models/account_user_spec.rb b/spec/models/account_user_spec.rb
index e5a560fe9..394654db4 100644
--- a/spec/models/account_user_spec.rb
+++ b/spec/models/account_user_spec.rb
@@ -42,4 +42,43 @@ RSpec.describe AccountUser do
       expect(user.assigned_conversations.count).to eq(0)
     end
   end
+
+  describe 'filtered unread count invalidation' do
+    let(:account) { create(:account) }
+    let(:user) { create(:user) }
+    let(:invalidator) { instance_double(Conversations::UnreadCounts::FilteredCountInvalidator, user_visibility_changed!: true) }
+
+    before do
+      allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).and_return(invalidator)
+      allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    end
+
+    it 'invalidates filtered counts when the user is added to an account' do
+      create(:account_user, account: account, user: user)
+
+      expect(invalidator).to have_received(:user_visibility_changed!).with(user_id: user.id)
+    end
+
+    it 'invalidates filtered counts when the user role changes' do
+      account_user = create(:account_user, account: account, user: user)
+
+      account_user.update!(role: :administrator)
+
+      expect(invalidator).to have_received(:user_visibility_changed!).with(user_id: user.id).twice
+      expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+        'account.cache_invalidated',
+        kind_of(Time),
+        account: account,
+        cache_keys: account.cache_keys
+      )
+    end
+
+    it 'invalidates filtered counts when the user is removed from an account' do
+      account_user = create(:account_user, account: account, user: user)
+
+      account_user.destroy!
+
+      expect(invalidator).to have_received(:user_visibility_changed!).with(user_id: user.id).twice
+    end
+  end
 end
diff --git a/spec/models/campaign_spec.rb b/spec/models/campaign_spec.rb
index 2be6bd588..e4bdd05e4 100644
--- a/spec/models/campaign_spec.rb
+++ b/spec/models/campaign_spec.rb
@@ -3,11 +3,48 @@
 require 'rails_helper'
 
 RSpec.describe Campaign do
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
   describe 'associations' do
     it { is_expected.to belong_to(:account) }
     it { is_expected.to belong_to(:inbox) }
   end
 
+  describe '#destroy' do
+    let(:account) { create(:account) }
+    let(:campaign) { create(:campaign, account: account) }
+
+    before do
+      campaign
+      allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    end
+
+    after do
+      Redis::Alfred.delete(store.conversation_version_key(account.id))
+    end
+
+    it 'invalidates and refreshes filtered counts when conversations are detached from a deleted campaign' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        campaign.destroy!
+      end.to change { store.conversation_version(account.id) }.by(1)
+
+      expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+        'account.cache_invalidated',
+        kind_of(Time),
+        account: account,
+        cache_keys: account.cache_keys
+      )
+    end
+
+    it 'does not notify filtered count refreshes when the feature is disabled' do
+      campaign.destroy!
+
+      expect(Rails.configuration.dispatcher).not_to have_received(:dispatch)
+    end
+  end
+
   describe '.before_create' do
     let(:account) { create(:account) }
     let(:website_channel) { create(:channel_widget, account: account) }
diff --git a/spec/models/conversation_participants_spec.rb b/spec/models/conversation_participants_spec.rb
index c078f69f6..f8801d461 100644
--- a/spec/models/conversation_participants_spec.rb
+++ b/spec/models/conversation_participants_spec.rb
@@ -29,4 +29,30 @@ RSpec.describe ConversationParticipant do
       expect(participant.errors.messages[:user]).to eq(['must have inbox access'])
     end
   end
+
+  describe 'filtered unread count invalidation' do
+    let(:account) { create(:account) }
+    let(:conversation) { create(:conversation, account: account) }
+    let(:user) { create(:user, account: account) }
+    let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+    before do
+      account.enable_features!(:unread_count_for_filters)
+      create(:inbox_member, inbox: conversation.inbox, user: user)
+    end
+
+    it 'invalidates the participant built-in filter version when a participant is added' do
+      expect do
+        create(:conversation_participant, account: account, conversation: conversation, user: user)
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates the participant built-in filter version when a participant is removed' do
+      participant = create(:conversation_participant, account: account, conversation: conversation, user: user)
+
+      expect do
+        participant.destroy!
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+  end
 end
diff --git a/spec/models/conversation_spec.rb b/spec/models/conversation_spec.rb
index 58d64ea94..43bbab56f 100644
--- a/spec/models/conversation_spec.rb
+++ b/spec/models/conversation_spec.rb
@@ -117,6 +117,7 @@ RSpec.describe Conversation do
     end
     let(:assignment_mailer) { instance_double(AssignmentMailer, deliver: true) }
     let(:label) { create(:label, account: account) }
+    let(:filtered_store) { Conversations::UnreadCounts::FilteredCountStore }
 
     before do
       create(:inbox_member, user: old_assignee, inbox: conversation.inbox)
@@ -125,6 +126,10 @@ RSpec.describe Conversation do
       Current.user = old_assignee
     end
 
+    after do
+      Redis::Alfred.delete(filtered_store.conversation_version_key(account.id))
+    end
+
     it 'sends conversation updated event if labels are updated' do
       conversation.update(label_list: [label.title])
       changed_attributes = conversation.previous_changes
@@ -139,6 +144,33 @@ RSpec.describe Conversation do
         )
     end
 
+    it 'invalidates filtered counts without sending conversation updated event if last activity time is updated' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        conversation.update!(last_activity_at: 1.hour.from_now)
+      end.to change { filtered_store.conversation_version(account.id) }.by(1)
+      expect(Rails.configuration.dispatcher).not_to have_received(:dispatch).with(
+        described_class::CONVERSATION_UPDATED,
+        kind_of(Time),
+        anything
+      )
+    end
+
+    it 'invalidates filtered counts without sending conversation updated event if campaign assignment is updated' do
+      account.enable_features!(:unread_count_for_filters)
+      campaign = create(:campaign, account: account, inbox: conversation.inbox)
+
+      expect do
+        conversation.update!(campaign: campaign)
+      end.to change { filtered_store.conversation_version(account.id) }.by(1)
+      expect(Rails.configuration.dispatcher).not_to have_received(:dispatch).with(
+        described_class::CONVERSATION_UPDATED,
+        kind_of(Time),
+        anything
+      )
+    end
+
     it 'runs after_update callbacks' do
       conversation.update(
         status: :resolved,
@@ -174,20 +206,47 @@ RSpec.describe Conversation do
         .with(described_class::CONVERSATION_UPDATED, kind_of(Time), conversation: conversation, notifiable_assignee_change: true)
     end
 
-    it 'will run conversation_updated event for conversation_language in additional_attributes' do
-      conversation.additional_attributes[:conversation_language] = 'es'
-      conversation.save!
+    it 'will run conversation_updated event for conversation language changes' do
+      conversation.update!(additional_attributes: { 'conversation_language' => 'es' })
       changed_attributes = conversation.previous_changes
+
       expect(Rails.configuration.dispatcher).to have_received(:dispatch)
         .with(described_class::CONVERSATION_UPDATED, kind_of(Time), conversation: conversation, notifiable_assignee_change: false,
                                                                     changed_attributes: changed_attributes, performed_by: nil)
     end
 
-    it 'will not run conversation_updated event for bowser_language in additional_attributes' do
-      conversation.additional_attributes[:browser_language] = 'es'
+    it 'invalidates filtered counts without sending conversation_updated for filtered-only additional_attributes' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        conversation.update!(additional_attributes: { 'browser_language' => 'es' })
+      end.to change { filtered_store.conversation_version(account.id) }.by(1)
+      expect(Rails.configuration.dispatcher).not_to have_received(:dispatch).with(
+        described_class::CONVERSATION_UPDATED,
+        kind_of(Time),
+        anything
+      )
+    end
+
+    it 'invalidates filtered counts when filterable additional_attributes are removed' do
+      account.enable_features!(:unread_count_for_filters)
+      conversation.update!(additional_attributes: { 'referer' => 'https://www.chatwoot.com/' })
+
+      expect do
+        conversation.update!(additional_attributes: {})
+      end.to change { filtered_store.conversation_version(account.id) }.by(1)
+      expect(Rails.configuration.dispatcher).not_to have_received(:dispatch).with(
+        described_class::CONVERSATION_UPDATED,
+        kind_of(Time),
+        anything
+      )
+    end
+
+    it 'will not run conversation_updated event for non-filterable additional_attributes' do
+      conversation.additional_attributes[:source_id] = 'es'
       conversation.save!
       expect(Rails.configuration.dispatcher).not_to have_received(:dispatch)
-        .with(described_class::CONVERSATION_UPDATED, kind_of(Time), conversation: conversation, notifiable_assignee_change: true)
+        .with(described_class::CONVERSATION_UPDATED, kind_of(Time), anything)
     end
 
     it 'creates conversation activities' do
diff --git a/spec/models/custom_attribute_definition_spec.rb b/spec/models/custom_attribute_definition_spec.rb
index c529fc609..8cf9065e0 100644
--- a/spec/models/custom_attribute_definition_spec.rb
+++ b/spec/models/custom_attribute_definition_spec.rb
@@ -68,5 +68,51 @@ RSpec.describe CustomAttributeDefinition do
         expect(cad.attribute_display_name).to eq('Order Date')
       end
     end
+
+    describe 'filtered unread count invalidation' do
+      let(:invalidator) { instance_double(Conversations::UnreadCounts::FilteredCountInvalidator, custom_attribute_definition_changed!: true) }
+
+      before do
+        allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+        allow(Rails.configuration.dispatcher).to receive(:dispatch)
+      end
+
+      it 'invalidates conversation filters when a conversation custom attribute definition changes' do
+        cad = create(:custom_attribute_definition, account: account, attribute_model: 'conversation_attribute')
+
+        cad.update!(attribute_display_name: 'Updated Order Date')
+
+        expect(invalidator).to have_received(:custom_attribute_definition_changed!).with(cad)
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'account.cache_invalidated',
+          kind_of(Time),
+          account: account,
+          cache_keys: account.cache_keys
+        )
+      end
+
+      it 'invalidates conversation filters when a conversation custom attribute definition is deleted' do
+        cad = create(:custom_attribute_definition, account: account, attribute_model: 'conversation_attribute')
+
+        cad.destroy!
+
+        expect(invalidator).to have_received(:custom_attribute_definition_changed!).with(cad)
+        expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+          'account.cache_invalidated',
+          kind_of(Time),
+          account: account,
+          cache_keys: account.cache_keys
+        )
+      end
+
+      it 'ignores contact custom attribute definition changes' do
+        cad = create(:custom_attribute_definition, account: account, attribute_model: 'contact_attribute')
+
+        cad.update!(attribute_display_name: 'Updated Contact Field')
+
+        expect(invalidator).not_to have_received(:custom_attribute_definition_changed!)
+        expect(Rails.configuration.dispatcher).not_to have_received(:dispatch)
+      end
+    end
   end
 end
diff --git a/spec/models/custom_filter_spec.rb b/spec/models/custom_filter_spec.rb
new file mode 100644
index 000000000..ecb3f2baa
--- /dev/null
+++ b/spec/models/custom_filter_spec.rb
@@ -0,0 +1,58 @@
+require 'rails_helper'
+
+RSpec.describe CustomFilter do
+  let(:account) { create(:account) }
+  let(:user) { create(:user, account: account) }
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+  before do
+    account.enable_features!(:unread_count_for_filters)
+  end
+
+  describe 'filtered unread count invalidation' do
+    it 'invalidates the folder index and filter version when a conversation filter is created' do
+      custom_filter = nil
+
+      expect do
+        custom_filter = create(:custom_filter, account: account, user: user, filter_type: :conversation)
+      end.to change { store.folder_index_version(account_id: account.id, user_id: user.id) }.by(1)
+      expect(store.filter_version(account_id: account.id, filter_id: custom_filter.id)).to eq(1)
+    end
+
+    it 'invalidates only the filter version when the query changes' do
+      custom_filter = create(:custom_filter, account: account, user: user, filter_type: :conversation)
+      folder_index_version = store.folder_index_version(account_id: account.id, user_id: user.id)
+
+      expect do
+        custom_filter.update!(query: { payload: [{ attribute_key: 'status', values: ['resolved'] }] })
+      end.to(change { store.filter_version(account_id: account.id, filter_id: custom_filter.id) }.by(1))
+      expect(store.folder_index_version(account_id: account.id, user_id: user.id)).to eq(folder_index_version)
+    end
+
+    it 'does not invalidate counts when only the name changes' do
+      custom_filter = create(:custom_filter, account: account, user: user, filter_type: :conversation)
+
+      expect do
+        custom_filter.update!(name: 'Renamed filter')
+      end.not_to(change { store.filter_version(account_id: account.id, filter_id: custom_filter.id) })
+    end
+
+    it 'invalidates the folder index and deletes the count when a conversation filter is destroyed' do
+      custom_filter = create(:custom_filter, account: account, user: user, filter_type: :conversation)
+      store.write_filter_count!(
+        account_id: account.id,
+        filter_id: custom_filter.id,
+        user_id: user.id,
+        count: 3,
+        account_version: 0,
+        filter_version: 0,
+        owner_built_in_filter_version: 0
+      )
+
+      expect do
+        custom_filter.destroy!
+      end.to change { store.folder_index_version(account_id: account.id, user_id: user.id) }.by(1)
+      expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+    end
+  end
+end
diff --git a/spec/models/inbox_member_spec.rb b/spec/models/inbox_member_spec.rb
index b081c546c..67f662cac 100644
--- a/spec/models/inbox_member_spec.rb
+++ b/spec/models/inbox_member_spec.rb
@@ -18,4 +18,46 @@ RSpec.describe InboxMember do
       end
     end
   end
+
+  describe 'filtered unread count invalidation' do
+    let(:account) { create(:account) }
+    let(:inbox) { create(:inbox, account: account) }
+    let(:user) { create(:user) }
+    let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+    before do
+      account.enable_features!(:unread_count_for_filters)
+    end
+
+    it 'invalidates the user built-in filter version when inbox access is added' do
+      expect do
+        create(:inbox_member, inbox: inbox, user: user)
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates the user built-in filter version when inbox access is removed' do
+      inbox_member = create(:inbox_member, inbox: inbox, user: user)
+
+      expect do
+        inbox_member.destroy!
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates the user built-in filter version when the parent inbox is removed' do
+      create(:inbox_member, inbox: inbox, user: user)
+
+      expect do
+        perform_enqueued_jobs { inbox.destroy! }
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates administrator built-in filter versions when the parent inbox is removed' do
+      admin = create(:user)
+      create(:account_user, account: account, user: admin, role: :administrator)
+
+      expect do
+        perform_enqueued_jobs { inbox.destroy! }
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: admin.id) }.by(1)
+    end
+  end
 end
diff --git a/spec/models/inbox_spec.rb b/spec/models/inbox_spec.rb
index 92fddcd78..617a74388 100644
--- a/spec/models/inbox_spec.rb
+++ b/spec/models/inbox_spec.rb
@@ -41,6 +41,34 @@ RSpec.describe Inbox do
     it_behaves_like 'avatarable'
   end
 
+  describe 'account teardown' do
+    it 'destroys an orphaned inbox after its account has been deleted' do
+      account = create(:account)
+      inbox = create(:inbox, account: account)
+      account.delete
+
+      orphaned_inbox = described_class.find(inbox.id)
+
+      expect { orphaned_inbox.destroy! }.not_to raise_error
+    end
+  end
+
+  describe 'filtered unread count invalidation' do
+    let(:account) { create(:account) }
+    let(:inbox) { create(:inbox, account: account) }
+    let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+    before do
+      account.enable_features!(:unread_count_for_filters)
+    end
+
+    it 'invalidates saved folder snapshots when destroyed' do
+      expect do
+        inbox.destroy!
+      end.to change { store.conversation_version(account.id) }.by(1)
+    end
+  end
+
   describe '#add_members' do
     let(:inbox) { FactoryBot.create(:inbox) }
 
diff --git a/spec/models/team_member_spec.rb b/spec/models/team_member_spec.rb
index f37f70425..d57c59996 100644
--- a/spec/models/team_member_spec.rb
+++ b/spec/models/team_member_spec.rb
@@ -1,8 +1,51 @@
 require 'rails_helper'
 
 RSpec.describe TeamMember do
+  include ActiveJob::TestHelper
+
   describe 'associations' do
     it { is_expected.to belong_to(:team) }
     it { is_expected.to belong_to(:user) }
   end
+
+  describe 'filtered unread count invalidation' do
+    let(:account) { create(:account) }
+    let(:team) { create(:team, account: account) }
+    let(:user) { create(:user) }
+    let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+    before do
+      account.enable_features!(:unread_count_for_filters)
+    end
+
+    it 'invalidates the user built-in filter version when team access is added' do
+      expect do
+        create(:team_member, team: team, user: user)
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates the user built-in filter version when team access is removed' do
+      team_member = create(:team_member, team: team, user: user)
+
+      expect do
+        team_member.destroy!
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates the user built-in filter version when the parent team is removed' do
+      create(:team_member, team: team, user: user)
+
+      expect do
+        perform_enqueued_jobs { team.destroy! }
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+
+    it 'invalidates saved filter snapshots when the parent team is removed' do
+      create(:conversation, account: account, team: team)
+
+      expect do
+        perform_enqueued_jobs { team.destroy! }
+      end.to change { store.conversation_version(account.id) }.by(1)
+    end
+  end
 end
diff --git a/spec/services/conversations/filter_service_spec.rb b/spec/services/conversations/filter_service_spec.rb
index fa054b330..eecbaec2e 100644
--- a/spec/services/conversations/filter_service_spec.rb
+++ b/spec/services/conversations/filter_service_spec.rb
@@ -231,6 +231,24 @@ describe Conversations::FilterService do
         expect(result[:count][:all_count]).to be 2
       end
 
+      it 'filters conversations by display_id substring' do
+        conversation = create(:conversation, account: account, inbox: inbox, assignee: user_1)
+        create(:conversation, account: account, inbox: inbox, assignee: user_1)
+
+        params[:payload] = [{
+          attribute_key: 'display_id',
+          filter_operator: 'contains',
+          values: [conversation.display_id.to_s],
+          query_operator: nil,
+          custom_attribute_type: ''
+        }.with_indifferent_access]
+
+        result = filter_service.new(params, user_1, account).perform
+
+        expect(result[:count][:all_count]).to eq(1)
+        expect(result[:conversations].pluck(:id)).to contain_exactly(conversation.id)
+      end
+
       it 'filters items with does not contain filter operator with values being an array' do
         params[:payload] = [{
           attribute_key: 'browser_language',
diff --git a/spec/services/conversations/unread_counts/counter_spec.rb b/spec/services/conversations/unread_counts/counter_spec.rb
index 723f2d437..50efd7d43 100644
--- a/spec/services/conversations/unread_counts/counter_spec.rb
+++ b/spec/services/conversations/unread_counts/counter_spec.rb
@@ -95,4 +95,22 @@ RSpec.describe Conversations::UnreadCounts::Counter do
       teams: { visible_team.id.to_s => 1 }
     )
   end
+
+  it 'merges filtered counts when the filtered count feature is enabled' do
+    account.enable_features!(:unread_count_for_filters)
+    filtered_counter = instance_double(
+      Conversations::UnreadCounts::FilteredCounter,
+      perform: { mentions_count: 1, participating_count: 2, unattended_count: 3, folders: { '4' => 5 } }
+    )
+    allow(Conversations::UnreadCounts::FilteredCounter).to receive(:new).and_return(filtered_counter)
+
+    result = described_class.new(account: account, user: agent).perform
+
+    expect(result).to include(
+      mentions_count: 1,
+      participating_count: 2,
+      unattended_count: 3,
+      folders: { '4' => 5 }
+    )
+  end
 end
diff --git a/spec/services/conversations/unread_counts/filtered_count_instrumentation_spec.rb b/spec/services/conversations/unread_counts/filtered_count_instrumentation_spec.rb
new file mode 100644
index 000000000..4fb6c6d36
--- /dev/null
+++ b/spec/services/conversations/unread_counts/filtered_count_instrumentation_spec.rb
@@ -0,0 +1,137 @@
+require 'rails_helper'
+
+RSpec.describe Conversations::UnreadCounts::FilteredCountInstrumentation do
+  let(:new_relic_agent) do
+    Class.new do
+      def self.record_custom_event(*) end
+      def self.record_metric(*) end
+    end
+  end
+
+  before do
+    stub_const('NewRelic::Agent', new_relic_agent)
+    allow(new_relic_agent).to receive(:record_custom_event)
+    allow(new_relic_agent).to receive(:record_metric)
+  end
+
+  describe '.observe' do
+    it 'records duration metrics without custom events around successful operations' do
+      result = described_class.observe(:counter_perform, account_id: 1, snapshot_scope: :built_in_filter) { 'ok' }
+
+      expect(result).to eq('ok')
+      expect(new_relic_agent).not_to have_received(:record_custom_event)
+      expect(new_relic_agent).to have_received(:record_metric).with(
+        'Custom/Conversations/UnreadCounts/Filtered/counter_perform/duration_ms',
+        kind_of(Float)
+      )
+    end
+
+    it 'records failed operations and re-raises the original error' do
+      error = StandardError.new('boom')
+
+      expect do
+        described_class.observe(:snapshot_build, account_id: 1) { raise error }
+      end.to raise_error(error)
+      expect(new_relic_agent).not_to have_received(:record_custom_event)
+      expect(new_relic_agent).to have_received(:record_metric).with(
+        'Custom/Conversations/UnreadCounts/Filtered/snapshot_build/duration_ms',
+        kind_of(Float)
+      )
+    end
+  end
+
+  describe '.increment' do
+    it 'records count metrics without custom events for aggregated read-path operations' do
+      described_class.increment(:snapshot_state, account_id: 1, snapshot_status: :fresh)
+
+      expect(new_relic_agent).not_to have_received(:record_custom_event)
+      expect(new_relic_agent).to have_received(:record_metric).with(
+        'Custom/Conversations/UnreadCounts/Filtered/snapshot_state/count',
+        1
+      )
+    end
+
+    it 'keeps custom events for invalidation signals' do
+      described_class.increment(:invalidation, account_id: 1, invalidation_scope: :conversation)
+
+      expect(new_relic_agent).to have_received(:record_custom_event).with(
+        'FilteredUnreadCounts',
+        hash_including(
+          account_id: 1,
+          invalidation_scope: 'conversation',
+          operation: 'invalidation'
+        )
+      )
+      expect(new_relic_agent).to have_received(:record_metric).with(
+        'Custom/Conversations/UnreadCounts/Filtered/invalidation/count',
+        1
+      )
+    end
+
+    it 'does not raise when New Relic is unavailable' do
+      allow(described_class).to receive(:new_relic_agent).and_return(nil)
+
+      expect { described_class.increment(:snapshot_state, account_id: 1) }.not_to raise_error
+    end
+  end
+
+  describe '.summarize_request' do
+    it 'records one custom event with aggregated request counters' do
+      result = described_class.summarize_request(account_id: 1) do
+        described_class.increment(:snapshot_state, account_id: 1, snapshot_scope: :built_in_filter, snapshot_status: :fresh)
+        described_class.increment(:snapshot_state, account_id: 1, snapshot_scope: :filter, snapshot_status: :missing)
+        described_class.increment(:refresh_claim, account_id: 1, snapshot_scope: :filter, claimed: true)
+        described_class.increment(:refresh_claim, account_id: 1, snapshot_scope: :filter, claimed: false)
+        described_class.increment(:build_lock, account_id: 1, snapshot_scope: :filter, acquired: true)
+        described_class.observe(:snapshot_build, account_id: 1, snapshot_scope: :filter) { 'built' }
+
+        'ok'
+      end
+
+      expect(result).to eq('ok')
+      expect(new_relic_agent).to have_received(:record_custom_event).once.with(
+        'FilteredUnreadCounts',
+        hash_including(
+          account_id: 1,
+          build_lock_acquired_count: 1,
+          duration_ms: kind_of(Float),
+          filter_build_lock_acquired_count: 1,
+          filter_refresh_claimed_count: 1,
+          filter_refresh_skipped_count: 1,
+          filter_snapshot_build_success_count: 1,
+          filter_snapshot_count: 1,
+          operation: 'request_summary',
+          refresh_claimed_count: 1,
+          refresh_skipped_count: 1,
+          snapshot_build_success_count: 1,
+          snapshot_fresh_count: 1,
+          snapshot_missing_count: 1,
+          snapshot_total_count: 2,
+          status: 'success'
+        )
+      )
+      expect(new_relic_agent).to have_received(:record_metric).with(
+        'Custom/Conversations/UnreadCounts/Filtered/api_response/duration_ms',
+        kind_of(Float)
+      )
+    end
+
+    it 'records summary errors and re-raises the original error' do
+      error = StandardError.new('boom')
+
+      expect do
+        described_class.summarize_request(account_id: 1) { raise error }
+      end.to raise_error(error)
+
+      expect(new_relic_agent).to have_received(:record_custom_event).with(
+        'FilteredUnreadCounts',
+        hash_including(
+          account_id: 1,
+          error_class: 'StandardError',
+          operation: 'request_summary',
+          status: 'error'
+        )
+      )
+    end
+  end
+end
diff --git a/spec/services/conversations/unread_counts/filtered_count_invalidator_spec.rb b/spec/services/conversations/unread_counts/filtered_count_invalidator_spec.rb
new file mode 100644
index 000000000..e0324c4b5
--- /dev/null
+++ b/spec/services/conversations/unread_counts/filtered_count_invalidator_spec.rb
@@ -0,0 +1,244 @@
+require 'rails_helper'
+
+RSpec.describe Conversations::UnreadCounts::FilteredCountInvalidator do
+  subject(:invalidator) { described_class.new(account) }
+
+  let(:account) { create(:account) }
+  let(:user) { create(:user, account: account) }
+  let(:other_user) { create(:user, account: account) }
+  let(:filter_id) { 123 }
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+  after do
+    redis_keys.each { |key| Redis::Alfred.delete(key) }
+  end
+
+  describe '#conversation_changed!' do
+    it 'bumps the account conversation version when the feature is enabled' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect { invalidator.conversation_changed! }.to change { store.conversation_version(account.id) }.by(1)
+    end
+
+    it 'records invalidation instrumentation when the feature is enabled' do
+      account.enable_features!(:unread_count_for_filters)
+      allow(Conversations::UnreadCounts::FilteredCountInstrumentation).to receive(:increment)
+
+      invalidator.conversation_changed!
+
+      expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:increment).with(
+        :invalidation,
+        account_id: account.id,
+        invalidation_scope: :conversation,
+        reason: :conversation_changed,
+        version: 1
+      )
+    end
+
+    it 'does not write Redis keys when the feature is disabled' do
+      expect { invalidator.conversation_changed! }.not_to(change { store.conversation_version(account.id) })
+    end
+  end
+
+  describe '#user_visibility_changed!' do
+    it 'bumps the user built-in filter version' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        invalidator.user_visibility_changed!(user_id: user.id)
+      end.to change { store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+    end
+  end
+
+  describe '#users_visibility_changed!' do
+    it 'pipelines built-in filter version bumps for multiple users' do
+      account.enable_features!(:unread_count_for_filters)
+      user_ids = [user.id, other_user.id]
+      allow(Redis::Alfred).to receive(:pipelined).and_call_original
+
+      expect do
+        invalidator.users_visibility_changed!(user_ids: user_ids + [user.id, nil])
+      end.to change { built_in_filter_version_for(user) }.by(1)
+                                                         .and change { built_in_filter_version_for(other_user) }.by(1)
+
+      expect(Redis::Alfred).to have_received(:pipelined).once
+    end
+
+    it 'does not write Redis keys when no user ids are present' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect(invalidator.users_visibility_changed!(user_ids: [nil, ''])).to be(false)
+    end
+  end
+
+  describe '#custom_filter_created!' do
+    it 'bumps the folder index and saved filter versions for conversation filters' do
+      account.enable_features!(:unread_count_for_filters)
+      filter_version = store.filter_version(account_id: account.id, filter_id: filter_id)
+
+      expect do
+        invalidator.custom_filter_created!(conversation_filter)
+      end.to change { store.folder_index_version(account_id: account.id, user_id: user.id) }.by(1)
+      expect(store.filter_version(account_id: account.id, filter_id: filter_id)).to eq(filter_version + 1)
+    end
+
+    it 'ignores non-conversation filters' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        invalidator.custom_filter_created!(conversation_filter(is_conversation: false))
+      end.not_to(change { store.folder_index_version(account_id: account.id, user_id: user.id) })
+    end
+  end
+
+  describe '#custom_filter_updated!' do
+    it 'bumps only the filter version when the query changes' do
+      account.enable_features!(:unread_count_for_filters)
+      filter = conversation_filter(previous_changes: { 'query' => [{ status: 'open' }, { status: 'resolved' }] })
+      folder_index_version = store.folder_index_version(account_id: account.id, user_id: user.id)
+
+      expect do
+        invalidator.custom_filter_updated!(filter)
+      end.to change { store.filter_version(account_id: account.id, filter_id: filter_id) }.by(1)
+      expect(store.folder_index_version(account_id: account.id, user_id: user.id)).to eq(folder_index_version)
+    end
+
+    it 'ignores name-only updates' do
+      account.enable_features!(:unread_count_for_filters)
+      filter = conversation_filter(previous_changes: { 'name' => %w[Open Resolved] })
+
+      expect do
+        invalidator.custom_filter_updated!(filter)
+      end.not_to(change { store.filter_version(account_id: account.id, filter_id: filter_id) })
+    end
+
+    it 'bumps versions and deletes the saved count when the filter moves away from conversations' do
+      account.enable_features!(:unread_count_for_filters)
+      filter = conversation_filter(
+        is_conversation: false,
+        previous_changes: { 'filter_type' => %w[conversation contact] }
+      )
+      store.write_filter_count!(
+        account_id: account.id,
+        filter_id: filter_id,
+        user_id: user.id,
+        count: 4,
+        account_version: 0,
+        filter_version: 0,
+        owner_built_in_filter_version: 0
+      )
+      filter_version = store.filter_version(account_id: account.id, filter_id: filter_id)
+
+      expect do
+        invalidator.custom_filter_updated!(filter)
+      end.to change { store.folder_index_version(account_id: account.id, user_id: user.id) }.by(1)
+      expect(store.filter_version(account_id: account.id, filter_id: filter_id)).to eq(filter_version + 1)
+      expect(store.filter_count(account_id: account.id, filter_id: filter_id)).to be_nil
+    end
+  end
+
+  describe '#custom_filter_destroyed!' do
+    it 'bumps the folder index version and deletes the saved count' do
+      account.enable_features!(:unread_count_for_filters)
+      store.write_filter_count!(
+        account_id: account.id,
+        filter_id: filter_id,
+        user_id: user.id,
+        count: 2,
+        account_version: 0,
+        filter_version: 0,
+        owner_built_in_filter_version: 0
+      )
+
+      expect do
+        invalidator.custom_filter_destroyed!(conversation_filter)
+      end.to change { store.folder_index_version(account_id: account.id, user_id: user.id) }.by(1)
+      expect(store.filter_count(account_id: account.id, filter_id: filter_id)).to be_nil
+    end
+  end
+
+  describe '#custom_attribute_definition_changed!' do
+    it 'bumps affected conversation saved filter versions' do
+      account.enable_features!(:unread_count_for_filters)
+      definition = create(:custom_attribute_definition, account: account, attribute_key: 'plan', attribute_model: 'conversation_attribute')
+      matching_filter = create(:custom_filter, account: account, user: user, query: custom_attribute_query('plan'))
+      blank_type_filter = create(:custom_filter, account: account, user: user, query: custom_attribute_query('plan', ''))
+      contact_filter = create(:custom_filter, account: account, user: user, query: custom_attribute_query('plan', 'contact_attribute'))
+      other_filter = create(:custom_filter, account: account, user: user, query: custom_attribute_query('tier'))
+      versions = filter_versions(matching_filter, blank_type_filter, contact_filter, other_filter)
+
+      invalidator.custom_attribute_definition_changed!(definition)
+
+      expect(store.filter_version(account_id: account.id, filter_id: matching_filter.id)).to eq(versions[matching_filter.id] + 1)
+      expect(store.filter_version(account_id: account.id, filter_id: blank_type_filter.id)).to eq(versions[blank_type_filter.id] + 1)
+      expect(store.filter_version(account_id: account.id, filter_id: contact_filter.id)).to eq(versions[contact_filter.id])
+      expect(store.filter_version(account_id: account.id, filter_id: other_filter.id)).to eq(versions[other_filter.id])
+    end
+
+    it 'bumps filters referencing the previous attribute key when the key changes' do
+      definition = create(:custom_attribute_definition, account: account, attribute_key: 'plan', attribute_model: 'conversation_attribute')
+      matching_filter = create(:custom_filter, account: account, user: user, query: custom_attribute_query('plan'))
+      version = store.filter_version(account_id: account.id, filter_id: matching_filter.id)
+
+      definition.update!(attribute_key: 'new_plan')
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        invalidator.custom_attribute_definition_changed!(definition)
+      end.to change { store.filter_version(account_id: account.id, filter_id: matching_filter.id) }.from(version).to(version + 1)
+    end
+  end
+
+  def conversation_filter(is_conversation: true, previous_changes: {})
+    instance_double(
+      CustomFilter,
+      id: filter_id,
+      user_id: user.id,
+      conversation?: is_conversation,
+      previous_changes: previous_changes
+    )
+  end
+
+  def custom_attribute_query(attribute_key, custom_attribute_type = 'conversation_attribute')
+    {
+      payload: [
+        {
+          attribute_key: attribute_key,
+          filter_operator: 'equal_to',
+          values: ['gold'],
+          custom_attribute_type: custom_attribute_type
+        }
+      ]
+    }
+  end
+
+  def filter_versions(*custom_filters)
+    custom_filters.to_h { |custom_filter| [custom_filter.id, store.filter_version(account_id: account.id, filter_id: custom_filter.id)] }
+  end
+
+  def built_in_filter_version_for(user)
+    store.built_in_filter_version(account_id: account.id, user_id: user.id)
+  end
+
+  def redis_keys
+    base_redis_keys + custom_filter_version_keys
+  end
+
+  def base_redis_keys
+    [
+      store.conversation_version_key(account.id),
+      *built_in_filter_version_keys,
+      store.folder_index_version_key(account.id, user.id),
+      store.filter_version_key(account.id, filter_id),
+      store.filter_count_key(account.id, filter_id)
+    ]
+  end
+
+  def built_in_filter_version_keys
+    [user.id, other_user.id].map { |user_id| store.built_in_filter_version_key(account.id, user_id) }
+  end
+
+  def custom_filter_version_keys
+    CustomFilter.where(account_id: account.id).pluck(:id).map { |id| store.filter_version_key(account.id, id) }
+  end
+end
diff --git a/spec/services/conversations/unread_counts/filtered_count_store_spec.rb b/spec/services/conversations/unread_counts/filtered_count_store_spec.rb
new file mode 100644
index 000000000..7732eb2dd
--- /dev/null
+++ b/spec/services/conversations/unread_counts/filtered_count_store_spec.rb
@@ -0,0 +1,262 @@
+require 'rails_helper'
+
+RSpec.describe Conversations::UnreadCounts::FilteredCountStore do
+  let(:account_id) { 1 }
+  let(:user_id) { 2 }
+  let(:filter_id) { 3 }
+  let(:built_at) { Time.zone.parse('2026-06-29 10:00:00 UTC') }
+
+  after do
+    redis_keys.each { |key| Redis::Alfred.delete(key) }
+  end
+
+  describe 'key builders' do
+    it 'builds V2 keys for built-in filters, folder indexes, and saved filters' do
+      expect(described_class.conversation_version_key(account_id)).to eq(
+        'UNREAD_CONVERSATIONS::V2::ACCOUNT::1::CONVERSATION_VERSION'
+      )
+      expect(described_class.built_in_filter_version_key(account_id, user_id)).to eq(
+        'UNREAD_CONVERSATIONS::V2::ACCOUNT::1::USER::2::BUILT_IN_FILTER_VERSION'
+      )
+      expect(described_class.built_in_filter_counts_key(account_id, user_id)).to eq(
+        'UNREAD_CONVERSATIONS::V2::ACCOUNT::1::USER::2::BUILT_IN_FILTER_COUNTS'
+      )
+      expect(described_class.folder_index_key(account_id, user_id)).to eq(
+        'UNREAD_CONVERSATIONS::V2::ACCOUNT::1::USER::2::FOLDER_INDEX'
+      )
+      expect(described_class.filter_count_key(account_id, filter_id)).to eq(
+        'UNREAD_CONVERSATIONS::V2::ACCOUNT::1::FILTER::3::COUNT'
+      )
+    end
+  end
+
+  describe 'version metadata' do
+    it 'defaults missing version keys to zero' do
+      expect(described_class.conversation_version(account_id)).to eq(0)
+      expect(described_class.built_in_filter_version(account_id: account_id, user_id: user_id)).to eq(0)
+      expect(described_class.folder_index_version(account_id: account_id, user_id: user_id)).to eq(0)
+      expect(described_class.filter_version(account_id: account_id, filter_id: filter_id)).to eq(0)
+    end
+
+    it 'increments independent version keys' do
+      expect(described_class.bump_conversation_version!(account_id)).to eq(1)
+      expect(described_class.bump_built_in_filter_version!(account_id: account_id, user_id: user_id)).to eq(1)
+      expect(described_class.bump_folder_index_version!(account_id: account_id, user_id: user_id)).to eq(1)
+      expect(described_class.bump_filter_version!(account_id: account_id, filter_id: filter_id)).to eq(1)
+    end
+
+    it 'increments and expires version keys in one Redis transaction' do
+      key = described_class.conversation_version_key(account_id)
+      connection = instance_double(Redis)
+      transaction = instance_double(Redis::MultiConnection)
+
+      allow(Redis::Alfred).to receive(:with).and_yield(connection)
+      expect(connection).to receive(:multi).and_yield(transaction).and_return([1, true])
+      expect(transaction).to receive(:incr).with(key)
+      expect(transaction).to receive(:expire).with(key, Conversations::UnreadCounts::FILTERED_COUNT_VERSION_TTL)
+
+      expect(described_class.bump_conversation_version!(account_id)).to eq(1)
+    end
+
+    it 'expires version keys after bumping them' do
+      described_class.bump_conversation_version!(account_id)
+      described_class.bump_built_in_filter_version!(account_id: account_id, user_id: user_id)
+      described_class.bump_folder_index_version!(account_id: account_id, user_id: user_id)
+      described_class.bump_filter_version!(account_id: account_id, filter_id: filter_id)
+
+      version_keys.each do |key|
+        expect(ttl_for(key)).to be_within(5).of(Conversations::UnreadCounts::FILTERED_COUNT_VERSION_TTL)
+      end
+    end
+  end
+
+  describe 'built-in filter count snapshots' do
+    it 'round-trips counts and classifies fresh, stale, expired, and missing snapshots' do
+      account_version = described_class.bump_conversation_version!(account_id)
+      built_in_filter_version = described_class.bump_built_in_filter_version!(account_id: account_id, user_id: user_id)
+
+      described_class.write_built_in_filter_counts!(
+        account_id: account_id,
+        user_id: user_id,
+        account_version: account_version,
+        built_in_filter_version: built_in_filter_version,
+        built_at: built_at,
+        counts: { mentions_count: 3, participating_count: 4, unattended_count: 5 },
+        meta: { permission_mode: 'base' }
+      )
+
+      snapshot = described_class.built_in_filter_counts(account_id: account_id, user_id: user_id)
+      expect(snapshot[:counts]).to eq(mentions_count: 3, participating_count: 4, unattended_count: 5)
+      expect(snapshot[:meta]).to eq(permission_mode: 'base')
+      expect(ttl_for(described_class.built_in_filter_counts_key(account_id, user_id))).to be_within(5).of(
+        Conversations::UnreadCounts::FILTERED_COUNT_REDIS_TTL
+      )
+
+      expect(described_class.built_in_filter_counts_state(account_id: account_id, user_id: user_id, now: built_at + 1.minute)).to be_fresh
+
+      described_class.bump_built_in_filter_version!(account_id: account_id, user_id: user_id)
+      expect(described_class.built_in_filter_counts_state(account_id: account_id, user_id: user_id, now: built_at + 2.minutes)).to be_stale
+      expect(described_class.built_in_filter_counts_state(account_id: account_id, user_id: user_id, now: built_at + 36.minutes)).to be_expired
+
+      Redis::Alfred.delete(described_class.built_in_filter_counts_key(account_id, user_id))
+      expect(described_class.built_in_filter_counts_state(account_id: account_id, user_id: user_id)).to be_missing
+    end
+  end
+
+  describe 'folder index snapshots' do
+    it 'round-trips folder ids and classifies freshness against the folder index version' do
+      folder_index_version = described_class.bump_folder_index_version!(account_id: account_id, user_id: user_id)
+
+      described_class.write_folder_index!(
+        account_id: account_id,
+        user_id: user_id,
+        folder_index_version: folder_index_version,
+        built_at: built_at,
+        filter_ids: %w[10 11]
+      )
+
+      expect(described_class.folder_index(account_id: account_id, user_id: user_id)[:filter_ids]).to eq([10, 11])
+      expect(described_class.folder_index_state(account_id: account_id, user_id: user_id, now: built_at + 1.minute)).to be_fresh
+
+      described_class.bump_folder_index_version!(account_id: account_id, user_id: user_id)
+      expect(described_class.folder_index_state(account_id: account_id, user_id: user_id, now: built_at + 2.minutes)).to be_stale
+    end
+  end
+
+  describe 'saved filter count snapshots' do
+    it 'round-trips counts and uses account, filter, and owner built-in filter versions for freshness' do
+      account_version = described_class.bump_conversation_version!(account_id)
+      filter_version = described_class.bump_filter_version!(account_id: account_id, filter_id: filter_id)
+      owner_built_in_filter_version = described_class.bump_built_in_filter_version!(account_id: account_id, user_id: user_id)
+
+      described_class.write_filter_count!(
+        account_id: account_id,
+        filter_id: filter_id,
+        user_id: user_id,
+        count: 7,
+        account_version: account_version,
+        filter_version: filter_version,
+        owner_built_in_filter_version: owner_built_in_filter_version,
+        built_at: built_at,
+        meta: { status: 'ok', timed_out: false, invalid_filter: false }
+      )
+
+      snapshot = described_class.filter_count(account_id: account_id, filter_id: filter_id)
+      expect(snapshot[:count]).to eq(7)
+      expect(snapshot[:meta]).to eq(status: 'ok', timed_out: false, invalid_filter: false)
+      expect(described_class.filter_count_state(account_id: account_id, filter_id: filter_id, now: built_at + 1.minute)).to be_fresh
+
+      described_class.bump_filter_version!(account_id: account_id, filter_id: filter_id)
+      expect(described_class.filter_count_state(account_id: account_id, filter_id: filter_id, now: built_at + 2.minutes)).to be_stale
+
+      described_class.delete_filter_count!(account_id: account_id, filter_id: filter_id)
+      expect(described_class.filter_count(account_id: account_id, filter_id: filter_id)).to be_nil
+    end
+
+    it 'uses caller-provided versions when classifying snapshots' do
+      account_version = described_class.bump_conversation_version!(account_id)
+      filter_version = described_class.bump_filter_version!(account_id: account_id, filter_id: filter_id)
+      owner_built_in_filter_version = described_class.bump_built_in_filter_version!(account_id: account_id, user_id: user_id)
+
+      described_class.write_filter_count!(
+        account_id: account_id,
+        filter_id: filter_id,
+        user_id: user_id,
+        count: 7,
+        account_version: account_version,
+        filter_version: filter_version,
+        owner_built_in_filter_version: owner_built_in_filter_version,
+        built_at: built_at
+      )
+
+      versions = {
+        account_version: account_version,
+        filter_version: filter_version,
+        owner_built_in_filter_version: owner_built_in_filter_version
+      }
+
+      expect(described_class).not_to receive(:conversation_version)
+      expect(described_class).not_to receive(:filter_version)
+      expect(described_class).not_to receive(:built_in_filter_version)
+
+      expect(
+        described_class.filter_count_state(
+          account_id: account_id,
+          filter_id: filter_id,
+          versions: versions,
+          now: built_at + 1.minute
+        )
+      ).to be_fresh
+    end
+  end
+
+  describe 'refresh throttles' do
+    it 'uses refresh_after and independent throttle keys to suppress duplicate rebuilds' do
+      described_class.write_built_in_filter_counts!(
+        account_id: account_id,
+        user_id: user_id,
+        account_version: 0,
+        built_in_filter_version: 0,
+        built_at: built_at,
+        counts: {}
+      )
+
+      snapshot = described_class.built_in_filter_counts(account_id: account_id, user_id: user_id)
+      expect(described_class.refresh_due?(snapshot, now: built_at + 10.seconds)).to be(false)
+      expect(described_class.refresh_due?(snapshot, now: built_at + 31.seconds)).to be(true)
+
+      expect(described_class.claim_built_in_filter_refresh!(account_id: account_id, user_id: user_id)).to be(true)
+      expect(described_class.claim_built_in_filter_refresh!(account_id: account_id, user_id: user_id)).to be(false)
+      expect(described_class.claim_folder_index_refresh!(account_id: account_id, user_id: user_id)).to be(true)
+      expect(described_class.claim_filter_refresh!(account_id: account_id, filter_id: filter_id)).to be(true)
+    end
+  end
+
+  describe 'Redis access pattern' do
+    it 'does not scan Redis keys' do
+      expect(Redis::Alfred).not_to receive(:scan_each)
+
+      described_class.bump_conversation_version!(account_id)
+      described_class.write_folder_index!(account_id: account_id, user_id: user_id, folder_index_version: 0, filter_ids: [filter_id])
+      described_class.folder_index_state(account_id: account_id, user_id: user_id)
+      described_class.claim_filter_refresh!(account_id: account_id, filter_id: filter_id)
+      described_class.delete_filter_count!(account_id: account_id, filter_id: filter_id)
+    end
+  end
+
+  def ttl_for(key)
+    Redis::Alfred.ttl(key)
+  end
+
+  def redis_keys
+    version_keys + snapshot_keys + lock_and_throttle_keys
+  end
+
+  def version_keys
+    [
+      described_class.conversation_version_key(account_id),
+      described_class.built_in_filter_version_key(account_id, user_id),
+      described_class.folder_index_version_key(account_id, user_id),
+      described_class.filter_version_key(account_id, filter_id)
+    ]
+  end
+
+  def snapshot_keys
+    [
+      described_class.built_in_filter_counts_key(account_id, user_id),
+      described_class.folder_index_key(account_id, user_id),
+      described_class.filter_count_key(account_id, filter_id)
+    ]
+  end
+
+  def lock_and_throttle_keys
+    [
+      described_class.built_in_filter_build_lock_key(account_id, user_id),
+      described_class.built_in_filter_refresh_throttle_key(account_id, user_id),
+      described_class.folder_index_build_lock_key(account_id, user_id),
+      described_class.folder_index_refresh_throttle_key(account_id, user_id),
+      described_class.filter_build_lock_key(account_id, filter_id),
+      described_class.filter_refresh_throttle_key(account_id, filter_id)
+    ]
+  end
+end
diff --git a/spec/services/conversations/unread_counts/filtered_counter_spec.rb b/spec/services/conversations/unread_counts/filtered_counter_spec.rb
new file mode 100644
index 000000000..bb5d419a6
--- /dev/null
+++ b/spec/services/conversations/unread_counts/filtered_counter_spec.rb
@@ -0,0 +1,549 @@
+require 'rails_helper'
+
+RSpec.describe Conversations::UnreadCounts::FilteredCounter do
+  subject(:counter) { described_class.new(account: account, user: agent, now: now) }
+
+  let(:account) { create(:account) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:visible_inbox) { create(:inbox, account: account) }
+  let(:hidden_inbox) { create(:inbox, account: account) }
+  let(:now) { Time.zone.parse('2026-06-29 10:00:00 UTC') }
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
+
+  before do
+    create(:inbox_member, user: agent, inbox: visible_inbox)
+  end
+
+  after do
+    redis_keys.each { |key| Redis::Alfred.delete(key) }
+  end
+
+  it 'builds built-in filter counts from unread open conversations visible to the user' do
+    mentioned = create_visible_unread_conversation
+    participating = create_visible_unread_conversation
+    create_visible_unread_conversation(unattended: true)
+    hidden_mention = create_unread_conversation(account: account, inbox: hidden_inbox)
+    resolved_mention = create_visible_unread_conversation(status: :resolved)
+    read_mention = create_visible_unread_conversation(agent_last_seen_at: 1.minute.from_now)
+
+    [mentioned, hidden_mention, resolved_mention, read_mention].each do |conversation|
+      create(:mention, account: account, conversation: conversation, user: agent)
+    end
+    create(:conversation_participant, account: account, conversation: participating, user: agent)
+
+    expect(counter.perform).to include(
+      mentions_count: 1,
+      participating_count: 1,
+      unattended_count: 1
+    )
+  end
+
+  it 'returns stale built-in counts until the refresh interval elapses' do
+    mentioned = create_visible_unread_conversation
+    create(:mention, account: account, conversation: mentioned, user: agent)
+
+    expect(counter.perform[:mentions_count]).to eq(1)
+
+    second_mention = create_visible_unread_conversation
+    create(:mention, account: account, conversation: second_mention, user: agent)
+    store.bump_conversation_version!(account.id)
+
+    expect(described_class.new(account: account, user: agent, now: now + 10.seconds).perform[:mentions_count]).to eq(1)
+
+    Redis::Alfred.delete(store.built_in_filter_refresh_throttle_key(account.id, agent.id))
+    expect(described_class.new(account: account, user: agent, now: now + 31.seconds).perform[:mentions_count]).to eq(2)
+  end
+
+  it 'returns stale built-in counts when a refresh build hits a database error' do
+    mentioned = create_visible_unread_conversation
+    create(:mention, account: account, conversation: mentioned, user: agent)
+
+    expect(counter.perform[:mentions_count]).to eq(1)
+
+    store.bump_conversation_version!(account.id)
+    Redis::Alfred.delete(store.built_in_filter_refresh_throttle_key(account.id, agent.id))
+    failing_counter = described_class.new(account: account, user: agent, now: now + 31.seconds)
+    allow(failing_counter).to receive(:built_in_counts_from_database).and_raise(ActiveRecord::StatementInvalid.new('statement timeout'))
+
+    expect(failing_counter.perform[:mentions_count]).to eq(1)
+  end
+
+  it 'tags built-in snapshots with versions captured before the DB read' do
+    race_counter = described_class.new(account: account, user: agent, now: now)
+    allow(race_counter).to receive(:built_in_counts_from_database) do
+      store.bump_conversation_version!(account.id)
+      { mentions_count: 1, participating_count: 0, unattended_count: 0 }
+    end
+
+    race_counter.perform
+
+    snapshot = store.built_in_filter_counts(account_id: account.id, user_id: agent.id)
+    expect(snapshot[:account_version]).to eq(0)
+    expect(store.built_in_filter_counts_state(account_id: account.id, user_id: agent.id, now: now)).to be_stale
+  end
+
+  it 'tags folder indexes with versions captured before the DB read' do
+    race_counter = described_class.new(account: account, user: agent, now: now)
+    allow(race_counter).to receive(:folder_filter_ids_from_database) do
+      store.bump_folder_index_version!(account_id: account.id, user_id: agent.id)
+      []
+    end
+
+    race_counter.send(:build_folder_index!, race_counter.send(:version_cache).folder_index)
+
+    snapshot = store.folder_index(account_id: account.id, user_id: agent.id)
+    expect(snapshot[:folder_index_version]).to eq(0)
+    expect(store.folder_index_state(account_id: account.id, user_id: agent.id, now: now)).to be_stale
+  end
+
+  it 'builds saved folder counts from unread conversations matching the saved filter query' do
+    resolved = create_visible_unread_conversation(status: :resolved)
+    create_visible_unread_conversation(status: :open)
+    hidden_resolved = create_unread_conversation(account: account, inbox: hidden_inbox)
+    hidden_resolved.update!(status: :resolved)
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'status', values: ['resolved'])
+    )
+
+    expect(counter.perform[:folders]).to eq(custom_filter.id.to_s => 1)
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)[:count]).to eq(1)
+    expect(resolved.reload.status).to eq('resolved')
+  end
+
+  it 'caps inline saved filter builds per request' do
+    create_visible_unread_conversation(status: :open)
+    max_inline_filter_builds = Conversations::UnreadCounts::MAX_INLINE_FILTER_BUILDS
+    custom_filters = Array.new(max_inline_filter_builds + 1) do
+      create(
+        :custom_filter,
+        account: account,
+        user: agent,
+        filter_type: :conversation,
+        query: filter_query(attribute_key: 'status', values: ['open'])
+      )
+    end
+    query_counter = instance_double(Conversations::UnreadCounts::FilterQueryCounter, perform: 1)
+    allow(Conversations::UnreadCounts::FilterQueryCounter).to receive(:new).and_return(query_counter)
+
+    result = counter.perform
+
+    expect(result[:folders].size).to eq(max_inline_filter_builds)
+    expect(Conversations::UnreadCounts::FilterQueryCounter).to have_received(:new).exactly(max_inline_filter_builds).times
+    expect(custom_filters.count { |custom_filter| store.filter_count(account_id: account.id, filter_id: custom_filter.id).present? }).to eq(
+      max_inline_filter_builds
+    )
+  end
+
+  it 'reuses shared versions while resolving multiple saved filters' do
+    create_visible_unread_conversation(status: :open)
+    2.times do
+      create(
+        :custom_filter,
+        account: account,
+        user: agent,
+        filter_type: :conversation,
+        query: filter_query(attribute_key: 'status', values: ['open'])
+      )
+    end
+    query_counter = instance_double(Conversations::UnreadCounts::FilterQueryCounter, perform: 1)
+    allow(Conversations::UnreadCounts::FilterQueryCounter).to receive(:new).and_return(query_counter)
+    expect(store).to receive(:conversation_version).with(account.id).once.and_call_original
+    expect(store).to receive(:built_in_filter_version).with(account_id: account.id, user_id: agent.id).once.and_call_original
+
+    expect(counter.perform[:folders].size).to eq(2)
+  end
+
+  it 'tags saved filter counts with versions captured before the DB read' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'status', values: ['open'])
+    )
+    race_counter = described_class.new(account: account, user: agent, now: now)
+    allow(race_counter).to receive(:filter_query_count) do
+      store.bump_filter_version!(account_id: account.id, filter_id: custom_filter.id)
+      1
+    end
+
+    race_counter.send(:build_filter_count!, custom_filter.id, race_counter.send(:version_cache).filter(custom_filter.id))
+
+    snapshot = store.filter_count(account_id: account.id, filter_id: custom_filter.id)
+    expect(snapshot[:filter_version]).to eq(0)
+    expect(store.filter_count_state(account_id: account.id, filter_id: custom_filter.id, owner_user_id: agent.id, now: now)).to be_stale
+  end
+
+  it 'tags saved filter counts with versions captured before loading the filter row' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'status', values: ['open'])
+    )
+    filters = account.custom_filters
+    allow(account).to receive(:custom_filters).and_return(filters)
+    allow(filters).to receive(:find_by) do
+      store.bump_filter_version!(account_id: account.id, filter_id: custom_filter.id)
+      custom_filter
+    end
+
+    counter.send(:build_filter_count!, custom_filter.id, counter.send(:version_cache).filter(custom_filter.id))
+
+    snapshot = store.filter_count(account_id: account.id, filter_id: custom_filter.id)
+    expect(snapshot[:filter_version]).to eq(0)
+    expect(store.filter_count_state(account_id: account.id, filter_id: custom_filter.id, owner_user_id: agent.id, now: now)).to be_stale
+  end
+
+  it 'omits invalid saved folders without writing a badge count' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'unknown_attribute', values: ['value'])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'records snapshot lifecycle instrumentation while calculating counts' do
+    allow(Conversations::UnreadCounts::FilteredCountInstrumentation).to receive(:observe) do |_operation, _attributes, &block|
+      block.call
+    end
+    allow(Conversations::UnreadCounts::FilteredCountInstrumentation).to receive(:increment)
+
+    counter.perform
+
+    expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:observe).with(:counter_perform, account_id: account.id)
+    expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:observe).with(
+      :snapshot_build,
+      account_id: account.id,
+      snapshot_scope: :built_in_filter
+    )
+    expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:increment).with(
+      :snapshot_state,
+      account_id: account.id,
+      snapshot_scope: :built_in_filter,
+      snapshot_status: :missing
+    )
+    expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:increment).with(
+      :refresh_claim,
+      account_id: account.id,
+      snapshot_scope: :built_in_filter,
+      claimed: true
+    )
+  end
+
+  it 'records acquired build locks when snapshot builds fail' do
+    error = StandardError.new('snapshot failed')
+    lock_manager = instance_double(Redis::LockManager)
+    resolver = Conversations::UnreadCounts::FilteredCountSnapshotResolver.new(
+      account: account,
+      now: now,
+      store: store,
+      lock_manager: lock_manager
+    )
+    state = Conversations::UnreadCounts::FilteredCountStore::SnapshotResult.new(status: :missing, payload: nil)
+
+    allow(lock_manager).to receive(:with_lock)
+      .with('lock-key', Conversations::UnreadCounts::FilteredCountSnapshotResolver::BUILD_LOCK_TTL)
+      .and_yield
+      .and_return(true)
+    allow(Conversations::UnreadCounts::FilteredCountInstrumentation).to receive(:observe) do |_operation, _attributes, &block|
+      block.call
+    end
+    allow(Conversations::UnreadCounts::FilteredCountInstrumentation).to receive(:increment)
+
+    expect do
+      resolver.resolve(scope: :built_in_filter, state: state, lock_key: 'lock-key', claim_refresh: -> { true }) { raise error }
+    end.to raise_error(error)
+    expect(Conversations::UnreadCounts::FilteredCountInstrumentation).to have_received(:increment).with(
+      :build_lock,
+      account_id: account.id,
+      snapshot_scope: :built_in_filter,
+      acquired: true
+    )
+  end
+
+  it 'omits saved folders with malformed query payloads' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'status', values: 'open')
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with trailing query operators' do
+    query = filter_query(attribute_key: 'status', values: ['open'])
+    query[:payload].first[:query_operator] = 'AND'
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: query
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with invalid typed values' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'team_id', values: ['abc'])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with invalid ID values' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'assignee_id', values: ['abc'])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'counts saved folders with display_id substring filters' do
+    conversation = create_visible_unread_conversation
+    create_visible_unread_conversation
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'display_id', filter_operator: 'contains', values: [conversation.display_id.to_s])
+    )
+
+    expect(counter.perform[:folders]).to eq(custom_filter.id.to_s => 1)
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)[:count]).to eq(1)
+  end
+
+  it 'counts saved folders with display_id text fragment filters' do
+    create_visible_unread_conversation
+    create_visible_unread_conversation
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'display_id', filter_operator: 'does_not_contain', values: ['abc'])
+    )
+
+    expect(counter.perform[:folders]).to eq(custom_filter.id.to_s => 2)
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)[:count]).to eq(2)
+  end
+
+  it 'omits saved folders with invalid typed custom attribute values' do
+    create(
+      :custom_attribute_definition,
+      account: account,
+      attribute_model: :conversation_attribute,
+      attribute_key: 'budget',
+      attribute_display_type: :number
+    )
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'budget', values: ['abc'])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with text operators on typed custom attributes' do
+    create(
+      :custom_attribute_definition,
+      account: account,
+      attribute_model: :conversation_attribute,
+      attribute_key: 'budget',
+      attribute_display_type: :number
+    )
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'budget', filter_operator: 'contains', values: ['123'])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with invalid label values' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'labels', values: [1])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with invalid text values' do
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'mail_subject', values: [1])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders with invalid date custom attribute values' do
+    create(
+      :custom_attribute_definition,
+      account: account,
+      attribute_model: :conversation_attribute,
+      attribute_key: 'renewal_on',
+      attribute_display_type: :date
+    )
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'renewal_on', values: ['not-a-date'])
+    )
+
+    expect(counter.perform[:folders]).to eq({})
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)).to be_nil
+  end
+
+  it 'omits saved folders when stored custom attribute values cannot be cast' do
+    create(
+      :custom_attribute_definition,
+      account: account,
+      attribute_model: :conversation_attribute,
+      attribute_key: 'budget',
+      attribute_display_type: :number
+    )
+    query_counter = Conversations::UnreadCounts::FilterQueryCounter.new(
+      account: account,
+      user: agent,
+      query: filter_query(attribute_key: 'budget', filter_operator: 'is_present', values: [])
+    )
+    relation = instance_double(ActiveRecord::Relation)
+    cast_error = ActiveRecord::StatementInvalid.new('PG::InvalidTextRepresentation: invalid input syntax for type numeric')
+    allow(cast_error).to receive(:cause).and_return(PG::InvalidTextRepresentation.new('invalid input syntax for type numeric'))
+    allow(query_counter).to receive(:query_builder).and_return(relation)
+    allow(relation).to receive(:count).and_raise(cast_error)
+
+    expect(query_counter.perform).to be_nil
+  end
+
+  it 'counts saved folders with days_before date filters' do
+    old_conversation = create_visible_unread_conversation
+    old_conversation.update!(created_at: 8.days.ago)
+    create_visible_unread_conversation
+    custom_filter = create(
+      :custom_filter,
+      account: account,
+      user: agent,
+      filter_type: :conversation,
+      query: filter_query(attribute_key: 'created_at', filter_operator: 'days_before', values: [7])
+    )
+
+    expect(counter.perform[:folders]).to eq(custom_filter.id.to_s => 1)
+    expect(store.filter_count(account_id: account.id, filter_id: custom_filter.id)[:count]).to eq(1)
+  end
+
+  def create_visible_unread_conversation(status: :open, agent_last_seen_at: 1.hour.ago, unattended: false)
+    conversation = create_unread_conversation(account: account, inbox: visible_inbox)
+    conversation.update!(
+      status: status,
+      agent_last_seen_at: agent_last_seen_at,
+      first_reply_created_at: unattended ? nil : Time.current,
+      waiting_since: unattended ? 5.minutes.ago : nil
+    )
+    conversation
+  end
+
+  def filter_query(attribute_key:, values:, filter_operator: 'equal_to')
+    {
+      payload: [{
+        attribute_key: attribute_key,
+        attribute_model: 'standard',
+        filter_operator: filter_operator,
+        values: values
+      }]
+    }
+  end
+
+  def redis_keys
+    version_keys + snapshot_keys + lock_and_throttle_keys
+  end
+
+  def filter_ids
+    CustomFilter.where(account_id: account.id).pluck(:id)
+  end
+
+  def version_keys
+    [
+      store.conversation_version_key(account.id),
+      store.built_in_filter_version_key(account.id, agent.id),
+      store.folder_index_version_key(account.id, agent.id)
+    ] + filter_ids.map { |filter_id| store.filter_version_key(account.id, filter_id) }
+  end
+
+  def snapshot_keys
+    [
+      store.built_in_filter_counts_key(account.id, agent.id),
+      store.folder_index_key(account.id, agent.id)
+    ] + filter_ids.map { |filter_id| store.filter_count_key(account.id, filter_id) }
+  end
+
+  def lock_and_throttle_keys
+    user_lock_and_throttle_keys + filter_lock_and_throttle_keys
+  end
+
+  def user_lock_and_throttle_keys
+    [
+      store.built_in_filter_build_lock_key(account.id, agent.id),
+      store.built_in_filter_refresh_throttle_key(account.id, agent.id),
+      store.folder_index_build_lock_key(account.id, agent.id),
+      store.folder_index_refresh_throttle_key(account.id, agent.id)
+    ]
+  end
+
+  def filter_lock_and_throttle_keys
+    filter_ids.flat_map do |filter_id|
+      [
+        store.filter_build_lock_key(account.id, filter_id),
+        store.filter_refresh_throttle_key(account.id, filter_id)
+      ]
+    end
+  end
+end
diff --git a/spec/services/conversations/unread_counts/listener_spec.rb b/spec/services/conversations/unread_counts/listener_spec.rb
index fbb0a0835..f13f70ce0 100644
--- a/spec/services/conversations/unread_counts/listener_spec.rb
+++ b/spec/services/conversations/unread_counts/listener_spec.rb
@@ -5,6 +5,7 @@ RSpec.describe Conversations::UnreadCounts::Listener do
   let(:account) { create(:account) }
   let(:conversation) { create(:conversation, account: account) }
   let(:notifier) { instance_double(Conversations::UnreadCounts::Notifier, perform: true) }
+  let(:filtered_store) { Conversations::UnreadCounts::FilteredCountStore }
 
   before do
     allow(Conversations::UnreadCounts::Notifier).to receive(:new).and_return(notifier)
@@ -21,6 +22,19 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     expect(notifier).to have_received(:perform)
   end
 
+  it 'refreshes unread count memberships before invalidating filtered counts when an incoming message is created' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    message = create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :incoming)
+    event = Events::Base.new('message.created', Time.zone.now, message: message)
+    invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator)
+
+    allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+    expect(notifier).to receive(:perform).ordered.and_return(true)
+    expect(invalidator).to receive(:conversation_changed!).ordered.and_return(true)
+
+    listener.message_created(event)
+  end
+
   it 'ignores outgoing message creation' do
     message = create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :outgoing)
     event = Events::Base.new('message.created', Time.zone.now, message: message)
@@ -41,6 +55,32 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     expect(Conversations::UnreadCounts::Notifier).not_to have_received(:new)
   end
 
+  it 'invalidates filtered counts when any message is created' do
+    account.enable_features!(:unread_count_for_filters)
+    message = create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :outgoing)
+    event = Events::Base.new('message.created', Time.zone.now, message: message)
+
+    expect do
+      listener.message_created(event)
+    end.to change { filtered_store.conversation_version(account.id) }.by(1)
+    expect(Conversations::UnreadCounts::Notifier).not_to have_received(:new)
+  end
+
+  it 'notifies clients when outgoing message activity changes filtered counts' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    message = create(:message, account: account, inbox: conversation.inbox, conversation: conversation, message_type: :outgoing)
+    event = Events::Base.new('message.created', Time.zone.now, message: message)
+
+    listener.message_created(event)
+
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation: conversation
+    )
+  end
+
   it 'refreshes unread counts when conversation status changes' do
     changed_attributes = { 'status' => %w[open resolved] }
     event = Events::Base.new('conversation.status_changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
@@ -51,6 +91,45 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     expect(notifier).to have_received(:perform)
   end
 
+  it 'refreshes unread count memberships before invalidating filtered counts when conversation status changes' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    changed_attributes = { 'status' => %w[open resolved] }
+    event = Events::Base.new('conversation.status_changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
+    invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator)
+
+    allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+    expect(notifier).to receive(:perform).ordered.and_return(true)
+    expect(invalidator).to receive(:conversation_changed!).ordered.and_return(true)
+
+    listener.conversation_status_changed(event)
+  end
+
+  it 'invalidates filtered counts when conversation status changes' do
+    account.enable_features!(:unread_count_for_filters)
+    changed_attributes = { 'status' => %w[open resolved] }
+    event = Events::Base.new('conversation.status_changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
+
+    expect do
+      listener.conversation_status_changed(event)
+    end.to change { filtered_store.conversation_version(account.id) }.by(1)
+  end
+
+  it 'notifies clients when a status change only affects filtered counts' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    allow(notifier).to receive(:perform).and_return(false)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    changed_attributes = { 'status' => %w[pending resolved] }
+    event = Events::Base.new('conversation.status_changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
+
+    listener.conversation_status_changed(event)
+
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation: conversation
+    )
+  end
+
   it 'refreshes unread counts when labels change' do
     changed_attributes = { label_list: [%w[old], %w[new]] }
     event = Events::Base.new('conversation.updated', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
@@ -61,14 +140,61 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     expect(notifier).to have_received(:perform)
   end
 
-  it 'ignores conversation updates unrelated to unread count dimensions' do
+  it 'does not invalidate filtered counts from conversation updated events' do
+    account.enable_features!(:unread_count_for_filters)
+    event = Events::Base.new('conversation.updated', Time.zone.now, conversation: conversation, changed_attributes: { priority: [nil, 'high'] })
+
+    expect do
+      listener.conversation_updated(event)
+    end.not_to(change { filtered_store.conversation_version(account.id) })
+    expect(Conversations::UnreadCounts::Notifier).not_to have_received(:new)
+  end
+
+  it 'notifies clients when filtered conversation fields change' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
     event = Events::Base.new('conversation.updated', Time.zone.now, conversation: conversation, changed_attributes: { priority: [nil, 'high'] })
 
     listener.conversation_updated(event)
 
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation: conversation
+    )
+  end
+
+  it 'ignores conversation updates unrelated to unread count dimensions' do
+    event = Events::Base.new('conversation.updated', Time.zone.now, conversation: conversation, changed_attributes: { identifier: %w[old new] })
+
+    listener.conversation_updated(event)
+
     expect(Conversations::UnreadCounts::Notifier).not_to have_received(:new)
   end
 
+  it 'invalidates filtered counts when the conversation contact changes' do
+    account.enable_features!(:unread_count_for_filters)
+    event = Events::Base.new('conversation.contact_changed', Time.zone.now, conversation: conversation)
+
+    expect do
+      listener.conversation_contact_changed(event)
+    end.to change { filtered_store.conversation_version(account.id) }.by(1)
+  end
+
+  it 'notifies clients when the conversation contact changes' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    event = Events::Base.new('conversation.contact_changed', Time.zone.now, conversation: conversation)
+
+    listener.conversation_contact_changed(event)
+
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation: conversation
+    )
+  end
+
   it 'refreshes unread counts when assignee changes' do
     changed_attributes = { assignee_id: [nil, 1] }
     event = Events::Base.new('assignee.changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
@@ -79,6 +205,45 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     expect(notifier).to have_received(:perform)
   end
 
+  it 'notifies clients when an assignee change only affects filtered counts' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    allow(notifier).to receive(:perform).and_return(false)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    changed_attributes = { assignee_id: [nil, 1] }
+    event = Events::Base.new('assignee.changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
+
+    listener.assignee_changed(event)
+
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation: conversation
+    )
+  end
+
+  it 'refreshes unread count memberships before invalidating filtered counts when assignee changes' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    changed_attributes = { assignee_id: [nil, 1] }
+    event = Events::Base.new('assignee.changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
+    invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator)
+
+    allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+    expect(notifier).to receive(:perform).ordered.and_return(true)
+    expect(invalidator).to receive(:conversation_changed!).ordered.and_return(true)
+
+    listener.assignee_changed(event)
+  end
+
+  it 'invalidates filtered counts when a user is mentioned' do
+    account.enable_features!(:unread_count_for_filters)
+    user = create(:user, account: account)
+    event = Events::Base.new('conversation.mentioned', Time.zone.now, conversation: conversation, user: user)
+
+    expect do
+      listener.conversation_mentioned(event)
+    end.to change { filtered_store.built_in_filter_version(account_id: account.id, user_id: user.id) }.by(1)
+  end
+
   it 'refreshes unread counts when team changes' do
     changed_attributes = { team_id: [nil, 1] }
     event = Events::Base.new('team.changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
@@ -89,6 +254,47 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     expect(notifier).to have_received(:perform)
   end
 
+  it 'notifies clients when a team change only affects filtered counts' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    allow(notifier).to receive(:perform).and_return(false)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    changed_attributes = { team_id: [nil, 1] }
+    event = Events::Base.new('team.changed', Time.zone.now, conversation: conversation, changed_attributes: changed_attributes)
+
+    listener.team_changed(event)
+
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation: conversation
+    )
+  end
+
+  it 'invalidates filtered counts when a conversation is deleted' do
+    account.enable_features!(:unread_count_for_filters)
+    conversation_data = deleted_conversation_data(conversation)
+
+    expect do
+      listener.conversation_deleted(Events::Base.new('conversation.deleted', Time.zone.now, conversation_data: conversation_data))
+    end.to change { filtered_store.conversation_version(account.id) }.by(1)
+  end
+
+  it 'notifies clients when a deleted conversation only affects filtered counts' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    conversation_data = deleted_conversation_data(conversation)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+
+    listener.conversation_deleted(Events::Base.new('conversation.deleted', Time.zone.now, conversation_data: conversation_data))
+
+    expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+      'conversation.unread_count_changed',
+      kind_of(Time),
+      conversation_data: conversation_data.stringify_keys
+    )
+  ensure
+    store.clear_account!(account.id)
+  end
+
   it 'removes unread count memberships when a conversation is deleted' do
     account.enable_features!(:conversation_unread_counts)
     label = create(:label, account: account)
@@ -131,6 +337,29 @@ RSpec.describe Conversations::UnreadCounts::Listener do
     store.clear_account!(account.id)
   end
 
+  it 'removes unread count memberships before invalidating filtered counts when a conversation is deleted' do
+    account.enable_features!(:conversation_unread_counts, :unread_count_for_filters)
+    conversation_data = deleted_conversation_data(conversation)
+    invalidator = instance_double(Conversations::UnreadCounts::FilteredCountInvalidator)
+
+    store.mark_base_ready!(account.id)
+    store.add_base_membership(
+      account_id: account.id,
+      inbox_id: conversation.inbox_id,
+      label_ids: [],
+      conversation_id: conversation.id
+    )
+
+    allow(Conversations::UnreadCounts::FilteredCountInvalidator).to receive(:new).with(account).and_return(invalidator)
+    allow(Rails.configuration.dispatcher).to receive(:dispatch)
+    expect(store).to receive(:remove_base_membership).ordered.and_call_original
+    expect(invalidator).to receive(:conversation_changed!).ordered.and_return(true)
+
+    listener.conversation_deleted(Events::Base.new('conversation.deleted', Time.zone.now, conversation_data: conversation_data))
+  ensure
+    store.clear_account!(account.id)
+  end
+
   def deleted_conversation_data(conversation)
     {
       id: conversation.id,
diff --git a/spec/services/conversations/unread_counts/notifier_spec.rb b/spec/services/conversations/unread_counts/notifier_spec.rb
index 1b35d37f6..a8c46be0c 100644
--- a/spec/services/conversations/unread_counts/notifier_spec.rb
+++ b/spec/services/conversations/unread_counts/notifier_spec.rb
@@ -29,6 +29,18 @@ RSpec.describe Conversations::UnreadCounts::Notifier do
 
       expect(Rails.configuration.dispatcher).not_to have_received(:dispatch)
     end
+
+    it 'dispatches unread count changed event when filtered counts are enabled' do
+      conversation.account.enable_features!(:unread_count_for_filters)
+
+      described_class.new(conversation).perform
+
+      expect(Rails.configuration.dispatcher).to have_received(:dispatch).with(
+        'conversation.unread_count_changed',
+        kind_of(Time),
+        conversation: conversation
+      )
+    end
   end
 
   context 'when conversation unread counts feature is disabled' do
diff --git a/spec/services/labels/destroy_service_spec.rb b/spec/services/labels/destroy_service_spec.rb
index 7d06b72d0..7f14273b3 100644
--- a/spec/services/labels/destroy_service_spec.rb
+++ b/spec/services/labels/destroy_service_spec.rb
@@ -6,6 +6,7 @@ describe Labels::DestroyService do
   let(:label) { create(:label, account: account) }
   let(:contact) { conversation.contact }
   let(:label_deleted_at) { Time.zone.parse('2026-05-07 10:00:00 UTC') }
+  let(:store) { Conversations::UnreadCounts::FilteredCountStore }
 
   before do
     conversation.label_list.add(label.title)
@@ -74,6 +75,18 @@ describe Labels::DestroyService do
       ).perform
     end
 
+    it 'invalidates filtered counts when conversation label associations are removed' do
+      account.enable_features!(:unread_count_for_filters)
+
+      expect do
+        described_class.new(
+          label_title: label.title,
+          account_id: account.id,
+          label_deleted_at: label_deleted_at
+        ).perform
+      end.to change { store.conversation_version(account.id) }.by(1)
+    end
+
     it 'does not remove label associations created after the label was deleted' do
       other_conversation = create(:conversation, account: account)
       other_conversation.label_list.add(label.title)

From 4854fb7b4b4155f84df883b0d6a197a33cff324c Mon Sep 17 00:00:00 2001
From: Sony Mathew <sony@chatwoot.com>
Date: Thu, 9 Jul 2026 04:22:40 +0530
Subject: [PATCH 16/17] chore: upgrade websocket-driver (#14961)

# Pull Request Template

## Description

Updates `websocket-driver` from `0.7.7` to `0.8.2` to resolve the
bundle-audit findings for CVE-2026-54463, CVE-2026-54464,
CVE-2026-54465, and GHSA-2x63-gw47-w4mm.

This is a lockfile-only transitive dependency update through Rails
Action Cable. No application code changes are included.

Fixes # (issue)
N/A

## Type of change

- [x] Bug fix (non-breaking change which fixes an issue)

## How Has This Been Tested?

- `bundle exec bundle audit update && bundle exec bundle audit check -v`
- `bundle check && bundle exec ruby -e 'require "action_cable"; require
"action_cable/connection/client_socket"; require "websocket/driver";
puts "actioncable=#{ActionCable::VERSION::STRING}"; puts
"websocket-driver=#{Gem.loaded_specs["websocket-driver"].version}"; puts
"driver_rack=#{WebSocket::Driver.respond_to?(:rack)}"'`
- `POSTGRES_DATABASE=chatwoot_test_3d6a RAILS_ENV=test bundle exec rails
db:prepare && POSTGRES_DATABASE=chatwoot_test_3d6a bundle exec rspec
spec/listeners/action_cable_listener_spec.rb`
- `git diff --check`

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas (not applicable; lockfile-only change)
- [ ] I have made corresponding changes to the documentation (not
applicable; dependency security update)
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works (not applicable; dependency security update)
- [x] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules (not applicable)
---
 Gemfile.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index bd41474a3..68674155e 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1030,7 +1030,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    websocket-driver (0.7.7)
+    websocket-driver (0.8.2)
       base64
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)

From 8d554f2b74e0f01c94e5f2e121e0fb8c5187e6fc Mon Sep 17 00:00:00 2001
From: Muhsin Keloth <muhsinkeramam@gmail.com>
Date: Thu, 9 Jul 2026 10:02:02 +0400
Subject: [PATCH 17/17] chore(inbox): disable Instagram inbox creation (#14964)

Reverts chatwoot/chatwoot#14955
---
 .../dashboard/components/widgets/ChannelItem.vue         | 9 ++++++---
 app/javascript/dashboard/constants/globals.js            | 7 ++++---
 .../dashboard/onboarding/inbox-setup/useChannelConfig.js | 8 +++++---
 .../specs/inbox-setup/useDetectedChannels.spec.js        | 6 +++---
 .../dashboard/settings/inbox/channels/Whatsapp.vue       | 4 ++--
 5 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/app/javascript/dashboard/components/widgets/ChannelItem.vue b/app/javascript/dashboard/components/widgets/ChannelItem.vue
index c084d6086..2652b582b 100644
--- a/app/javascript/dashboard/components/widgets/ChannelItem.vue
+++ b/app/javascript/dashboard/components/widgets/ChannelItem.vue
@@ -1,7 +1,7 @@
 <script setup>
 import { computed } from 'vue';
 import ChannelSelector from '../ChannelSelector.vue';
-import { IS_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
+import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 const props = defineProps({
   channel: {
@@ -21,7 +21,10 @@ const hasFbConfigured = computed(() => {
 });
 
 const hasInstagramConfigured = computed(() => {
-  return window.chatwootConfig?.instagramAppId;
+  return (
+    !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+    window.chatwootConfig?.instagramAppId
+  );
 });
 
 const hasTiktokConfigured = computed(() => {
@@ -59,7 +62,7 @@ const isActive = computed(() => {
 
   if (key === 'whatsapp_call') {
     return (
-      !IS_WHATSAPP_INBOX_CREATION_DISABLED &&
+      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
       props.enabledFeatures.channel_voice &&
       !!window.chatwootConfig?.whatsappAppId &&
       window.chatwootConfig.whatsappAppId !== 'none'
diff --git a/app/javascript/dashboard/constants/globals.js b/app/javascript/dashboard/constants/globals.js
index bb602e751..717e5104f 100644
--- a/app/javascript/dashboard/constants/globals.js
+++ b/app/javascript/dashboard/constants/globals.js
@@ -79,6 +79,7 @@ export default {
 };
 export const DEFAULT_REDIRECT_URL = '/app/';
 
-// Temporarily disables WhatsApp embedded signup and WhatsApp Call inbox
-// creation. Flip to false when the channel is brought back.
-export const IS_WHATSAPP_INBOX_CREATION_DISABLED = true;
+// Temporarily disables Instagram and WhatsApp inbox creation
+// (WhatsApp embedded signup popup, Instagram OAuth, WhatsApp Call).
+// Flip to false when the channels are brought back.
+export const IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED = true;
diff --git a/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js b/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
index 32b3904de..9618c5e44 100644
--- a/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
+++ b/app/javascript/dashboard/routes/dashboard/onboarding/inbox-setup/useChannelConfig.js
@@ -1,5 +1,5 @@
 import { useMapGetter } from 'dashboard/composables/store';
-import { IS_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
+import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 // OAuth/SDK channels need installation-level app credentials to be usable. When
 // the credential is missing the channel is "not configured" and is hidden from
@@ -14,12 +14,14 @@ export function useChannelConfig() {
     // WhatsApp is onboarded only via Meta embedded signup, which needs both the
     // app id (not the 'none' sentinel) and the signup configuration id.
     whatsapp: () =>
-      !IS_WHATSAPP_INBOX_CREATION_DISABLED &&
+      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
       Boolean(installationConfig.whatsappAppId) &&
       installationConfig.whatsappAppId !== 'none' &&
       Boolean(installationConfig.whatsappConfigurationId),
     facebook: () => Boolean(installationConfig.fbAppId),
-    instagram: () => Boolean(installationConfig.instagramAppId),
+    instagram: () =>
+      !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
+      Boolean(installationConfig.instagramAppId),
     tiktok: () => Boolean(installationConfig.tiktokAppId),
     gmail: () => Boolean(installationConfig.googleOAuthClientId),
     outlook: () => Boolean(globalConfig.value.azureAppId),
diff --git a/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js b/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
index d130a3712..875bfaf0d 100644
--- a/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
+++ b/app/javascript/dashboard/routes/dashboard/onboarding/specs/inbox-setup/useDetectedChannels.spec.js
@@ -6,11 +6,11 @@ import { useDetectedChannels } from '../../inbox-setup/useDetectedChannels';
 
 vi.mock('vue-router');
 
-// Neutralize the temporary WhatsApp kill switch so these specs keep covering
-// the credential-based gating it short-circuits.
+// Neutralize the temporary Instagram/WhatsApp kill switch so these specs keep
+// covering the credential-based gating it currently short-circuits.
 vi.mock('dashboard/constants/globals', async importOriginal => ({
   ...(await importOriginal()),
-  IS_WHATSAPP_INBOX_CREATION_DISABLED: false,
+  IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED: false,
 }));
 
 // Mounts the composable against a real store and the real useAccount (only
diff --git a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
index 9436ccc2a..98cc90fee 100644
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue
@@ -7,7 +7,7 @@ import ThreeSixtyDialogWhatsapp from './360DialogWhatsapp.vue';
 import CloudWhatsapp from './CloudWhatsapp.vue';
 import WhatsappEmbeddedSignup from './WhatsappEmbeddedSignup.vue';
 import ChannelSelector from 'dashboard/components/ChannelSelector.vue';
-import { IS_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
+import { IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED } from 'dashboard/constants/globals';
 
 const route = useRoute();
 const router = useRouter();
@@ -24,7 +24,7 @@ const PROVIDER_TYPES = {
 
 const hasWhatsappAppId = computed(() => {
   return (
-    !IS_WHATSAPP_INBOX_CREATION_DISABLED &&
+    !IS_INSTAGRAM_WHATSAPP_INBOX_CREATION_DISABLED &&
     window.chatwootConfig?.whatsappAppId &&
     window.chatwootConfig.whatsappAppId !== 'none'
   );