Merge branch 'develop' into fix/audio-retry

2026-06-16 13:53:43 +04:00
parent f4c3f5095e de137e8297
commit e82dca9b79
2190 changed files with 121009 additions and 19124 deletions
@@ -23,9 +23,15 @@ export function useBulkActions() {

  function deSelectConversation(conversationId, inboxId) {
    store.dispatch('bulkActions/removeSelectedConversationIds', conversationId);
-    selectedInboxes.value = selectedInboxes.value.filter(
-      item => item !== inboxId
-    );
+    // Only remove one instance of the inboxId, not all
+    // This handles the case where multiple conversations from the same inbox are selected
+    const index = selectedInboxes.value.indexOf(inboxId);
+    if (index > -1) {
+      selectedInboxes.value = [
+        ...selectedInboxes.value.slice(0, index),
+        ...selectedInboxes.value.slice(index + 1),
+      ];
+    }
  }

  function resetBulkActions() {
@@ -102,7 +108,7 @@ export function useBulkActions() {
    }
  }

-  // Only used in context menu
+  // Used by both context menu and bulk action bar.
  async function onRemoveLabels(labelsToRemove, conversationId = null) {
    try {
      await store.dispatch('bulkActions/process', {
@@ -113,14 +119,24 @@ export function useBulkActions() {
        },
      });

-      useAlert(
-        t('CONVERSATION.CARD_CONTEXT_MENU.API.LABEL_REMOVAL.SUCCESFUL', {
-          labelName: labelsToRemove[0],
-          conversationId,
-        })
-      );
+      // Context-menu remove should not disturb an existing bulk selection.
+      if (conversationId) {
+        useAlert(
+          t('CONVERSATION.CARD_CONTEXT_MENU.API.LABEL_REMOVAL.SUCCESFUL', {
+            labelName: labelsToRemove[0],
+            conversationId,
+          })
+        );
+      } else {
+        store.dispatch('bulkActions/clearSelectedConversationIds');
+        useAlert(t('BULK_ACTION.LABELS.REMOVE_SUCCESFUL'));
+      }
    } catch (err) {
-      useAlert(t('CONVERSATION.CARD_CONTEXT_MENU.API.LABEL_REMOVAL.FAILED'));
+      useAlert(
+        conversationId
+          ? t('CONVERSATION.CARD_CONTEXT_MENU.API.LABEL_REMOVAL.FAILED')
+          : t('BULK_ACTION.LABELS.REMOVE_FAILED')
+      );
    }
  }

@@ -141,6 +157,8 @@ export function useBulkActions() {
  }

  async function onUpdateConversations(status, snoozedUntil) {
+    if (selectedConversations.value.length === 0) return;
+
    let conversationIds = selectedConversations.value;
    let skippedCount = 0;

@@ -10,10 +10,12 @@ vi.mock('shared/helpers/mitt', () => ({

 vi.mock('dashboard/helper/AnalyticsHelper/index', async importOriginal => {
  const actual = await importOriginal();
-  actual.default = {
-    track: vi.fn(),
+  return {
+    ...actual,
+    default: {
+      track: vi.fn(),
+    },
  };
-  return actual;
 });

 describe('useTrack', () => {
@@ -16,10 +16,12 @@ vi.mock('vue-i18n');
 vi.mock('dashboard/api/captain/tasks');
 vi.mock('dashboard/helper/AnalyticsHelper/index', async importOriginal => {
  const actual = await importOriginal();
-  actual.default = {
-    track: vi.fn(),
+  return {
+    ...actual,
+    default: {
+      track: vi.fn(),
+    },
  };
-  return actual;
 });
 vi.mock('dashboard/helper/AnalyticsHelper/events', () => ({
  CAPTAIN_EVENTS: {
@@ -0,0 +1,149 @@
+import { useFacebookPageConnect } from '../useFacebookPageConnect';
+import { useMapGetter } from 'dashboard/composables/store';
+import ChannelApi from 'dashboard/api/channels';
+import { setupFacebookSdk } from 'dashboard/routes/dashboard/settings/inbox/channels/whatsapp/utils';
+
+vi.mock('dashboard/composables/store', () => ({ useMapGetter: vi.fn() }));
+vi.mock('dashboard/api/channels', () => ({
+  default: { fetchFacebookPages: vi.fn() },
+}));
+vi.mock(
+  'dashboard/routes/dashboard/settings/inbox/channels/whatsapp/utils',
+  () => ({ setupFacebookSdk: vi.fn() })
+);
+
+const flushPromises = () =>
+  new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+
+const createDeferred = () => {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+
+const ACCOUNT_ID = 42;
+const PAGES = [
+  { id: 'p1', name: 'Page One', access_token: 'page-token-1' },
+  { id: 'p2', name: 'Page Two', access_token: 'page-token-2', exists: true },
+];
+
+const pagesResponse = {
+  data: { data: { page_details: PAGES, user_access_token: 'long-token' } },
+};
+
+// FB.login invokes its callback with the given response.
+const stubLogin = response => {
+  window.FB = { login: vi.fn(callback => callback(response)) };
+};
+
+const connected = {
+  status: 'connected',
+  authResponse: { accessToken: 'user-token' },
+};
+
+describe('useFacebookPageConnect', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    window.chatwootConfig = { fbAppId: 'fb-app', fbApiVersion: 'v22.0' };
+    useMapGetter.mockReturnValue({ value: ACCOUNT_ID });
+    setupFacebookSdk.mockResolvedValue();
+    ChannelApi.fetchFacebookPages.mockResolvedValue(pagesResponse);
+    stubLogin(connected);
+  });
+
+  it('resolves the user token and pages on a connected login', async () => {
+    const { loginAndFetchPages } = useFacebookPageConnect();
+
+    await expect(loginAndFetchPages()).resolves.toEqual({
+      userAccessToken: 'long-token',
+      pages: PAGES,
+    });
+    expect(setupFacebookSdk).toHaveBeenCalledWith('fb-app', 'v22.0');
+    expect(ChannelApi.fetchFacebookPages).toHaveBeenCalledWith(
+      'user-token',
+      ACCOUNT_ID
+    );
+    expect(window.FB.login).toHaveBeenCalledWith(expect.any(Function), {
+      scope:
+        'pages_manage_metadata,business_management,pages_messaging,pages_show_list,pages_read_engagement',
+    });
+  });
+
+  it('resolves null when the user is not authorized', async () => {
+    stubLogin({ status: 'not_authorized' });
+    const { loginAndFetchPages } = useFacebookPageConnect();
+
+    await expect(loginAndFetchPages()).resolves.toBeNull();
+    expect(ChannelApi.fetchFacebookPages).not.toHaveBeenCalled();
+  });
+
+  it('resolves null on an unknown login status', async () => {
+    stubLogin({ status: 'unknown' });
+    const { loginAndFetchPages } = useFacebookPageConnect();
+
+    await expect(loginAndFetchPages()).resolves.toBeNull();
+  });
+
+  it('rejects when fetching pages fails', async () => {
+    ChannelApi.fetchFacebookPages.mockRejectedValue(new Error('fetch failed'));
+    const { loginAndFetchPages } = useFacebookPageConnect();
+
+    await expect(loginAndFetchPages()).rejects.toThrow('fetch failed');
+  });
+
+  it('rejects when the SDK fails to load', async () => {
+    const error = new Error('script load failed');
+    error.name = 'ScriptLoaderError';
+    setupFacebookSdk.mockRejectedValue(error);
+    const { loginAndFetchPages } = useFacebookPageConnect();
+
+    await expect(loginAndFetchPages()).rejects.toThrow('script load failed');
+  });
+
+  it('ignores a second call while a run is in flight', async () => {
+    const pending = createDeferred();
+    ChannelApi.fetchFacebookPages.mockReturnValue(pending.promise);
+
+    const { loginAndFetchPages } = useFacebookPageConnect();
+    const first = loginAndFetchPages();
+    const second = loginAndFetchPages();
+
+    await expect(second).resolves.toBeNull();
+
+    pending.resolve(pagesResponse);
+    await first;
+    expect(window.FB.login).toHaveBeenCalledTimes(1);
+  });
+
+  it('toggles isAuthenticating across a run', async () => {
+    const pending = createDeferred();
+    ChannelApi.fetchFacebookPages.mockReturnValue(pending.promise);
+
+    const { isAuthenticating, loginAndFetchPages } = useFacebookPageConnect();
+    expect(isAuthenticating.value).toBe(false);
+
+    const result = loginAndFetchPages();
+    await flushPromises();
+    expect(isAuthenticating.value).toBe(true);
+
+    pending.resolve(pagesResponse);
+    await result;
+    expect(isAuthenticating.value).toBe(false);
+  });
+
+  it('preloads the SDK once and reuses it for login', async () => {
+    const { preloadSdk, loginAndFetchPages } = useFacebookPageConnect();
+
+    preloadSdk();
+    preloadSdk();
+    await loginAndFetchPages();
+
+    expect(setupFacebookSdk).toHaveBeenCalledTimes(1);
+  });
+});
@@ -47,7 +47,11 @@ const mockStore = createStore({
            11: { id: 11, channel_type: INBOX_TYPES.API },
            12: { id: 12, channel_type: INBOX_TYPES.SMS },
            13: { id: 13, channel_type: INBOX_TYPES.INSTAGRAM },
-            14: { id: 14, channel_type: INBOX_TYPES.VOICE },
+            14: {
+              id: 14,
+              channel_type: INBOX_TYPES.TWILIO,
+              voice_enabled: true,
+            },
            15: { id: 15, channel_type: INBOX_TYPES.TIKTOK },
          };
          return inboxes[id] || null;
@@ -211,11 +215,11 @@ describe('useInbox', () => {
      });
      expect(wrapper.vm.isAnInstagramChannel).toBe(true);

-      // Test Voice
+      // Test Voice (Twilio with voice_enabled)
      wrapper = mount(createTestComponent(14), {
        global: { plugins: [mockStore] },
      });
-      expect(wrapper.vm.isAVoiceChannel).toBe(true);
+      expect(wrapper.vm.voiceCallEnabled).toBe(true);

      // Test Tiktok
      wrapper = mount(createTestComponent(15), {
@@ -274,7 +278,8 @@ describe('useInbox', () => {
        'isAnEmailChannel',
        'isAnInstagramChannel',
        'isATiktokChannel',
-        'isAVoiceChannel',
+        'voiceCallEnabled',
+        'voiceCallProvider',
      ];

      expectedProperties.forEach(prop => {
@@ -1,6 +1,47 @@
+const keyboardEventsMock = vi.hoisted(() => ({
+  mountedCallbacks: [],
+  unmountedCallbacks: [],
+  registeredKeybindings: {},
+}));
+
+vi.mock('vue', async importOriginal => ({
+  ...(await importOriginal()),
+  onMounted: vi.fn(callback =>
+    keyboardEventsMock.mountedCallbacks.push(callback)
+  ),
+  onUnmounted: vi.fn(callback =>
+    keyboardEventsMock.unmountedCallbacks.push(callback)
+  ),
+}));
+
+vi.mock('dashboard/composables/useDetectKeyboardLayout', () => ({
+  useDetectKeyboardLayout: vi.fn(() => Promise.resolve('QWERTY')),
+}));
+
+vi.mock('tinykeys', () => ({
+  createKeybindingsHandler: vi.fn(keybindings => {
+    keyboardEventsMock.registeredKeybindings = keybindings;
+    return event => keybindings[event.shortcut]?.(event);
+  }),
+}));
+
+import { useDetectKeyboardLayout } from 'dashboard/composables/useDetectKeyboardLayout';
 import { useKeyboardEvents } from 'dashboard/composables/useKeyboardEvents';
+import { LAYOUT_QWERTZ } from 'shared/helpers/KeyboardHelpers';
+
+const mount = async events => {
+  useKeyboardEvents(events);
+  await keyboardEventsMock.mountedCallbacks[0]();
+  return keyboardEventsMock.registeredKeybindings;
+};

 describe('useKeyboardEvents', () => {
+  beforeEach(() => {
+    keyboardEventsMock.mountedCallbacks = [];
+    keyboardEventsMock.unmountedCallbacks = [];
+    keyboardEventsMock.registeredKeybindings = {};
+  });
+
  it('should be defined', () => {
    expect(useKeyboardEvents).toBeDefined();
  });
@@ -9,18 +50,46 @@ describe('useKeyboardEvents', () => {
    expect(useKeyboardEvents).toBeInstanceOf(Function);
  });

-  it('should set up listeners on mount and remove them on unmount', async () => {
-    const events = {
-      'ALT+KeyL': () => {},
-    };
+  it('registers keybindings on mount and removes the listener on unmount', async () => {
+    const addEventListener = vi.spyOn(document, 'addEventListener');

-    const mountedMock = vi.fn();
-    const unmountedMock = vi.fn();
-    useKeyboardEvents(events);
-    mountedMock();
-    unmountedMock();
+    const keybindings = await mount({ 'ALT+KeyL': () => {} });
+    expect(Object.keys(keybindings)).toEqual(['ALT+KeyL']);

-    expect(mountedMock).toHaveBeenCalled();
-    expect(unmountedMock).toHaveBeenCalled();
+    const { signal } = addEventListener.mock.calls[0][2];
+    expect(signal.aborted).toBe(false);
+
+    keyboardEventsMock.unmountedCallbacks[0]();
+    expect(signal.aborted).toBe(true);
+  });
+
+  it('prefixes Shift on QWERTZ layouts for the affected keys', async () => {
+    useDetectKeyboardLayout.mockResolvedValueOnce(LAYOUT_QWERTZ);
+
+    const keybindings = await mount({ 'Alt+KeyL': () => {} });
+
+    expect(Object.keys(keybindings)).toEqual(['Shift+Alt+KeyL']);
+  });
+
+  it('ignores shortcuts on focused typeable elements by default', async () => {
+    const action = vi.fn();
+    const keybindings = await mount({
+      'Alt+KeyL': { action, allowOnFocusedInput: false },
+    });
+
+    keybindings['Alt+KeyL']({ target: document.createElement('textarea') });
+
+    expect(action).not.toHaveBeenCalled();
+  });
+
+  it('runs shortcuts on focused typeable elements when allowed', async () => {
+    const action = vi.fn();
+    const keybindings = await mount({
+      'Alt+KeyL': { action, allowOnFocusedInput: true },
+    });
+
+    keybindings['Alt+KeyL']({ target: document.createElement('textarea') });
+
+    expect(action).toHaveBeenCalledTimes(1);
  });
 });
@@ -0,0 +1,208 @@
+import { useWhatsappEmbeddedSignup } from '../useWhatsappEmbeddedSignup';
+import {
+  setupFacebookSdk,
+  initWhatsAppEmbeddedSignup,
+  createMessageHandler,
+} from 'dashboard/routes/dashboard/settings/inbox/channels/whatsapp/utils';
+
+vi.mock(
+  'dashboard/routes/dashboard/settings/inbox/channels/whatsapp/utils',
+  () => ({
+    setupFacebookSdk: vi.fn(),
+    initWhatsAppEmbeddedSignup: vi.fn(),
+    createMessageHandler: vi.fn(),
+    isValidBusinessData: vi.fn(data =>
+      Boolean(data && data.business_id && data.waba_id)
+    ),
+  })
+);
+
+const flushPromises = () =>
+  new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+
+const createDeferred = () => {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+
+const VALID_BUSINESS = {
+  business_id: 'biz-1',
+  waba_id: 'waba-1',
+  phone_number_id: 'phone-1',
+};
+
+describe('useWhatsappEmbeddedSignup', () => {
+  // The mocked createMessageHandler captures the callback the composable
+  // registers, so tests can simulate Meta's WA_EMBEDDED_SIGNUP postMessages
+  // directly without the window-event + origin plumbing (that is covered by
+  // the utils' own tests).
+  let signupCallback;
+  let registeredListener;
+
+  const emit = data => signupCallback(data);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    window.chatwootConfig = {
+      whatsappAppId: 'app-id',
+      whatsappConfigurationId: 'config-id',
+      whatsappApiVersion: 'v22.0',
+    };
+
+    setupFacebookSdk.mockResolvedValue();
+    createMessageHandler.mockImplementation(callback => {
+      signupCallback = callback;
+      registeredListener = () => {};
+      return registeredListener;
+    });
+  });
+
+  it('resolves credentials when the auth code arrives before the business data', async () => {
+    initWhatsAppEmbeddedSignup.mockResolvedValue('auth-code');
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const result = runEmbeddedSignup();
+
+    await flushPromises(); // SDK setup + FB.login resolve the code first
+    emit({ event: 'FINISH', data: VALID_BUSINESS });
+
+    await expect(result).resolves.toEqual({
+      code: 'auth-code',
+      business_id: 'biz-1',
+      waba_id: 'waba-1',
+      phone_number_id: 'phone-1',
+    });
+    expect(setupFacebookSdk).toHaveBeenCalledWith('app-id', 'v22.0');
+    expect(initWhatsAppEmbeddedSignup).toHaveBeenCalledWith('config-id');
+  });
+
+  it('resolves credentials when the business data arrives before the auth code', async () => {
+    const code = createDeferred();
+    initWhatsAppEmbeddedSignup.mockReturnValue(code.promise);
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const result = runEmbeddedSignup();
+
+    // Business data lands first, while FB.login is still pending.
+    emit({
+      event: 'FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING',
+      data: VALID_BUSINESS,
+    });
+    code.resolve('late-code');
+
+    await expect(result).resolves.toEqual({
+      code: 'late-code',
+      business_id: 'biz-1',
+      waba_id: 'waba-1',
+      phone_number_id: 'phone-1',
+    });
+  });
+
+  it('defaults phone_number_id to an empty string when absent', async () => {
+    initWhatsAppEmbeddedSignup.mockResolvedValue('auth-code');
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const result = runEmbeddedSignup();
+
+    await flushPromises();
+    emit({
+      event: 'FINISH',
+      data: { business_id: 'biz-1', waba_id: 'waba-1' },
+    });
+
+    await expect(result).resolves.toMatchObject({ phone_number_id: '' });
+  });
+
+  it('resolves null when FB.login is cancelled', async () => {
+    initWhatsAppEmbeddedSignup.mockRejectedValue(new Error('Login cancelled'));
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+
+    await expect(runEmbeddedSignup()).resolves.toBeNull();
+  });
+
+  it('resolves null on a CANCEL event', async () => {
+    initWhatsAppEmbeddedSignup.mockReturnValue(createDeferred().promise);
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const result = runEmbeddedSignup();
+
+    emit({ event: 'CANCEL' });
+
+    await expect(result).resolves.toBeNull();
+  });
+
+  it('rejects with the Meta error message on an error event', async () => {
+    initWhatsAppEmbeddedSignup.mockReturnValue(createDeferred().promise);
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const result = runEmbeddedSignup();
+
+    emit({ event: 'error', error_message: 'WABA not eligible' });
+
+    await expect(result).rejects.toThrow('WABA not eligible');
+  });
+
+  it('rejects when the business data is invalid', async () => {
+    initWhatsAppEmbeddedSignup.mockReturnValue(createDeferred().promise);
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const result = runEmbeddedSignup();
+
+    emit({ event: 'FINISH', data: { business_id: 'biz-1' } }); // no waba_id
+
+    await expect(result).rejects.toThrow('Invalid business data');
+  });
+
+  it('rejects when the SDK or login fails for a non-cancel reason', async () => {
+    initWhatsAppEmbeddedSignup.mockRejectedValue(new Error('popup blocked'));
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+
+    await expect(runEmbeddedSignup()).rejects.toThrow('popup blocked');
+  });
+
+  it('ignores a second call while a run is in flight', async () => {
+    initWhatsAppEmbeddedSignup.mockResolvedValue('auth-code');
+
+    const { runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    const first = runEmbeddedSignup();
+    const second = runEmbeddedSignup();
+
+    await expect(second).resolves.toBeNull();
+
+    // Let the first run finish so it doesn't leak into the next test.
+    await flushPromises();
+    emit({ event: 'FINISH', data: VALID_BUSINESS });
+    await first;
+
+    expect(setupFacebookSdk).toHaveBeenCalledTimes(1);
+  });
+
+  it('toggles isAuthenticating and removes the listener once settled', async () => {
+    initWhatsAppEmbeddedSignup.mockResolvedValue('auth-code');
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+
+    const { isAuthenticating, runEmbeddedSignup } = useWhatsappEmbeddedSignup();
+    expect(isAuthenticating.value).toBe(false);
+
+    const result = runEmbeddedSignup();
+    expect(isAuthenticating.value).toBe(true);
+
+    await flushPromises();
+    emit({ event: 'FINISH', data: VALID_BUSINESS });
+    await result;
+
+    expect(isAuthenticating.value).toBe(false);
+    expect(removeSpy).toHaveBeenCalledWith('message', registeredListener);
+    removeSpy.mockRestore();
+  });
+});
@@ -52,6 +52,10 @@ export function useAccount() {
    });
  };

+  const finishOnboarding = async data => {
+    await store.dispatch('accounts/finishOnboarding', data);
+  };
+
  return {
    accountId,
    route,
@@ -61,5 +65,6 @@ export function useAccount() {
    isCloudFeatureEnabled,
    isOnChatwootCloud,
    updateAccount,
+    finishOnboarding,
  };
 }
@@ -1,59 +1,145 @@
-import { computed, ref, watch, onUnmounted, onMounted } from 'vue';
+import { computed, readonly, ref, watch, onUnmounted, onMounted } from 'vue';
+import { useStore } from 'vuex';
+import { useI18n } from 'vue-i18n';
 import VoiceAPI from 'dashboard/api/channel/voice/voiceAPIClient';
 import TwilioVoiceClient from 'dashboard/api/channel/voice/twilioVoiceClient';
 import { useCallsStore } from 'dashboard/stores/calls';
+import { useAlert } from 'dashboard/composables';
+import {
+  useWhatsappCallSession,
+  sendWhatsappTerminateBeacon,
+  cleanupWhatsappSession,
+} from 'dashboard/composables/useWhatsappCallSession';
+import { handleVoiceCallCreated } from 'dashboard/helper/voice';
+import { VOICE_CALL_PROVIDERS } from 'dashboard/helper/inbox';
+import {
+  CONTENT_TYPES,
+  VOICE_CALL_DIRECTION,
+  VOICE_CALL_STATUS,
+} from 'dashboard/components-next/message/constants';
 import Timer from 'dashboard/helper/Timer';

-export function useCallSession() {
-  const callsStore = useCallsStore();
-  const isJoining = ref(false);
-  const callDuration = ref(0);
-  const durationTimer = new Timer(elapsed => {
-    callDuration.value = elapsed;
+const isWhatsappCall = call => call?.provider === VOICE_CALL_PROVIDERS.WHATSAPP;
+
+// Dismissed call sids must not be re-seeded by the conversation-load watcher.
+// Lives at module scope so all consumers share the same set.
+const dismissedCallSids = new Set();
+const markDismissed = callSid => {
+  if (callSid) dismissedCallSids.add(callSid);
+};
+
+// Globals attached once across all useCallSession() consumers — bubbles in a
+// long thread call this composable many times, and a per-instance Timer +
+// window listener stack would multiply work.
+let globalsAttachedCount = 0;
+let globalDurationTimer = null;
+const globalCallDuration = ref(0);
+let storedCallsStoreRef = null;
+// Shared join lock so two surfaces (bubble + widget) clicking concurrently
+// see one in-flight join, not two unrelated isJoining refs.
+const globalIsJoining = ref(false);
+const globalIsJoiningReadonly = readonly(globalIsJoining);
+
+const handleBeforeUnloadGlobal = event => {
+  const store = storedCallsStoreRef;
+  if (!store) return;
+  if (!store.hasActiveCall && !store.hasIncomingCall) return;
+  event.preventDefault();
+  event.returnValue = '';
+};
+const handlePageHideGlobal = () => sendWhatsappTerminateBeacon();
+const handleTwilioDisconnectedGlobal = () =>
+  storedCallsStoreRef?.clearActiveCall();
+
+const attachGlobalsOnFirstMount = callsStore => {
+  globalsAttachedCount += 1;
+  if (globalsAttachedCount > 1) return;
+  storedCallsStoreRef = callsStore;
+  globalDurationTimer = new Timer(elapsed => {
+    globalCallDuration.value = elapsed;
  });
-
-  const activeCall = computed(() => callsStore.activeCall);
-  const incomingCalls = computed(() => callsStore.incomingCalls);
-  const hasActiveCall = computed(() => callsStore.hasActiveCall);
-
-  watch(
-    hasActiveCall,
-    active => {
-      if (active) {
-        durationTimer.start();
-      } else {
-        durationTimer.stop();
-        callDuration.value = 0;
-      }
-    },
-    { immediate: true }
+  TwilioVoiceClient.addEventListener(
+    'call:disconnected',
+    handleTwilioDisconnectedGlobal
  );
+  window.addEventListener('beforeunload', handleBeforeUnloadGlobal);
+  window.addEventListener('pagehide', handlePageHideGlobal);
+};

-  onMounted(() => {
-    TwilioVoiceClient.addEventListener('call:disconnected', () =>
-      callsStore.clearActiveCall()
-    );
-  });
+const detachGlobalsOnLastUnmount = () => {
+  globalsAttachedCount -= 1;
+  if (globalsAttachedCount > 0) return;
+  globalDurationTimer?.stop();
+  globalDurationTimer = null;
+  globalCallDuration.value = 0;
+  storedCallsStoreRef = null;
+  TwilioVoiceClient.removeEventListener(
+    'call:disconnected',
+    handleTwilioDisconnectedGlobal
+  );
+  window.removeEventListener('beforeunload', handleBeforeUnloadGlobal);
+  window.removeEventListener('pagehide', handlePageHideGlobal);
+};

-  onUnmounted(() => {
-    durationTimer.stop();
-    TwilioVoiceClient.removeEventListener('call:disconnected', () =>
-      callsStore.clearActiveCall()
-    );
-  });
+// Build the action surface used by both the root session composable and the
+// lighter useCallActions consumer. All state is module-scoped — the actions
+// don't depend on per-instance refs, so they're cheap to call from anywhere.
+const buildCallActions = ({ callsStore, whatsappSession, t }) => {
+  const findCall = callSid => callsStore.calls.find(c => c.callSid === callSid);

-  const endCall = async ({ conversationId, inboxId }) => {
-    await VoiceAPI.leaveConference(inboxId, conversationId);
-    TwilioVoiceClient.endClientCall();
-    durationTimer.stop();
-    callsStore.clearActiveCall();
+  const endCall = async ({ conversationId, inboxId, callSid }) => {
+    const call = findCall(callSid);
+    if (isWhatsappCall(call)) {
+      // Pass call.callId so a wiped module state (e.g. a prior accept attempt
+      // tore down the WebRTC session) doesn't stop us hitting /terminate.
+      await whatsappSession.endActiveCall(call?.callId);
+      globalDurationTimer?.stop();
+      callsStore.clearActiveCall();
+      return;
+    }
+
+    // try/finally so a failed leaveConference (e.g. backend 5xx) still
+    // tears down the local Device and UI state — otherwise the call stays
+    // visually active with the mic open.
+    try {
+      await VoiceAPI.leaveConference({ inboxId, conversationId, callSid });
+    } finally {
+      TwilioVoiceClient.endClientCall();
+      globalDurationTimer?.stop();
+      callsStore.clearActiveCall();
+    }
  };

  const joinCall = async ({ conversationId, inboxId, callSid }) => {
-    if (isJoining.value) return null;
+    if (globalIsJoining.value) return null;

-    isJoining.value = true;
+    const call = findCall(callSid);
+    // Outbound *WhatsApp* calls have no separate join step — the offer was
+    // sent at initiate time and the answer is applied by the cable handler.
+    // Routing through acceptIncomingCall here would call prepareInboundAnswer →
+    // cleanup() and destroy the live outbound session. Outbound *Twilio*
+    // calls still need joinConference + joinClientCall (FloatingCallWidget
+    // auto-joins them), so don't short-circuit those.
+    if (
+      call?.callDirection === VOICE_CALL_DIRECTION.OUTBOUND &&
+      isWhatsappCall(call)
+    ) {
+      return null;
+    }
+
+    globalIsJoining.value = true;
    try {
+      if (isWhatsappCall(call)) {
+        await whatsappSession.acceptIncomingCall({
+          callId: call.callId,
+          sdpOffer: call.sdpOffer,
+          iceServers: call.iceServers,
+        });
+        callsStore.setCallActive(callSid);
+        globalDurationTimer?.start();
+        return { callId: call.callId };
+      }
+
      const device = await TwilioVoiceClient.initializeDevice(inboxId);
      if (!device) return null;

@@ -66,45 +152,169 @@ export function useCallSession() {
      await TwilioVoiceClient.joinClientCall({
        to: joinResponse?.conference_sid,
        conversationId,
+        callSid,
      });

      callsStore.setCallActive(callSid);
-      durationTimer.start();
+      globalDurationTimer?.start();

      return { conferenceSid: joinResponse?.conference_sid };
    } catch (error) {
+      useAlert(error?.response?.data?.error || t('CONTACT_PANEL.CALL_FAILED'));
+      if (error?.response?.status === 409) {
+        TwilioVoiceClient.endClientCall();
+        markDismissed(callSid);
+        callsStore.dismissCall(callSid);
+      } else if (!isWhatsappCall(call)) {
+        // Tear down the Twilio Device on any other join error so a retry
+        // starts from a clean state — joinClientCall can leave the device
+        // half-initialized after a network blip.
+        TwilioVoiceClient.endClientCall();
+      }
      // eslint-disable-next-line no-console
      console.error('Failed to join call:', error);
+      // Drop any half-built WebRTC state so the next click starts fresh.
+      cleanupWhatsappSession();
      return null;
    } finally {
-      isJoining.value = false;
+      globalIsJoining.value = false;
    }
  };

-  const rejectIncomingCall = callSid => {
-    TwilioVoiceClient.endClientCall();
-    callsStore.dismissCall(callSid);
+  // Await provider-side reject before dismissing the local entry; if the API
+  // call fails the call should stay surfaced so the agent can retry instead of
+  // disappearing while the backend still rings.
+  const rejectIncomingCall = async callSid => {
+    const call = findCall(callSid);
+    try {
+      if (isWhatsappCall(call) && call?.callId) {
+        if (call.callDirection === VOICE_CALL_DIRECTION.OUTBOUND) {
+          // Outbound calls that are still ringing must be terminated, not
+          // rejected (reject is the inbound-side verb on Meta's API).
+          await whatsappSession.endActiveCall(call.callId);
+        } else {
+          await whatsappSession.rejectIncomingCall(call.callId);
+        }
+      } else if (call?.inboxId && call?.conversationId) {
+        // Twilio incoming reject: agent hasn't joined the Device yet, so
+        // endClientCall is a no-op. End the conference server-side instead
+        // so Twilio hangs up the inbound leg.
+        await VoiceAPI.leaveConference({
+          inboxId: call.inboxId,
+          conversationId: call.conversationId,
+          callSid,
+        });
+      } else {
+        TwilioVoiceClient.endClientCall();
+      }
+    } finally {
+      markDismissed(callSid);
+      callsStore.dismissCall(callSid);
+    }
  };

  const dismissCall = callSid => {
+    markDismissed(callSid);
    callsStore.dismissCall(callSid);
  };

+  return { endCall, joinCall, rejectIncomingCall, dismissCall };
+};
+
+const buildReactiveSurface = callsStore => {
+  const activeCall = computed(() => callsStore.activeCall);
+  const incomingCalls = computed(() => callsStore.incomingCalls);
+  const hasActiveCall = computed(() => callsStore.hasActiveCall);
  const formattedCallDuration = computed(() => {
-    const minutes = Math.floor(callDuration.value / 60);
-    const seconds = callDuration.value % 60;
+    const total = globalCallDuration.value;
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
    return `${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
  });
-
  return {
    activeCall,
    incomingCalls,
    hasActiveCall,
-    isJoining,
+    isJoining: globalIsJoiningReadonly,
    formattedCallDuration,
-    joinCall,
-    endCall,
-    rejectIncomingCall,
-    dismissCall,
  };
+};
+
+// Root-mount composable. Call once at the dashboard root (FloatingCallWidget
+// is the natural anchor — always mounted, lifetime spans the whole session).
+// This is the only path that registers global window/Twilio listeners and
+// owns the duration Timer.
+export function useCallSession() {
+  const store = useStore();
+  const callsStore = useCallsStore();
+  const whatsappSession = useWhatsappCallSession();
+  const { t } = useI18n();
+
+  const reactive = buildReactiveSurface(callsStore);
+
+  // Cable broadcasts (voice_call.incoming / message.created) are one-shot, so
+  // on a hard refresh they leave the calls store empty. Seed it from any
+  // ringing voice_call message in the conversation cache. Skip calls the
+  // agent has already dismissed locally so they don't re-pop on the next
+  // conversation update.
+  const seedCallsFromHydratedMessages = () => {
+    const conversations = store.getters.getAllConversations || [];
+    const currentUserId = store.getters.getCurrentUserID;
+    const currentUserAvailability = store.getters.getCurrentUserAvailability;
+    conversations.forEach(conv => {
+      (conv.messages || []).forEach(msg => {
+        if (msg.content_type !== CONTENT_TYPES.VOICE_CALL) return;
+        if (msg.call?.status !== VOICE_CALL_STATUS.RINGING) return;
+        const callSid = msg.call?.provider_call_id;
+        if (callSid && dismissedCallSids.has(callSid)) return;
+        handleVoiceCallCreated(msg, currentUserId, currentUserAvailability);
+      });
+    });
+  };
+
+  watch(
+    reactive.hasActiveCall,
+    active => {
+      if (active) {
+        globalDurationTimer?.start();
+      } else {
+        globalDurationTimer?.stop();
+        globalCallDuration.value = 0;
+      }
+    },
+    { immediate: true }
+  );
+
+  onMounted(() => {
+    attachGlobalsOnFirstMount(callsStore);
+    seedCallsFromHydratedMessages();
+  });
+
+  // Re-seed when conversations stream in after mount; addCall merges by callSid
+  // and dismissed sids are filtered, so this is idempotent.
+  watch(
+    () => store.getters.getAllConversations?.length,
+    () => seedCallsFromHydratedMessages()
+  );
+
+  onUnmounted(() => detachGlobalsOnLastUnmount());
+
+  const actions = buildCallActions({ callsStore, whatsappSession, t });
+
+  return { ...reactive, ...actions };
+}
+
+// Lightweight consumer for components that need to read state and trigger
+// actions but should NOT mount global listeners (e.g., per-message bubbles
+// rendered in a thread). Reads from the same module-level state that
+// useCallSession owns, so the duration timer and dismissed set stay coherent.
+export function useCallActions() {
+  const callsStore = useCallsStore();
+  const whatsappSession = useWhatsappCallSession();
+  const { t } = useI18n();
+
+  const reactive = buildReactiveSurface(callsStore);
+  const actions = buildCallActions({ callsStore, whatsappSession, t });
+
+  return { ...reactive, ...actions };
 }
@@ -36,11 +36,18 @@ export function useConfig() {
   */
  const enterprisePlanName = config.enterprisePlanName;

+  /**
+   * Indicates whether inbox webhook events (ENABLE_INBOX_EVENTS) are enabled.
+   * @type {boolean}
+   */
+  const inboxEventsEnabled = config.inboxEventsEnabled === 'true';
+
  return {
    hostURL,
    vapidPublicKey,
    enabledLanguages,
    isEnterprise,
    enterprisePlanName,
+    inboxEventsEnabled,
  };
 }
@@ -0,0 +1,77 @@
+import { ref } from 'vue';
+import { useMapGetter } from 'dashboard/composables/store';
+import ChannelApi from 'dashboard/api/channels';
+import { buildFacebookLoginScopes } from 'dashboard/helper/facebookScopes';
+import { setupFacebookSdk } from 'dashboard/routes/dashboard/settings/inbox/channels/whatsapp/utils';
+
+// Headless half of the Facebook Page connect flow: load the Meta SDK, run
+// FB.login for page scopes, and fetch the user's pages. The caller owns the
+// page-picker UI and the channel creation, because choosing a page is an
+// interactive step (a user can manage several pages).
+//
+// Split into preloadSdk() + loginAndFetchPages() for popup safety: FB.login
+// opens a popup and needs the click's transient activation. Preloading the SDK
+// when the picker opens means the click-time `await` resolves within that
+// activation window; a cold load resolves on the script's `load` task seconds
+// later, after activation has expired, and the popup gets blocked.
+export function useFacebookPageConnect() {
+  const accountId = useMapGetter('getCurrentAccountId');
+  const isAuthenticating = ref(false);
+
+  let sdkSetupPromise = null;
+
+  // Idempotent — call this when the picker UI opens. A failed load clears the
+  // cache so a later attempt can retry instead of being stuck on a rejection.
+  const preloadSdk = () => {
+    if (!sdkSetupPromise) {
+      sdkSetupPromise = setupFacebookSdk(
+        window.chatwootConfig?.fbAppId,
+        window.chatwootConfig?.fbApiVersion
+      ).catch(error => {
+        sdkSetupPromise = null;
+        throw error;
+      });
+    }
+    return sdkSetupPromise;
+  };
+
+  // FB.login never rejects; resolve the user access token on success and null
+  // for any other status (closed popup, not_authorized, unknown).
+  const login = () =>
+    new Promise(resolve => {
+      window.FB.login(
+        response => {
+          resolve(
+            response.status === 'connected'
+              ? response.authResponse?.accessToken || null
+              : null
+          );
+        },
+        { scope: buildFacebookLoginScopes() }
+      );
+    });
+
+  // Resolves { userAccessToken, pages } on success, null when the user cancels,
+  // and rejects on SDK-load or page-fetch failure (the caller maps it to UI).
+  const loginAndFetchPages = async () => {
+    if (isAuthenticating.value) return null;
+    isAuthenticating.value = true;
+    try {
+      await preloadSdk();
+      const token = await login();
+      if (!token) return null;
+
+      const response = await ChannelApi.fetchFacebookPages(
+        token,
+        accountId.value
+      );
+      const { page_details: pages, user_access_token: userAccessToken } =
+        response.data.data;
+      return { userAccessToken, pages };
+    } finally {
+      isAuthenticating.value = false;
+    }
+  };
+
+  return { isAuthenticating, preloadSdk, loginAndFetchPages };
+}
@@ -1,7 +1,11 @@
 import { computed } from 'vue';
 import { useMapGetter } from 'dashboard/composables/store';
 import { useCamelCase } from 'dashboard/composables/useTransformKeys';
-import { INBOX_TYPES } from 'dashboard/helper/inbox';
+import {
+  INBOX_TYPES,
+  isVoiceCallEnabled,
+  getVoiceCallProvider,
+} from 'dashboard/helper/inbox';

 export const INBOX_FEATURES = {
  REPLY_TO: 'replyTo',
@@ -134,9 +138,9 @@ export const useInbox = (inboxId = null) => {
    return channelType.value === INBOX_TYPES.TIKTOK;
  });

-  const isAVoiceChannel = computed(() => {
-    return channelType.value === INBOX_TYPES.VOICE;
-  });
+  const voiceCallEnabled = computed(() => isVoiceCallEnabled(inbox.value));
+
+  const voiceCallProvider = computed(() => getVoiceCallProvider(inbox.value));

  return {
    inbox,
@@ -156,6 +160,7 @@ export const useInbox = (inboxId = null) => {
    isAnEmailChannel,
    isAnInstagramChannel,
    isATiktokChannel,
-    isAVoiceChannel,
+    voiceCallEnabled,
+    voiceCallProvider,
  };
 };
@@ -7,6 +7,7 @@ export const DEFAULT_CONVERSATION_SIDEBAR_ITEMS_ORDER = Object.freeze([
  { name: 'conversation_info' },
  { name: 'contact_attributes' },
  { name: 'contact_notes' },
+  { name: 'shared_files' },
  { name: 'previous_conversation' },
  { name: 'conversation_participants' },
  { name: 'linear_issues' },
@@ -0,0 +1,455 @@
+import { readonly, ref } from 'vue';
+import Cookies from 'js-cookie';
+import WhatsappCallsAPI from 'dashboard/api/channel/whatsapp/whatsappCallsAPI';
+import { VOICE_CALL_OUTBOUND_INIT_STATUS } from 'dashboard/components-next/message/constants';
+
+// Module-level state lets the cable handlers and unload listeners reach the
+// live PeerConnection without prop-drilling refs through every composable.
+let pc = null;
+let localStream = null;
+let remoteStream = null;
+let remoteAudioEl = null;
+let mediaRecorder = null;
+let recorderChunks = [];
+let audioContext = null;
+let activeCallId = null;
+// voice_call.outbound_connected (the sole source of the outbound SDP answer) is
+// broadcast account-wide and can arrive before the /initiate response sets
+// activeCallId in this tab. Until we know our own call id we can't tell our
+// answer from a concurrent agent's, so the cable handler buffers them here keyed
+// by call id (a single slot would let a concurrent agent's event clobber ours)
+// and initiateOutboundCall flushes the matching one by id.
+const pendingOutboundAnswers = new Map();
+// Module-scoped so multiple composable callers (header button + contact-panel
+// button) share the same lock. A per-instance ref let two parallel callers
+// both pass the guard and tear down each other's WebRTC state in cleanup().
+// ref() so consumers can reactively gate buttons on it (the composable
+// re-exports this as `isInitiating`).
+const isInitiatingOutbound = ref(false);
+const isInitiatingOutboundReadonly = readonly(isInitiatingOutbound);
+// Inbound calls record from the moment the agent clicks accept (their click =
+// pickup). Outbound calls must wait — Meta's `connect` webhook (which lands
+// during ringing) negotiates remote tracks ~20s before the contact actually
+// answers, and we don't want pre-pickup audio in the recording. This flag is
+// flipped to true by armOutboundRecorder() when the ACCEPTED status arrives.
+let recorderArmed = false;
+
+const ensureRemoteAudioElement = () => {
+  if (remoteAudioEl) return remoteAudioEl;
+  remoteAudioEl = document.createElement('audio');
+  remoteAudioEl.id = 'whatsapp-call-remote-audio';
+  remoteAudioEl.autoplay = true;
+  remoteAudioEl.playsInline = true;
+  remoteAudioEl.style.display = 'none';
+  document.body.appendChild(remoteAudioEl);
+  return remoteAudioEl;
+};
+
+const playRemoteStream = stream => {
+  const el = ensureRemoteAudioElement();
+  el.srcObject = stream;
+  el.play().catch(err => {
+    // eslint-disable-next-line no-console
+    console.warn('[WhatsApp Call] remote audio play() failed:', err);
+  });
+};
+
+// 1s timeslice keeps a recent recording chunk in memory so a remote hangup
+// that races cleanup still has data to upload.
+const RECORDING_TIMESLICE_MS = 1000;
+const ICE_GATHER_TIMEOUT_MS = 10000;
+
+const RECORDER_MIME_CANDIDATES = [
+  'audio/webm;codecs=opus',
+  'audio/webm',
+  'audio/ogg;codecs=opus',
+];
+
+// Outbound calls have no backend-supplied ice_servers (the call doesn't exist
+// at offer time). Without STUN the browser only sends host candidates and
+// browser→Meta media silently drops through any non-trivial NAT.
+const DEFAULT_OUTBOUND_ICE_SERVERS = [{ urls: 'stun:stun.l.google.com:19302' }];
+
+const waitForIceGatheringComplete = peer =>
+  new Promise(resolve => {
+    if (peer.iceGatheringState === 'complete') {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, ICE_GATHER_TIMEOUT_MS);
+    peer.addEventListener('icegatheringstatechange', () => {
+      if (peer.iceGatheringState === 'complete') {
+        clearTimeout(timer);
+        resolve();
+      }
+    });
+  });
+
+const setupRecorder = () => {
+  if (!localStream || !remoteStream || mediaRecorder) return;
+  // createMediaStreamSource on a stream with no audio tracks wires up to
+  // nothing — the recorded mix would be silence. Wait until ontrack fires.
+  if (remoteStream.getAudioTracks().length === 0) return;
+
+  audioContext = new AudioContext({ sampleRate: 48000 });
+  // AudioContext starts suspended under most autoplay policies; without
+  // resume() the destination stream produces silence.
+  audioContext.resume().catch(() => {});
+
+  const destination = audioContext.createMediaStreamDestination();
+  audioContext.createMediaStreamSource(localStream).connect(destination);
+  audioContext.createMediaStreamSource(remoteStream).connect(destination);
+
+  const mimeType = RECORDER_MIME_CANDIDATES.find(t =>
+    MediaRecorder.isTypeSupported(t)
+  );
+  if (!mimeType) return;
+
+  recorderChunks = [];
+  mediaRecorder = new MediaRecorder(destination.stream, { mimeType });
+  mediaRecorder.ondataavailable = event => {
+    if (event.data && event.data.size > 0) recorderChunks.push(event.data);
+  };
+  mediaRecorder.start(RECORDING_TIMESLICE_MS);
+};
+
+const cleanup = () => {
+  if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+    try {
+      mediaRecorder.stop();
+    } catch (_) {
+      /* noop */
+    }
+  }
+  if (audioContext && audioContext.state !== 'closed') {
+    audioContext.close().catch(() => {});
+  }
+  if (localStream) localStream.getTracks().forEach(t => t.stop());
+  if (remoteStream) remoteStream.getTracks().forEach(t => t.stop());
+  if (pc) pc.close();
+  if (remoteAudioEl) remoteAudioEl.srcObject = null;
+
+  pc = null;
+  localStream = null;
+  remoteStream = null;
+  mediaRecorder = null;
+  recorderChunks = [];
+  audioContext = null;
+  activeCallId = null;
+  pendingOutboundAnswers.clear();
+  recorderArmed = false;
+};
+
+const buildPeerConnection = iceServers => {
+  const config = iceServers && iceServers.length ? { iceServers } : {};
+  pc = new RTCPeerConnection(config);
+  remoteStream = new MediaStream();
+  pc.ontrack = event => {
+    // Reuse the same MediaStream object — the recorder's audioContext source
+    // taps it once, so reassigning would orphan the recorder.
+    const tracks =
+      event.streams && event.streams[0]
+        ? event.streams[0].getTracks()
+        : [event.track];
+    tracks.forEach(track => {
+      if (!remoteStream.getTracks().includes(track))
+        remoteStream.addTrack(track);
+    });
+    playRemoteStream(remoteStream);
+    // Only arm the recorder when the call is actually accepted. For outbound
+    // this is the ACCEPTED status webhook; for inbound this is the agent's
+    // own click (acceptIncomingCall flips recorderArmed before returning).
+    if (recorderArmed) setupRecorder();
+  };
+  return pc;
+};
+
+const stopRecorderAndUpload = async callId => {
+  if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+    await new Promise(resolve => {
+      mediaRecorder.addEventListener('stop', resolve, { once: true });
+      try {
+        mediaRecorder.stop();
+      } catch (_) {
+        resolve();
+      }
+    });
+  }
+  if (!recorderChunks.length || !callId) return;
+
+  const blob = new Blob(recorderChunks, { type: recorderChunks[0].type });
+  // Best-effort — the controller's idempotency guard handles a retry.
+  try {
+    await WhatsappCallsAPI.uploadRecording(callId, blob);
+  } catch (_) {
+    /* noop */
+  }
+};
+
+// devise-token-auth requires access-token / client / uid headers on every
+// request — navigator.sendBeacon can't set custom headers, so we rehydrate
+// the auth payload from the cw_d_session_info cookie that the dashboard sets
+// at login. Used by the page-close terminate path below.
+const getDeviseAuthHeaders = () => {
+  try {
+    const raw = Cookies.get('cw_d_session_info');
+    if (!raw) return null;
+    const session = JSON.parse(raw);
+    return {
+      'access-token': session['access-token'] || '',
+      client: session.client || '',
+      uid: session.uid || '',
+      expiry: session.expiry || '',
+      'token-type': session['token-type'] || 'Bearer',
+    };
+  } catch (_) {
+    return null;
+  }
+};
+
+const beaconTerminate = callId => {
+  if (!callId) return;
+  const accountId = window.location.pathname.split('/')[3];
+  if (!accountId) return;
+  const headers = getDeviseAuthHeaders();
+  if (!headers) return;
+  const url = `/api/v1/accounts/${accountId}/whatsapp_calls/${callId}/terminate`;
+  // fetch+keepalive (instead of navigator.sendBeacon) so we can attach auth
+  // headers — without them devise-token-auth 401s and the call stays open on
+  // Meta until its carrier-side timeout (~60s).
+  try {
+    fetch(url, {
+      method: 'POST',
+      keepalive: true,
+      credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: '{}',
+    }).catch(() => {});
+  } catch (_) {
+    /* noop */
+  }
+};
+
+export const hasActiveWhatsappCall = () => !!(activeCallId || pc);
+
+export const isLocalWhatsappCall = callId =>
+  !!callId && activeCallId != null && callId === activeCallId;
+
+export function useWhatsappCallSession() {
+  const prepareInboundAnswer = async (sdpOffer, iceServers) => {
+    cleanup();
+    localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    buildPeerConnection(iceServers);
+    localStream.getTracks().forEach(t => pc.addTrack(t, localStream));
+    await pc.setRemoteDescription({ type: 'offer', sdp: sdpOffer });
+    const answer = await pc.createAnswer();
+    await pc.setLocalDescription(answer);
+    await waitForIceGatheringComplete(pc);
+    return pc.localDescription.sdp;
+  };
+
+  const prepareOutboundOffer = async () => {
+    cleanup();
+    localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    buildPeerConnection(DEFAULT_OUTBOUND_ICE_SERVERS);
+    localStream.getTracks().forEach(t => pc.addTrack(t, localStream));
+    const offer = await pc.createOffer();
+    await pc.setLocalDescription(offer);
+    await waitForIceGatheringComplete(pc);
+    return pc.localDescription.sdp;
+  };
+
+  const acceptIncomingCall = async ({ callId, sdpOffer, iceServers }) => {
+    // The store may not have sdpOffer yet (the cable broadcast can race the
+    // click). Fall back to GET /whatsapp_calls/:id which exposes it.
+    let offer = sdpOffer;
+    let ice = iceServers;
+    if (!offer && callId) {
+      try {
+        const fresh = await WhatsappCallsAPI.show(callId);
+        offer = fresh?.sdp_offer || fresh?.sdpOffer;
+        ice = ice || fresh?.ice_servers || fresh?.iceServers;
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.error(
+          '[WhatsApp Call] failed to fetch call data for accept:',
+          e
+        );
+      }
+    }
+    if (!offer) {
+      throw new Error('Missing sdp_offer for accept — call may have ended.');
+    }
+
+    // Release the mic + peer connection if anything between here and the accept
+    // round-trip fails — otherwise a rejected accept leaves the mic live and
+    // activeCallId set. Mirrors rejectIncomingCall's self-cleanup; rethrow so
+    // the caller can surface the failure and skip marking the call active.
+    try {
+      const sdpAnswer = await prepareInboundAnswer(offer, ice);
+      activeCallId = callId;
+      // Inbound: agent's click is the pickup. Arm the recorder before the API
+      // round-trip so when ontrack fires (triggered by setRemoteDescription
+      // back in prepareInboundAnswer) the recorder is already authorized.
+      recorderArmed = true;
+      setupRecorder();
+      await WhatsappCallsAPI.accept(callId, sdpAnswer);
+    } catch (e) {
+      cleanup();
+      throw e;
+    }
+  };
+
+  const rejectIncomingCall = async callId => {
+    try {
+      await WhatsappCallsAPI.reject(callId);
+    } finally {
+      cleanup();
+    }
+  };
+
+  const initiateOutboundCall = async conversationId => {
+    // Module-scoped lock + active-session guard so a second click — from the
+    // same composable instance OR a different one (header vs contact panel)
+    // OR while a call is already live — can't tear down the in-flight setup
+    // via prepareOutboundOffer's cleanup().
+    if (isInitiatingOutbound.value)
+      return { status: VOICE_CALL_OUTBOUND_INIT_STATUS.LOCKED };
+    if (hasActiveWhatsappCall())
+      return { status: VOICE_CALL_OUTBOUND_INIT_STATUS.LOCKED };
+    isInitiatingOutbound.value = true;
+    try {
+      const sdpOffer = await prepareOutboundOffer();
+      const response = await WhatsappCallsAPI.initiate(
+        conversationId,
+        sdpOffer
+      );
+      if (response?.id) {
+        activeCallId = response.id;
+        // A connect webhook that raced ahead of this response was buffered;
+        // apply our own by id now that we know it, then drop every buffered
+        // answer (concurrent agents' calls aren't ours to apply).
+        const buffered = pendingOutboundAnswers.get(activeCallId);
+        pendingOutboundAnswers.clear();
+        if (buffered) {
+          await pc.setRemoteDescription({
+            type: 'answer',
+            sdp: buffered,
+          });
+        }
+        return response;
+      }
+      // No call id back: this is the permission-request branch. The mic +
+      // PeerConnection allocated by prepareOutboundOffer aren't useful until
+      // the contact opts in and the agent retries — release them.
+      cleanup();
+      return response;
+    } catch (e) {
+      cleanup();
+      // BE returns 422 when the contact hasn't opted in (permission template
+      // sent or already pending). Surface it to the caller as a normal
+      // response shape so it can render the banner instead of an error toast.
+      const data = e?.response?.data;
+      if (
+        data?.status === VOICE_CALL_OUTBOUND_INIT_STATUS.PERMISSION_REQUESTED ||
+        data?.status === VOICE_CALL_OUTBOUND_INIT_STATUS.PERMISSION_PENDING
+      ) {
+        return { status: data.status };
+      }
+      throw e;
+    } finally {
+      isInitiatingOutbound.value = false;
+    }
+  };
+
+  // callIdOverride is the call.id from the dashboard's calls store. Module
+  // `activeCallId` may be null after a prior accept attempt's cleanup() — but
+  // the call still exists on Meta and must still be terminated. Falling back
+  // to the override means hangup is robust to a wiped local session.
+  const endActiveCall = async (callIdOverride = null) => {
+    const callId = activeCallId || callIdOverride;
+    if (!callId) {
+      cleanup();
+      return;
+    }
+    try {
+      // Terminate on Meta first so the contact is disconnected immediately. The
+      // recording upload below can be slow on long calls or poor networks, and
+      // the peer connection / mic must not stay live for the contact during it.
+      await WhatsappCallsAPI.terminate(callId).catch(() => {});
+      await stopRecorderAndUpload(callId);
+    } finally {
+      cleanup();
+    }
+  };
+
+  return {
+    isInitiating: isInitiatingOutboundReadonly,
+    prepareInboundAnswer,
+    prepareOutboundOffer,
+    acceptIncomingCall,
+    rejectIncomingCall,
+    initiateOutboundCall,
+    endActiveCall,
+  };
+}
+
+// Cable handlers fire outside any composable instance, so the shared session
+// surface is exposed as module-level functions for them.
+
+export const applyOutboundAnswer = async (callId, sdpAnswer) => {
+  // No in-flight peer connection in this tab → not our call.
+  if (!pc) return;
+  // /initiate hasn't returned our call id yet (the connect webhook raced
+  // ahead). Buffer the answer; initiateOutboundCall flushes it by id once it
+  // knows which call is ours, so a concurrent agent's answer is never applied.
+  if (activeCallId == null) {
+    pendingOutboundAnswers.set(callId, sdpAnswer);
+    return;
+  }
+  // activeCallId known → only apply the answer for this tab's call.
+  if (callId !== activeCallId) return;
+  await pc.setRemoteDescription({ type: 'answer', sdp: sdpAnswer });
+};
+
+// Called by the cable handler when Meta delivers status=ACCEPTED for the
+// outbound call (real pickup). Flips the recorder gate and starts the
+// MediaRecorder. Idempotent — safe if ontrack hasn't fired yet (setupRecorder
+// bails until the remote stream has audio tracks; ontrack will retry).
+export const armOutboundRecorder = () => {
+  recorderArmed = true;
+  setupRecorder();
+};
+
+export const cleanupWhatsappSession = () => cleanup();
+
+export const handleWhatsappRemoteEnd = async callId => {
+  // Snapshot before cleanup nulls activeCallId.
+  const id = callId || activeCallId;
+  if (!id) {
+    cleanup();
+    return;
+  }
+  try {
+    await stopRecorderAndUpload(id);
+  } finally {
+    cleanup();
+  }
+};
+
+export const setWhatsappCallMuted = muted => {
+  if (!localStream) return false;
+  localStream.getAudioTracks().forEach(track => {
+    track.enabled = !muted;
+  });
+  return muted;
+};
+
+export const sendWhatsappTerminateBeacon = () => {
+  // Always fire when there's a live callId. The beacon endpoint is idempotent,
+  // so racing it with an in-flight Axios terminate (which unload may abort) is
+  // fine — Meta gets exactly one terminate either way, and we avoid leaving
+  // the call ringing on Meta until its carrier-side timeout.
+  if (!activeCallId) return;
+  beaconTerminate(activeCallId);
+};
@@ -0,0 +1,96 @@
+import { ref } from 'vue';
+import {
+  setupFacebookSdk,
+  initWhatsAppEmbeddedSignup,
+  createMessageHandler,
+  isValidBusinessData,
+} from 'dashboard/routes/dashboard/settings/inbox/channels/whatsapp/utils';
+
+// Drives Meta's WhatsApp embedded-signup popup (Facebook JS SDK). FB.login()
+// resolves an auth `code` while the WABA identifiers (waba_id, phone_number_id)
+// arrive separately over a postMessage event — order isn't guaranteed, so we
+// hold both and resolve once both are present.
+//
+// `runEmbeddedSignup` returns the signup credentials; the caller exchanges them
+// for an inbox via `inboxes/createWhatsAppEmbeddedSignup` and owns its own UX
+// (alerts, navigation, etc). Resolves `null` when the user cancels the popup;
+// rejects on SDK load or signup errors. The window listener is scoped to a
+// single run, so this is safe to call from anywhere without lifecycle wiring.
+export function useWhatsappEmbeddedSignup() {
+  const isAuthenticating = ref(false);
+
+  const runEmbeddedSignup = () => {
+    if (isAuthenticating.value) return Promise.resolve(null);
+    isAuthenticating.value = true;
+
+    return new Promise((resolve, reject) => {
+      let authCode = null;
+      let businessData = null;
+      let settled = false;
+      let messageHandler;
+
+      const settle = (fn, value) => {
+        if (settled) return;
+        settled = true;
+        window.removeEventListener('message', messageHandler);
+        isAuthenticating.value = false;
+        fn(value);
+      };
+
+      // Both the auth code and the business data arrive asynchronously and in
+      // no fixed order; only resolve once we're holding both.
+      const resolveIfReady = () => {
+        if (!authCode || !businessData) return;
+        settle(resolve, {
+          code: authCode,
+          business_id: businessData.business_id,
+          waba_id: businessData.waba_id,
+          phone_number_id: businessData.phone_number_id || '',
+        });
+      };
+
+      messageHandler = createMessageHandler(data => {
+        if (
+          data.event === 'FINISH' ||
+          data.event === 'FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING'
+        ) {
+          if (!isValidBusinessData(data.data)) {
+            settle(reject, new Error('Invalid business data'));
+            return;
+          }
+          businessData = data.data;
+          resolveIfReady();
+        } else if (data.event === 'CANCEL') {
+          settle(resolve, null);
+        } else if (data.event === 'error') {
+          settle(reject, new Error(data.error_message || 'Signup error'));
+        }
+      });
+
+      window.addEventListener('message', messageHandler);
+
+      (async () => {
+        try {
+          await setupFacebookSdk(
+            window.chatwootConfig?.whatsappAppId,
+            window.chatwootConfig?.whatsappApiVersion
+          );
+          authCode = await initWhatsAppEmbeddedSignup(
+            window.chatwootConfig?.whatsappConfigurationId
+          );
+          resolveIfReady();
+        } catch (error) {
+          // FB.login() rejects with 'Login cancelled' when the user dismisses
+          // the popup — treat it as a cancel rather than an error.
+          if (error.message === 'Login cancelled') {
+            settle(resolve, null);
+          } else {
+            settle(reject, error);
+          }
+        }
+      })();
+    });
+  };
+
+  return { isAuthenticating, runEmbeddedSignup };
+}