feat: add WhatsApp Business App coexistence feature

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

.codeclimate.yml

@@ -59,4 +59,4 @@ exclude_patterns:
   - 'app/javascript/dashboard/helper/specs/macrosFixtures.js'
   - 'app/javascript/dashboard/routes/dashboard/settings/macros/constants.js'
   - '**/fixtures/**'
-  - '**/*/fixtures.js'
+  - '**/*/fixtures.js'

app/controllers/dashboard_controller.rb

@@ -67,6 +67,8 @@ class DashboardController < ActionController::Base
       FB_APP_ID: GlobalConfigService.load('FB_APP_ID', ''),
       INSTAGRAM_APP_ID: GlobalConfigService.load('INSTAGRAM_APP_ID', ''),
       FACEBOOK_API_VERSION: GlobalConfigService.load('FACEBOOK_API_VERSION', 'v17.0'),
+      WHATSAPP_APP_ID: GlobalConfigService.load('WHATSAPP_APP_ID', ''),
+      WHATSAPP_CONFIGURATION_ID: GlobalConfigService.load('WHATSAPP_CONFIGURATION_ID', ''),
       IS_ENTERPRISE: ChatwootApp.enterprise?,
       AZURE_APP_ID: GlobalConfigService.load('AZURE_APP_ID', ''),
       GIT_SHA: GIT_HASH

app/controllers/super_admin/app_configs_controller.rb

@@ -39,7 +39,8 @@ class SuperAdmin::AppConfigsController < SuperAdmin::ApplicationController
       'email' => ['MAILER_INBOUND_EMAIL_DOMAIN'],
       'linear' => %w[LINEAR_CLIENT_ID LINEAR_CLIENT_SECRET],
       'slack' => %w[SLACK_CLIENT_ID SLACK_CLIENT_SECRET],
-      'instagram' => %w[INSTAGRAM_APP_ID INSTAGRAM_APP_SECRET INSTAGRAM_VERIFY_TOKEN INSTAGRAM_API_VERSION ENABLE_INSTAGRAM_CHANNEL_HUMAN_AGENT]
+      'instagram' => %w[INSTAGRAM_APP_ID INSTAGRAM_APP_SECRET INSTAGRAM_VERIFY_TOKEN INSTAGRAM_API_VERSION ENABLE_INSTAGRAM_CHANNEL_HUMAN_AGENT],
+      'whatsapp_embedded' => %w[WHATSAPP_APP_ID WHATSAPP_APP_SECRET WHATSAPP_CONFIGURATION_ID WHATSAPP_API_VERSION]
     }
 
     @allowed_configs = mapping.fetch(@config, %w[ENABLE_ACCOUNT_SIGNUP FIREBASE_PROJECT_ID FIREBASE_CREDENTIALS])

app/controllers/whatsapp/embedded_controller.rb

@@ -0,0 +1,79 @@
+class Whatsapp::EmbeddedController < ApplicationController
+  include EnsureCurrentAccountHelper
+
+  before_action :authenticate_user!
+  before_action :current_account
+  before_action :check_authorization
+
+  def new
+    # Configuration endpoint for embedded signup initialization
+    render json: {
+      status: 'ready',
+      app_id: GlobalConfigService.load('WHATSAPP_APP_ID', ''),
+      config_id: GlobalConfigService.load('WHATSAPP_CONFIGURATION_ID', ''),
+      app_secret: GlobalConfigService.load('WHATSAPP_APP_SECRET', '')
+    }
+  end
+
+  def embedded_signup
+    # Complete embedded signup using auth code + business info from frontend
+    validate_authorization_code!
+    return if performed?
+
+    validate_required_parameters!
+    return if performed?
+
+    channel = process_signup
+    @inbox = channel.inbox
+
+    # Return the inbox object using the standard jbuilder template
+    render 'embedded_signup', formats: [:json]
+  rescue StandardError => e
+    handle_signup_error(e)
+  end
+
+  private
+
+  def validate_authorization_code!
+    return if params[:code].present?
+
+    render json: {
+      error: 'Missing authorization code',
+      message: 'Authorization code is required for embedded signup'
+    }, status: :bad_request
+  end
+
+  def validate_required_parameters!
+    return if params[:business_id].present? && params[:waba_id].present?
+
+    render json: {
+      error: 'Missing required parameters: business_id and waba_id are required'
+    }, status: :bad_request
+  end
+
+  def process_signup
+    service = Whatsapp::EmbeddedSignupService.new(
+      account: Current.account,
+      code: params[:code],
+      business_id: params[:business_id],
+      waba_id: params[:waba_id],
+      phone_number_id: params[:phone_number_id],
+      is_business_app_onboarding: params[:is_business_app_onboarding]
+    )
+
+    service.perform
+  end
+
+  def handle_signup_error(error)
+    Rails.logger.error("WhatsApp embedded signup processing error: #{error.message}")
+    Rails.logger.error(error.backtrace.join("\n"))
+    render json: {
+      error: 'Internal server error',
+      message: error.message
+    }, status: :internal_server_error
+  end
+
+  def check_authorization
+    authorize(Current.account, :update?)
+  end
+end

app/javascript/dashboard/composables/useWhatsappEmbeddedSignup.js

@@ -0,0 +1,371 @@
+import { ref, computed } from 'vue';
+import { useStore } from 'vuex';
+import { useRouter } from 'vue-router';
+import { useI18n } from 'vue-i18n';
+import { useAlert } from 'dashboard/composables';
+import Auth from 'dashboard/api/auth';
+
+export function useWhatsappEmbeddedSignup() {
+  const store = useStore();
+  const router = useRouter();
+  const { t } = useI18n();
+
+  // State
+  const fbSdkLoaded = ref(false);
+  const isProcessing = ref(false);
+  const processingMessage = ref('');
+  const authCodeReceived = ref(false);
+  const authCode = ref(null);
+  const businessData = ref(null);
+  const isAuthenticating = ref(false);
+
+  // Computed
+  const authHeaders = computed(() => {
+    if (Auth.hasAuthCookie()) {
+      const {
+        'access-token': accessToken,
+        'token-type': tokenType,
+        client,
+        expiry,
+        uid,
+      } = Auth.getAuthData();
+      return {
+        'access-token': accessToken,
+        'token-type': tokenType,
+        client,
+        expiry,
+        uid,
+      };
+    }
+    return {};
+  });
+
+  const benefits = computed(() => [
+    {
+      key: 'EASY_SETUP',
+      text: t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.BENEFITS.EASY_SETUP'),
+    },
+    {
+      key: 'SECURE_AUTH',
+      text: t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.BENEFITS.SECURE_AUTH'),
+    },
+    {
+      key: 'AUTO_CONFIG',
+      text: t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.BENEFITS.AUTO_CONFIG'),
+    },
+  ]);
+
+  const showLoader = computed(
+    () => isAuthenticating.value || isProcessing.value
+  );
+
+  // Error handling
+  const handleSignupError = data => {
+    isProcessing.value = false;
+    authCodeReceived.value = false;
+    isAuthenticating.value = false;
+
+    const errorMessage =
+      data.error ||
+      data.message ||
+      t('INBOX_MGMT.ADD.WHATSAPP.API.ERROR_MESSAGE');
+    useAlert(errorMessage);
+  };
+
+  const handleSignupCancellation = data => {
+    isProcessing.value = false;
+    authCodeReceived.value = false;
+    isAuthenticating.value = false;
+
+    let message = t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.CANCELLED');
+    if (data.data?.current_step) {
+      message += ` (Step: ${data.data.current_step})`;
+    }
+
+    useAlert(message);
+  };
+
+  const handleSignupSuccess = inboxData => {
+    isProcessing.value = false;
+    isAuthenticating.value = false;
+
+    // Update the store with the new inbox data
+    if (inboxData && inboxData.id) {
+      // Add the new inbox to the store
+      store.commit('inboxes/ADD_INBOXES', inboxData);
+
+      useAlert(t('INBOX_MGMT.FINISH.MESSAGE'));
+
+      router.replace({
+        name: 'settings_inboxes_add_agents',
+        params: {
+          page: 'new',
+          inbox_id: inboxData.id,
+        },
+      });
+    } else {
+      // Fallback if inbox data is not properly formatted
+      useAlert(t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.SUCCESS_FALLBACK'));
+      router.replace({
+        name: 'settings_inbox_list',
+      });
+    }
+  };
+
+  // Signup flow
+  const completeSignupFlow = async businessDataParam => {
+    if (!authCodeReceived.value || !authCode.value) {
+      handleSignupError({
+        error: t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.AUTH_NOT_COMPLETED'),
+      });
+      return;
+    }
+
+    isProcessing.value = true;
+
+    // Show different processing messages based on the signup type
+    if (businessDataParam.is_business_app_onboarding) {
+      processingMessage.value = t(
+        'INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.PROCESSING_BUSINESS_APP'
+      );
+    } else {
+      processingMessage.value = t(
+        'INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.PROCESSING_NEW_NUMBER'
+      );
+    }
+
+    try {
+      // Send both auth code and business info together (synchronous flow)
+      const accountId = store.getters.getCurrentAccountId;
+      const response = await fetch('/whatsapp/embedded_signup', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-CSRF-Token': document
+            .querySelector('meta[name="csrf-token"]')
+            ?.getAttribute('content'),
+          ...authHeaders.value,
+        },
+        body: JSON.stringify({
+          account_id: accountId,
+          code: authCode.value,
+          business_id: businessDataParam.business_id,
+          waba_id: businessDataParam.waba_id,
+          phone_number_id: businessDataParam.phone_number_id,
+          is_business_app_onboarding:
+            businessDataParam.is_business_app_onboarding || false,
+        }),
+      });
+
+      const responseData = await response.json();
+
+      if (response.ok) {
+        // Clear the stored auth code for security
+        authCode.value = null;
+
+        // Handle synchronous success response
+        handleSignupSuccess(responseData);
+      } else {
+        throw new Error(responseData.message || responseData.error);
+      }
+    } catch (error) {
+      handleSignupError({ error: error.message });
+    }
+  };
+
+  const isValidBusinessData = businessDataLocal => {
+    return (
+      businessDataLocal &&
+      (businessDataLocal.business_id || businessDataLocal.businessId) &&
+      (businessDataLocal.waba_id || businessDataLocal.wabaId)
+    );
+  };
+
+  // Message handling
+  const handleEmbeddedSignupData = async data => {
+    // Handle different embedded signup events per Facebook documentation
+    if (
+      data.event === 'FINISH' ||
+      data.event === 'FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING'
+    ) {
+      // Facebook might send business data in different structures
+      let businessDataLocal = data.data;
+
+      // If data.data doesn't exist, try other possible structures
+      if (!businessDataLocal) {
+        businessDataLocal = data.business_data || data.details || data;
+      }
+
+      // Validate we have the required business information
+      if (isValidBusinessData(businessDataLocal)) {
+        // Normalize the data structure to match our backend expectations
+        const normalizedData = {
+          business_id:
+            businessDataLocal.business_id || businessDataLocal.businessId,
+          waba_id: businessDataLocal.waba_id || businessDataLocal.wabaId,
+          phone_number_id:
+            businessDataLocal.phone_number_id ||
+            businessDataLocal.phoneNumberId ||
+            businessDataLocal.phone_id,
+          // Indicate if this is an existing WhatsApp Business App onboarding (coexistence)
+          is_business_app_onboarding:
+            data.event === 'FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING',
+        };
+
+        // Store business data
+        businessData.value = normalizedData;
+        // Check if we already have auth code and process immediately
+        if (authCodeReceived.value && authCode.value) {
+          await completeSignupFlow(normalizedData);
+        } else {
+          processingMessage.value = t(
+            'INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.WAITING_FOR_AUTH'
+          );
+        }
+      } else {
+        handleSignupError({
+          error: t(
+            'INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.INVALID_BUSINESS_DATA'
+          ),
+        });
+      }
+    } else if (data.event === 'CANCEL') {
+      handleSignupCancellation(data);
+    } else if (data.event === 'error') {
+      handleSignupError({
+        error:
+          data.error_message ||
+          t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.SIGNUP_ERROR'),
+        error_id: data.error_id,
+        session_id: data.session_id,
+      });
+    }
+  };
+
+  const fbLoginCallback = response => {
+    if (response.authResponse && response.authResponse.code) {
+      // Authorization code received from Facebook
+      authCode.value = response.authResponse.code;
+      authCodeReceived.value = true;
+      processingMessage.value = t(
+        'INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.WAITING_FOR_BUSINESS_INFO'
+      );
+
+      // Check if we already have business data and process immediately
+      if (businessData.value) {
+        completeSignupFlow(businessData.value);
+      }
+    } else if (response.error) {
+      handleSignupError({ error: response.error });
+    } else {
+      isProcessing.value = false;
+      isAuthenticating.value = false;
+      useAlert(t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.CANCELLED'));
+    }
+  };
+
+  const handleSignupMessage = event => {
+    // Handle Facebook embedded signup message events
+    try {
+      const originUrl = new URL(event.origin);
+      const allowedHosts = ['facebook.com', 'www.facebook.com'];
+      if (!allowedHosts.includes(originUrl.hostname)) return;
+    } catch (error) {
+      // Invalid origin URL, reject the event
+      return;
+    }
+
+    try {
+      const data = JSON.parse(event.data);
+
+      if (data.type === 'WA_EMBEDDED_SIGNUP') {
+        handleEmbeddedSignupData(data);
+      }
+    } catch (error) {
+      // Handle non-JSON messages silently
+    }
+  };
+
+  // Facebook SDK
+  const loadFacebookSdk = () => {
+    if (window.FB) {
+      fbSdkLoaded.value = true;
+      return;
+    }
+    const script = document.createElement('script');
+    script.src = 'https://connect.facebook.net/en_US/sdk.js';
+    script.async = true;
+    script.defer = true;
+    script.onload = () => {
+      window.FB.init({
+        appId: window.chatwootConfig?.whatsappAppId,
+        status: true,
+        xfbml: true,
+        version: window.chatwootConfig?.whatsappApiVersion || 'v22.0',
+      });
+      fbSdkLoaded.value = true;
+    };
+    document.body.appendChild(script);
+  };
+
+  const launchEmbeddedSignup = () => {
+    processingMessage.value = t(
+      'INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.AUTH_PROCESSING'
+    );
+
+    if (!window.FB) {
+      loadFacebookSdk();
+      setTimeout(() => launchEmbeddedSignup(), 1000);
+      return;
+    }
+
+    isAuthenticating.value = true;
+
+    // Following Facebook's embedded signup documentation
+    window.FB.login(fbLoginCallback, {
+      config_id: window.chatwootConfig?.whatsappConfigurationId,
+      response_type: 'code',
+      override_default_response_type: true,
+      extras: {
+        setup: {},
+        featureType: 'whatsapp_business_app_onboarding', // Enable WhatsApp Business App coexistence
+        sessionInfoVersion: '3',
+      },
+    });
+  };
+
+  // Lifecycle
+  const setupMessageListener = () => {
+    window.addEventListener('message', handleSignupMessage);
+  };
+
+  const cleanupMessageListener = () => {
+    window.removeEventListener('message', handleSignupMessage);
+  };
+
+  // Initialize
+  const initialize = () => {
+    loadFacebookSdk();
+    setupMessageListener();
+  };
+
+  return {
+    // State
+    fbSdkLoaded,
+    isProcessing,
+    processingMessage,
+    authCodeReceived,
+    authCode,
+    businessData,
+    isAuthenticating,
+
+    // Computed
+    benefits,
+    showLoader,
+
+    // Methods
+    launchEmbeddedSignup,
+    initialize,
+    cleanupMessageListener,
+  };
+}

app/javascript/dashboard/i18n/locale/en/inboxMgmt.json

@@ -222,10 +222,17 @@
         "DESC": "Start supporting your customers via WhatsApp.",
         "PROVIDERS": {
           "LABEL": "API Provider",
+          "WHATSAPP_EMBEDDED": "WhatsApp Business",
           "TWILIO": "Twilio",
           "WHATSAPP_CLOUD": "WhatsApp Cloud",
+          "WHATSAPP_CLOUD_DESC": "Quick setup through Meta",
+          "TWILIO_DESC": "Connect via Twilio credentials",
           "360_DIALOG": "360Dialog"
         },
+        "SELECT_PROVIDER": {
+          "TITLE": "Select your API provider",
+          "DESCRIPTION": "Choose your WhatsApp provider. You can connect directly through Meta which requires no setup, or connect through Twilio using your account credentials."
+        },
         "INBOX_NAME": {
           "LABEL": "Inbox Name",
           "PLACEHOLDER": "Please enter an inbox name",
@@ -260,10 +267,36 @@
         "API_CALLBACK": {
           "TITLE": "Callback URL",
           "SUBTITLE": "You have to configure the webhook URL and the verification token in the Facebook Developer portal with the values shown below.",
+          "SUBTITLE_EMBEDDED": "We have configured the webhook URL and the verification token in the Facebook Developer portal with the values shown below.",
           "WEBHOOK_URL": "Webhook URL",
           "WEBHOOK_VERIFICATION_TOKEN": "Webhook Verification Token"
         },
         "SUBMIT_BUTTON": "Create WhatsApp Channel",
+        "EMBEDDED_SIGNUP": {
+          "TITLE": "Quick Setup with Meta",
+          "DESC": "You will be redirected to Meta to log into your WhatsApp Business account. Having admin access will help make the setup smooth and easy.",
+          "BENEFITS": {
+            "TITLE": "Benefits of Embedded Signup:",
+            "EASY_SETUP": "No manual configuration required",
+            "SECURE_AUTH": "Secure OAuth based authentication",
+            "AUTO_CONFIG": "Automatic webhook and phone number configuration"
+          },
+          "SUBMIT_BUTTON": "Connect with WhatsApp Business",
+          "AUTH_PROCESSING": "Authenticating with Meta",
+          "WAITING_FOR_BUSINESS_INFO": "Please complete business setup in the Meta window...",
+          "PROCESSING": "Setting up your WhatsApp Business Account",
+          "LOADING_SDK": "Loading Facebook SDK...",
+          "CANCELLED": "WhatsApp Signup was cancelled",
+          "SUCCESS_TITLE": "WhatsApp Business Account Connected!",
+          "SUCCESS_TITLE_BUSINESS_APP": "WhatsApp Business App Connected!",
+          "WAITING_FOR_AUTH": "Waiting for authentication...",
+          "INVALID_BUSINESS_DATA": "Invalid business data received from Facebook. Please try again.",
+          "SIGNUP_ERROR": "Signup error occurred",
+          "PROCESSING_BUSINESS_APP": "Connecting your existing WhatsApp Business App...",
+          "PROCESSING_NEW_NUMBER": "Setting up your new WhatsApp Business number...",
+          "AUTH_NOT_COMPLETED": "Authentication not completed. Please restart the process.",
+          "SUCCESS_FALLBACK": "WhatsApp Business Account has been successfully configured"
+        },
         "API": {
           "ERROR_MESSAGE": "We were not able to save the WhatsApp channel"
         }

app/javascript/dashboard/routes/dashboard/settings/inbox/FinishSetup.vue

@@ -67,9 +67,14 @@ export default {
       }
 
       if (this.isWhatsAppCloudInbox) {
-        return `${this.$t('INBOX_MGMT.FINISH.MESSAGE')}. ${this.$t(
-          'INBOX_MGMT.ADD.WHATSAPP.API_CALLBACK.SUBTITLE'
-        )}`;
+        const isEmbeddedSignup =
+          this.currentInbox.provider_config?.source === 'embedded_signup';
+
+        const subtitleKey = isEmbeddedSignup
+          ? 'INBOX_MGMT.ADD.WHATSAPP.API_CALLBACK.SUBTITLE_EMBEDDED'
+          : 'INBOX_MGMT.ADD.WHATSAPP.API_CALLBACK.SUBTITLE';
+
+        return `${this.$t('INBOX_MGMT.FINISH.MESSAGE')}. ${this.$t(subtitleKey)}`;
       }
 
       if (this.isAEmailInbox && !this.currentInbox.provider) {

app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Whatsapp.vue

@@ -1,48 +1,138 @@
-<script>
-import PageHeader from '../../SettingsSubPageHeader.vue';
+<script setup>
+import { computed } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { useI18n } from 'vue-i18n';
 import Twilio from './Twilio.vue';
 import ThreeSixtyDialogWhatsapp from './360DialogWhatsapp.vue';
 import CloudWhatsapp from './CloudWhatsapp.vue';
+import WhatsappEmbeddedSignup from './WhatsappEmbeddedSignup.vue';
+import whatsappIcon from 'dashboard/assets/images/whatsapp.png';
+import twilioIcon from 'dashboard/assets/images/twilio.png';
 
-export default {
-  components: {
-    PageHeader,
-    Twilio,
-    ThreeSixtyDialogWhatsapp,
-    CloudWhatsapp,
+const route = useRoute();
+const router = useRouter();
+const { t } = useI18n();
+
+const PROVIDER_TYPES = {
+  WHATSAPP: 'whatsapp',
+  TWILIO: 'twilio',
+  WHATSAPP_CLOUD: 'whatsapp_cloud',
+  WHATSAPP_EMBEDDED: 'whatsapp_embedded',
+  THREE_SIXTY_DIALOG: '360dialog',
+};
+
+const hasWhatsappAppId = computed(() => {
+  return (
+    window.chatwootConfig?.whatsappAppId &&
+    window.chatwootConfig.whatsappAppId !== 'none'
+  );
+});
+
+const selectedProvider = computed(() => route.query.provider);
+
+const showProviderSelection = computed(() => !selectedProvider.value);
+
+const showConfiguration = computed(() => Boolean(selectedProvider.value));
+
+const availableProviders = computed(() => [
+  {
+    value: PROVIDER_TYPES.WHATSAPP,
+    label: t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.WHATSAPP_CLOUD'),
+    description: t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.WHATSAPP_CLOUD_DESC'),
+    icon: whatsappIcon,
   },
-  data() {
-    return {
-      provider: 'whatsapp_cloud',
-    };
+  {
+    value: PROVIDER_TYPES.TWILIO,
+    label: t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.TWILIO'),
+    description: t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.TWILIO_DESC'),
+    icon: twilioIcon,
   },
+]);
+
+const selectProvider = providerValue => {
+  router.push({
+    name: route.name,
+    params: route.params,
+    query: { provider: providerValue },
+  });
+};
+
+const shouldShowEmbeddedSignup = provider => {
+  return (
+    (provider === PROVIDER_TYPES.WHATSAPP && hasWhatsappAppId.value) ||
+    provider === PROVIDER_TYPES.WHATSAPP_EMBEDDED
+  );
+};
+
+const shouldShowCloudWhatsapp = provider => {
+  return provider === PROVIDER_TYPES.WHATSAPP && !hasWhatsappAppId.value;
 };
 </script>
 
 <template>
   <div
-    class="border border-n-weak bg-n-solid-1 rounded-t-lg border-b-0 h-full w-full p-6 col-span-6 overflow-auto"
+    class="w-full h-full col-span-6 p-6 overflow-auto border border-b-0 rounded-t-lg border-n-weak bg-n-solid-1"
   >
-    <PageHeader
-      :header-title="$t('INBOX_MGMT.ADD.WHATSAPP.TITLE')"
-      :header-content="$t('INBOX_MGMT.ADD.WHATSAPP.DESC')"
-    />
-    <div class="flex-shrink-0 flex-grow-0">
-      <label>
-        {{ $t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.LABEL') }}
-        <select v-model="provider">
-          <option value="whatsapp_cloud">
-            {{ $t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.WHATSAPP_CLOUD') }}
-          </option>
-          <option value="twilio">
-            {{ $t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.TWILIO') }}
-          </option>
-        </select>
-      </label>
+    <!-- Provider Selection View -->
+    <div v-if="showProviderSelection">
+      <div class="mb-10 text-left">
+        <h1 class="mb-2 text-lg font-medium text-slate-12">
+          {{ $t('INBOX_MGMT.ADD.WHATSAPP.SELECT_PROVIDER.TITLE') }}
+        </h1>
+        <p class="text-sm leading-relaxed text-slate-11">
+          {{ $t('INBOX_MGMT.ADD.WHATSAPP.SELECT_PROVIDER.DESCRIPTION') }}
+        </p>
+      </div>
+
+      <!-- Dynamic Provider Cards -->
+      <div class="flex justify-start gap-6">
+        <div
+          v-for="provider in availableProviders"
+          :key="provider.value"
+          class="gap-6 px-5 py-6 transition-all duration-200 border cursor-pointer w-96 border-n-weak rounded-2xl hover:bg-n-slate-3"
+          @click="selectProvider(provider.value)"
+        >
+          <!-- Provider Icon -->
+          <div class="flex justify-start mb-5">
+            <div class="flex items-center justify-center w-12 h-12 rounded-lg">
+              <img
+                :src="provider.icon"
+                :alt="provider.label"
+                class="object-contain w-10 h-10"
+              />
+            </div>
+          </div>
+
+          <!-- Card Content -->
+          <div class="text-left">
+            <h3 class="mb-1.5 text-sm font-medium text-slate-12">
+              {{ provider.label }}
+            </h3>
+            <p class="text-sm text-slate-11">
+              {{ provider.description }}
+            </p>
+          </div>
+        </div>
+      </div>
     </div>
 
-    <Twilio v-if="provider === 'twilio'" type="whatsapp" />
-    <ThreeSixtyDialogWhatsapp v-else-if="provider === '360dialog'" />
-    <CloudWhatsapp v-else />
+    <!-- Configuration View -->
+    <div v-else-if="showConfiguration">
+      <div class="p-8 border bg-n-solid-2 border-n-weak rounded-2xl">
+        <!-- Provider Configuration Forms -->
+        <WhatsappEmbeddedSignup
+          v-if="shouldShowEmbeddedSignup(selectedProvider)"
+        />
+        <CloudWhatsapp v-else-if="shouldShowCloudWhatsapp(selectedProvider)" />
+        <Twilio
+          v-else-if="selectedProvider === PROVIDER_TYPES.TWILIO"
+          type="whatsapp"
+        />
+        <ThreeSixtyDialogWhatsapp
+          v-else-if="selectedProvider === PROVIDER_TYPES.THREE_SIXTY_DIALOG"
+        />
+        <CloudWhatsapp v-else />
+      </div>
+    </div>
   </div>
 </template>

app/javascript/dashboard/routes/dashboard/settings/inbox/channels/WhatsappEmbeddedSignup.vue

@@ -0,0 +1,85 @@
+<script setup>
+import { onMounted, onBeforeUnmount } from 'vue';
+import Icon from 'next/icon/Icon.vue';
+import NextButton from 'next/button/Button.vue';
+import LoadingState from 'dashboard/components/widgets/LoadingState.vue';
+import whatsappIcon from 'dashboard/assets/images/whatsapp.png';
+import { useWhatsappEmbeddedSignup } from 'dashboard/composables/useWhatsappEmbeddedSignup';
+
+const {
+  fbSdkLoaded,
+  processingMessage,
+  isAuthenticating,
+  benefits,
+  showLoader,
+  launchEmbeddedSignup,
+  initialize,
+  cleanupMessageListener,
+} = useWhatsappEmbeddedSignup();
+
+onMounted(() => {
+  initialize();
+});
+
+onBeforeUnmount(() => {
+  cleanupMessageListener();
+});
+</script>
+
+<template>
+  <div class="h-full">
+    <LoadingState v-if="showLoader" :message="processingMessage" />
+
+    <div v-else>
+      <div class="flex flex-col items-start mb-4 text-left">
+        <div class="flex justify-start mb-5">
+          <div class="flex items-center justify-center w-12 h-12 rounded-lg">
+            <img
+              :src="whatsappIcon"
+              :alt="$t('INBOX_MGMT.ADD.WHATSAPP.PROVIDERS.WHATSAPP_CLOUD')"
+              class="object-contain w-10 h-10"
+            />
+          </div>
+        </div>
+
+        <h3 class="mb-2 text-lg font-medium text-slate-12">
+          {{ $t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.TITLE') }}
+        </h3>
+        <p class="text-sm leading-relaxed text-slate-12">
+          {{ $t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.DESC') }}
+        </p>
+      </div>
+
+      <div class="flex flex-col gap-2 mb-8">
+        <div
+          v-for="benefit in benefits"
+          :key="benefit.key"
+          class="flex items-center gap-2 text-sm text-slate-11"
+        >
+          <Icon icon="i-lucide-check" class="text-slate-11" />
+          {{ benefit.text }}
+        </div>
+      </div>
+
+      <div class="flex">
+        <NextButton
+          :disabled="!fbSdkLoaded || isAuthenticating"
+          :loading="isAuthenticating"
+          faded
+          slate
+          class="w-full"
+          @click="launchEmbeddedSignup"
+        >
+          {{ $t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.SUBMIT_BUTTON') }}
+        </NextButton>
+      </div>
+
+      <p
+        v-if="!fbSdkLoaded"
+        class="mt-3 text-xs text-left text-slate-500 dark:text-slate-400"
+      >
+        {{ $t('INBOX_MGMT.ADD.WHATSAPP.EMBEDDED_SIGNUP.LOADING_SDK') }}
+      </p>
+    </div>
+  </div>
+</template>

app/jobs/webhooks/whatsapp_events_job.rb

@@ -5,10 +5,38 @@ class Webhooks::WhatsappEventsJob < ApplicationJob
     channel = find_channel_from_whatsapp_business_payload(params)
 
     if channel_is_inactive?(channel)
+      Rails.logger.info("Channel is inactive: #{channel.inspect}")
       Rails.logger.warn("Inactive WhatsApp channel: #{channel&.phone_number || "unknown - #{params[:phone_number]}"}")
       return
     end
 
+    # Handle different webhook event types
+    if sync_event?(params)
+      handle_sync_events(channel, params)
+    else
+      handle_message_events(channel, params)
+    end
+  end
+
+  private
+
+  def sync_event?(params)
+    field = params.dig(:entry, 0, :changes, 0, :field)
+    %w[smb_app_state_sync smb_message_echoes history].include?(field)
+  end
+
+  def handle_sync_events(channel, params)
+    field = params.dig(:entry, 0, :changes, 0, :field)
+
+    case field
+    when 'smb_app_state_sync'
+      Whatsapp::ContactSyncService.new(inbox: channel.inbox, params: params).perform
+    when 'smb_message_echoes', 'history'
+      Whatsapp::ConversationSyncService.new(inbox: channel.inbox, params: params).perform
+    end
+  end
+
+  def handle_message_events(channel, params)
     case channel.provider
     when 'whatsapp_cloud'
       Whatsapp::IncomingMessageWhatsappCloudService.new(inbox: channel.inbox, params: params).perform
@@ -17,8 +45,6 @@ class Webhooks::WhatsappEventsJob < ApplicationJob
     end
   end
 
-  private
-
   def channel_is_inactive?(channel)
     return true if channel.blank?
     return true if channel.reauthorization_required?

app/services/whatsapp/contact_sync_service.rb

@@ -0,0 +1,97 @@
+class Whatsapp::ContactSyncService
+  include Rails.application.routes.url_helpers
+
+  pattr_initialize [:inbox!, :params!]
+
+  def perform
+    return unless valid_sync_event?
+
+    sync_contacts_from_webhook
+  end
+
+  private
+
+  def valid_sync_event?
+    return false unless params.dig(:entry, 0, :changes, 0, :field) == 'smb_app_state_sync'
+    return false if params.dig(:entry, 0, :changes, 0, :value, :state_sync).blank?
+
+    true
+  end
+
+  def sync_contacts_from_webhook
+    state_sync_data = params.dig(:entry, 0, :changes, 0, :value, :state_sync)
+
+    state_sync_data.each do |sync_item|
+      next unless sync_item[:type] == 'contact'
+
+      process_contact_sync(sync_item)
+    end
+  end
+
+  def process_contact_sync(sync_item)
+    contact_data = sync_item[:contact]
+    action = sync_item[:action]
+    phone_number = contact_data[:phone_number]
+
+    case action
+    when 'add'
+      create_or_update_contact(contact_data, phone_number)
+    when 'remove'
+      remove_contact(phone_number)
+    else
+      Rails.logger.warn "[WHATSAPP] Unknown contact sync action: #{action}"
+    end
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP] Contact sync failed for #{phone_number}: #{e.message}"
+  end
+
+  def create_or_update_contact(contact_data, phone_number)
+    formatted_phone = format_phone_number(phone_number)
+
+    # Find existing contact or create new one
+    contact_inbox = ::ContactInboxWithContactBuilder.new(
+      source_id: phone_number, # WhatsApp uses phone number without + as source_id
+      inbox: inbox,
+      contact_attributes: {
+        name: contact_data[:full_name] || contact_data[:first_name] || formatted_phone,
+        phone_number: formatted_phone,
+        additional_attributes: {
+          whatsapp_contact_synced: true,
+          whatsapp_contact_sync_timestamp: Time.current.to_i,
+          whatsapp_contact_first_name: contact_data[:first_name],
+          whatsapp_contact_full_name: contact_data[:full_name]
+        }
+      }
+    ).perform
+
+    Rails.logger.info "[WHATSAPP] Contact synced: #{contact_data[:full_name]} (#{formatted_phone})"
+    contact_inbox
+  end
+
+  def remove_contact(phone_number)
+    # Find the contact inbox for this phone number
+    contact_inbox = inbox.contact_inboxes.find_by(source_id: phone_number)
+
+    if contact_inbox
+      # Mark contact as removed from WhatsApp Business App (don't delete to preserve conversation history)
+      contact = contact_inbox.contact
+      contact.additional_attributes ||= {}
+      contact.additional_attributes[:whatsapp_contact_removed] = true
+      contact.additional_attributes[:whatsapp_contact_removed_timestamp] = Time.current.to_i
+      contact.save!
+
+      Rails.logger.info "[WHATSAPP] Contact marked as removed: #{contact.name} (#{contact.phone_number})"
+    else
+      Rails.logger.warn "[WHATSAPP] Contact not found for removal: #{phone_number}"
+    end
+  end
+
+  def format_phone_number(phone_number)
+    # Ensure phone number starts with + for consistency
+    phone_number.start_with?('+') ? phone_number : "+#{phone_number}"
+  end
+
+  def account
+    @account ||= inbox.account
+  end
+end

app/services/whatsapp/conversation_sync_service.rb

@@ -0,0 +1,288 @@
+class Whatsapp::ConversationSyncService
+  include Rails.application.routes.url_helpers
+  include ::Whatsapp::IncomingMessageServiceHelpers
+
+  pattr_initialize [:inbox!, :params!]
+
+  def perform
+    return unless valid_sync_event?
+
+    if history_sync_event?
+      process_history_sync
+    elsif message_echo_event?
+      process_message_echo
+    end
+  end
+
+  private
+
+  def valid_sync_event?
+    # Check for history sync or message echo events
+    history_sync_event? || message_echo_event?
+  end
+
+  def history_sync_event?
+    params.dig(:entry, 0, :changes, 0, :field) == 'history'
+  end
+
+  def message_echo_event?
+    params.dig(:entry, 0, :changes, 0, :field) == 'smb_message_echoes'
+  end
+
+  def process_history_sync
+    history_data = params.dig(:entry, 0, :changes, 0, :value, :history)
+
+    return handle_history_sync_error if history_data&.dig(0, :errors).present?
+
+    history_data.each do |history_item|
+      next if history_item[:data].blank?
+
+      sync_historical_data(history_item[:data])
+    end
+  end
+
+  def handle_history_sync_error
+    error_info = params.dig(:entry, 0, :changes, 0, :value, :history, 0, :errors, 0)
+    Rails.logger.warn "[WHATSAPP] History sync declined or failed: #{error_info[:message]}"
+  end
+
+  def sync_historical_data(data)
+    contacts = data[:contacts] || []
+    messages = data[:messages] || []
+
+    # First, ensure contacts exist
+    contacts.each { |contact_data| create_contact_from_history(contact_data) }
+
+    # Then, sync historical messages
+    messages.each { |message_data| create_message_from_history(message_data) }
+  end
+
+  def create_contact_from_history(contact_data)
+    phone_number = contact_data[:wa_id]
+    contact_name = contact_data.dig(:profile, :name) || phone_number
+
+    ::ContactInboxWithContactBuilder.new(
+      source_id: phone_number,
+      inbox: inbox,
+      contact_attributes: {
+        name: contact_name,
+        phone_number: format_phone_number(phone_number),
+        additional_attributes: {
+          whatsapp_contact_synced: true,
+          whatsapp_history_synced: true,
+          whatsapp_history_sync_timestamp: Time.current.to_i
+        }
+      }
+    ).perform
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP] Failed to create contact from history: #{e.message}"
+  end
+
+  def create_message_from_history(message_data)
+    return unless valid_message_data?(message_data)
+
+    phone_number = message_data[:from]
+    contact_inbox = find_or_create_contact_inbox(phone_number)
+    return unless contact_inbox
+
+    conversation = find_or_create_conversation(contact_inbox)
+    return unless conversation
+
+    create_historical_message(message_data, conversation, contact_inbox.contact)
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP] Failed to create historical message: #{e.message}"
+  end
+
+  def process_message_echo
+    message_echoes = params.dig(:entry, 0, :changes, 0, :value, :message_echoes) || []
+
+    message_echoes.each do |echo_data|
+      create_echo_message(echo_data)
+    end
+  end
+
+  def create_echo_message(echo_data)
+    return unless valid_echo_data?(echo_data)
+
+    to_phone_number = echo_data[:to]
+    echo_data[:from]
+
+    # Find the contact this message was sent to
+    contact_inbox = find_contact_inbox_by_phone(to_phone_number)
+    return unless contact_inbox
+
+    conversation = find_or_create_conversation(contact_inbox)
+    return unless conversation
+
+    # Create outgoing message (sent from business via WhatsApp Business App)
+    create_echo_message_record(echo_data, conversation, contact_inbox.contact)
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP] Failed to create echo message: #{e.message}"
+  end
+
+  def valid_message_data?(message_data)
+    message_data[:id].present? &&
+      message_data[:from].present? &&
+      message_data[:timestamp].present? &&
+      message_data[:type].present?
+  end
+
+  def valid_echo_data?(echo_data)
+    echo_data[:id].present? &&
+      echo_data[:to].present? &&
+      echo_data[:from].present? &&
+      echo_data[:timestamp].present? &&
+      echo_data[:type].present?
+  end
+
+  def find_or_create_contact_inbox(phone_number)
+    contact_inbox = inbox.contact_inboxes.find_by(source_id: phone_number)
+    return contact_inbox if contact_inbox
+
+    # Create contact if not exists
+    ::ContactInboxWithContactBuilder.new(
+      source_id: phone_number,
+      inbox: inbox,
+      contact_attributes: {
+        name: format_phone_number(phone_number),
+        phone_number: format_phone_number(phone_number),
+        additional_attributes: {
+          whatsapp_history_synced: true
+        }
+      }
+    ).perform
+  end
+
+  def find_contact_inbox_by_phone(phone_number)
+    # For echo messages, we need to find contact by their WhatsApp ID (without +)
+    inbox.contact_inboxes.find_by(source_id: phone_number)
+  end
+
+  def find_or_create_conversation(contact_inbox)
+    # Look for existing conversation or create new one
+    conversation = if inbox.lock_to_single_conversation
+                     contact_inbox.conversations.last
+                   else
+                     contact_inbox.conversations.where.not(status: :resolved).last
+                   end
+
+    return conversation if conversation
+
+    ::Conversation.create!(
+      account_id: inbox.account_id,
+      inbox_id: inbox.id,
+      contact_id: contact_inbox.contact_id,
+      contact_inbox_id: contact_inbox.id,
+      additional_attributes: {
+        whatsapp_history_synced: true
+      }
+    )
+  end
+
+  def create_historical_message(message_data, conversation, contact)
+    # Skip if message already exists
+    return if conversation.messages.find_by(source_id: message_data[:id])
+
+    message_content = extract_message_content(message_data)
+    external_timestamp = Time.zone.at(message_data[:timestamp].to_i)
+
+    message = conversation.messages.build(
+      content: message_content,
+      account_id: inbox.account_id,
+      inbox_id: inbox.id,
+      message_type: :incoming,
+      sender: contact,
+      source_id: message_data[:id],
+      created_at: external_timestamp,
+      content_attributes: {
+        external_created_at: external_timestamp.iso8601,
+        whatsapp_history_synced: true
+      }
+    )
+
+    # Handle different message types
+    case message_data[:type]
+    when 'image', 'audio', 'video', 'document'
+      attach_media_from_history(message, message_data)
+    when 'location'
+      attach_location_from_history(message, message_data)
+    end
+
+    message.save!
+    Rails.logger.info "[WHATSAPP] Historical message synced: #{message_data[:id]}"
+  end
+
+  def create_echo_message_record(echo_data, conversation, _contact)
+    # Skip if message already exists
+    return if conversation.messages.find_by(source_id: echo_data[:id])
+
+    message_content = extract_message_content(echo_data)
+    external_timestamp = Time.zone.at(echo_data[:timestamp].to_i)
+
+    message = conversation.messages.build(
+      content: message_content,
+      account_id: inbox.account_id,
+      inbox_id: inbox.id,
+      message_type: :outgoing, # This is a message sent by the business
+      sender: nil, # Business messages don't have a sender contact
+      source_id: echo_data[:id],
+      created_at: external_timestamp,
+      content_attributes: {
+        external_created_at: external_timestamp.iso8601,
+        whatsapp_echo_message: true
+      }
+    )
+
+    message.save!
+    Rails.logger.info "[WHATSAPP] Echo message synced: #{echo_data[:id]}"
+  end
+
+  def extract_message_content(message_data)
+    case message_data[:type]
+    when 'text'
+      message_data.dig(:text, :body)
+    when 'image', 'audio', 'video', 'document'
+      message_data.dig(message_data[:type].to_sym, :caption) || message_data[:type].humanize
+    when 'location'
+      location = message_data[:location]
+      "Location: #{location[:name] || 'Shared location'}"
+    else
+      message_data[:type].humanize
+    end
+  end
+
+  def attach_media_from_history(message, message_data)
+    # NOTE: Historical media might not be available for download
+    # We'll just record the media info in content_attributes
+    media_data = message_data[message_data[:type].to_sym] || {}
+
+    message.content_attributes[:media_info] = {
+      type: message_data[:type],
+      caption: media_data[:caption],
+      filename: media_data[:filename],
+      mime_type: media_data[:mime_type],
+      sha256: media_data[:sha256],
+      id: media_data[:id]
+    }
+  end
+
+  def attach_location_from_history(message, message_data)
+    location = message_data[:location] || {}
+
+    message.content_attributes[:location_info] = {
+      latitude: location[:latitude],
+      longitude: location[:longitude],
+      name: location[:name],
+      address: location[:address],
+      url: location[:url]
+    }
+  end
+
+  def format_phone_number(phone_number)
+    phone_number.start_with?('+') ? phone_number : "+#{phone_number}"
+  end
+
+  def account
+    @account ||= inbox.account
+  end
+end

app/services/whatsapp/embedded_signup_service.rb

@@ -0,0 +1,282 @@
+class Whatsapp::EmbeddedSignupService
+  include Rails.application.routes.url_helpers
+
+  def initialize(account:, code:, business_id:, waba_id:, phone_number_id:, is_business_app_onboarding: false)
+    @account = account
+    @code = code
+    @business_id = business_id
+    @waba_id = waba_id
+    @phone_number_id = phone_number_id
+    @is_business_app_onboarding = is_business_app_onboarding
+  end
+
+  def perform
+    # Validate required parameters
+    unless @code.present? && @business_id.present? && @waba_id.present? && @phone_number_id.present?
+      raise ArgumentError, 'Code, business_id, waba_id, and phone_number_id are all required'
+    end
+
+    GlobalConfig.clear_cache
+    # Exchange code for user access token
+    access_token = exchange_code_for_token
+
+    # Use the provided business info directly (more efficient)
+    phone_info = fetch_phone_info_via_waba(@waba_id, @phone_number_id, access_token)
+
+    # Validate that the token has access to the provided WABA (security check)
+    validate_token_waba_access(access_token, @waba_id)
+
+    waba_info = { waba_id: @waba_id, business_name: phone_info[:business_name] }
+
+    channel = create_or_update_channel(waba_info, phone_info, access_token)
+
+    # Enable sync features for WhatsApp Business App coexistence
+    enable_sync_features(channel, access_token) if channel
+
+    channel
+  rescue StandardError => e
+    Rails.logger.error("[WHATSAPP] Signup failed: #{e.message}")
+    raise e
+  end
+
+  private
+
+  def whatsapp_api_version
+    @whatsapp_api_version ||= GlobalConfigService.load('WHATSAPP_API_VERSION', 'v22.0')
+  end
+
+  def exchange_code_for_token
+    response = Faraday.get(
+      "https://graph.facebook.com/#{whatsapp_api_version}/oauth/access_token",
+      {
+        client_id: GlobalConfigService.load('WHATSAPP_APP_ID', ''),
+        client_secret: GlobalConfigService.load('WHATSAPP_APP_SECRET', ''),
+        code: @code
+      }
+    )
+
+    raise "Token exchange failed: #{response.body}" unless response.success?
+
+    data = JSON.parse(response.body)
+    raise "No access token in response: #{data}" unless data['access_token']
+
+    data['access_token']
+  end
+
+  def fetch_phone_info_via_waba(waba_id, phone_number_id, access_token)
+    # Get all phone numbers for the WABA
+    response = Faraday.get(
+      "https://graph.facebook.com/#{whatsapp_api_version}/#{waba_id}/phone_numbers",
+      { access_token: access_token }
+    )
+
+    raise "WABA phone numbers fetch failed: #{response.body}" unless response.success?
+
+    data = JSON.parse(response.body)
+    phone_numbers = data['data']
+    phone_data = phone_numbers.find { |phone| phone['id'] == phone_number_id } || phone_numbers.first
+
+    raise "No phone numbers found for WABA #{waba_id}" if phone_data.nil?
+
+    display_phone_number = sanitize_phone_number(phone_data['display_phone_number'])
+    {
+      phone_number_id: phone_data['id'],
+      phone_number: "+#{display_phone_number}",
+      verified: phone_data['code_verification_status'] == 'VERIFIED',
+      business_name: phone_data['verified_name'] || phone_data['display_phone_number']
+    }
+  end
+
+  def create_or_update_channel(waba_info, phone_info, access_token)
+    existing_channel = find_existing_channel(phone_info[:phone_number])
+    channel_attributes = build_channel_attributes(waba_info, phone_info, access_token)
+
+    if existing_channel
+      Rails.logger.error("Channel already exists: #{existing_channel.inspect}")
+      raise "Channel already exists: #{existing_channel.phone_number}"
+    else
+      channel = create_new_channel(channel_attributes, phone_info)
+
+      # Skip phone number registration for WhatsApp Business App onboarding (coexistence)
+      # as the number is already registered in the WhatsApp Business App
+      register_phone_number(phone_info[:phone_number_id], access_token) unless @is_business_app_onboarding
+
+      override_waba_webhook(waba_info[:waba_id], channel, access_token)
+      channel
+    end
+  end
+
+  def register_phone_number(phone_number_id, access_token)
+    HTTParty.post(
+      "https://graph.facebook.com/#{whatsapp_api_version}/#{phone_number_id}/register",
+      {
+        headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
+        body: { messaging_product: 'whatsapp', pin: '212834' }.to_json
+      }
+    )
+  end
+
+  def find_existing_channel(phone_number)
+    Channel::Whatsapp.find_by(account: @account, phone_number: phone_number)
+  end
+
+  def build_channel_attributes(waba_info, phone_info, access_token)
+    {
+      phone_number: phone_info[:phone_number],
+      provider: 'whatsapp_cloud',
+      provider_config: {
+        api_key: access_token,
+        phone_number_id: phone_info[:phone_number_id],
+        business_account_id: waba_info[:waba_id],
+        source: 'embedded_signup'
+      }
+    }
+  end
+
+  def create_new_channel(attributes, phone_info)
+    channel = Channel::Whatsapp.create!(account: @account, **attributes)
+    create_inbox_for_channel(channel, phone_info)
+    channel.reload
+    channel
+  end
+
+  def create_inbox_for_channel(channel, phone_info)
+    Inbox.create!(
+      account: @account,
+      name: "#{phone_info[:business_name]} WhatsApp",
+      channel: channel
+    )
+  end
+
+  def sanitize_phone_number(phone_number)
+    return phone_number if phone_number.blank?
+
+    phone_number.gsub(/[\s\-\(\)\.\+]/, '').strip
+  end
+
+  def validate_token_waba_access(access_token, waba_id)
+    token_debug_data = fetch_token_debug_data(access_token)
+    waba_scope = extract_waba_scope(token_debug_data)
+    verify_waba_authorization(waba_scope, waba_id)
+  end
+
+  def fetch_token_debug_data(access_token)
+    response = Faraday.get(
+      "https://graph.facebook.com/#{whatsapp_api_version}/debug_token",
+      {
+        input_token: access_token,
+        access_token: build_app_access_token
+      }
+    )
+
+    raise "Token validation failed: #{response.body}" unless response.success?
+
+    JSON.parse(response.body)
+  end
+
+  def extract_waba_scope(token_data)
+    granular_scopes = token_data.dig('data', 'granular_scopes')
+    waba_scope = granular_scopes&.find { |scope| scope['scope'] == 'whatsapp_business_management' }
+
+    raise 'No WABA scope found in token' unless waba_scope
+
+    waba_scope
+  end
+
+  def verify_waba_authorization(waba_scope, waba_id)
+    authorized_waba_ids = waba_scope['target_ids'] || []
+
+    return if authorized_waba_ids.include?(waba_id)
+
+    raise "Token does not have access to WABA #{waba_id}. Authorized WABAs: #{authorized_waba_ids}"
+  end
+
+  def build_app_access_token
+    app_id = GlobalConfigService.load('WHATSAPP_APP_ID', '')
+    app_secret = GlobalConfigService.load('WHATSAPP_APP_SECRET', '')
+    "#{app_id}|#{app_secret}"
+  end
+
+  def override_waba_webhook(waba_id, channel, access_token)
+    callback_url = "#{ENV.fetch('FRONTEND_URL', nil)}/webhooks/whatsapp/#{channel.phone_number}"
+    verify_token = channel.provider_config['webhook_verify_token']
+
+    response = HTTParty.post(
+      "https://graph.facebook.com/#{whatsapp_api_version}/#{waba_id}/subscribed_apps",
+      {
+        headers: {
+          'Authorization' => "Bearer #{access_token}",
+          'Content-Type' => 'application/json'
+        },
+        body: {
+          override_callback_uri: callback_url,
+          verify_token: verify_token,
+          # Enable sync features for WhatsApp Business App coexistence
+          webhook_fields: %w[messages smb_app_state_sync smb_message_echoes]
+        }.to_json
+      }
+    )
+
+    return if response.success?
+
+    Rails.logger.error("[WHATSAPP] Webhook override failed: #{response.body}")
+    raise "Webhook override failed: #{response.body}"
+  end
+
+  # Enable sync features for WhatsApp Business App coexistence
+  def enable_sync_features(channel, access_token)
+    # Initialize contact sync for existing WhatsApp Business App contacts
+    sync_contacts(channel, access_token)
+
+    # Request conversation history sync (if business allows)
+    request_conversation_history_sync(channel, access_token)
+  end
+
+  def sync_contacts(channel, access_token)
+    Rails.logger.info("[WHATSAPP] Initiating contact sync for channel #{channel.id}")
+
+    # Make API call to sync contacts from WhatsApp Business App
+    response = HTTParty.post(
+      "https://graph.facebook.com/#{whatsapp_api_version}/#{channel.provider_config['phone_number_id']}/request_sync",
+      {
+        headers: {
+          'Authorization' => "Bearer #{access_token}",
+          'Content-Type' => 'application/json'
+        },
+        body: {
+          sync_type: 'contact'
+        }.to_json
+      }
+    )
+
+    if response.success?
+      Rails.logger.info("[WHATSAPP] Contact sync initiated successfully for channel #{channel.id}")
+    else
+      Rails.logger.warn("[WHATSAPP] Contact sync failed for channel #{channel.id}: #{response.body}")
+    end
+  end
+
+  def request_conversation_history_sync(channel, access_token)
+    Rails.logger.info("[WHATSAPP] Initiating conversation history sync for channel #{channel.id}")
+
+    # Make API call to sync conversation history from WhatsApp Business App
+    response = HTTParty.post(
+      "https://graph.facebook.com/#{whatsapp_api_version}/#{channel.provider_config['phone_number_id']}/request_sync",
+      {
+        headers: {
+          'Authorization' => "Bearer #{access_token}",
+          'Content-Type' => 'application/json'
+        },
+        body: {
+          sync_type: 'history'
+        }.to_json
+      }
+    )
+
+    if response.success?
+      Rails.logger.info("[WHATSAPP] Conversation history sync initiated successfully for channel #{channel.id}")
+    else
+      Rails.logger.warn("[WHATSAPP] Conversation history sync failed for channel #{channel.id}: #{response.body}")
+    end
+  end
+end

app/views/layouts/vueapp.html.erb

@@ -39,6 +39,9 @@
         googleOAuthClientId: '<%= ENV.fetch('GOOGLE_OAUTH_CLIENT_ID', nil) %>',
         googleOAuthCallbackUrl: '<%= ENV.fetch('GOOGLE_OAUTH_CALLBACK_URL', nil) %>',
         fbApiVersion: '<%= @global_config['FACEBOOK_API_VERSION'] %>',
+        whatsappAppId: '<%= @global_config['WHATSAPP_APP_ID'] %>',
+        whatsappConfigurationId: '<%= @global_config['WHATSAPP_CONFIGURATION_ID'] %>',
+        whatsappApiVersion: '<%= @global_config['WHATSAPP_API_VERSION'] %>',
         signupEnabled: '<%= @global_config['ENABLE_ACCOUNT_SIGNUP'] %>',
         isEnterprise: '<%= @global_config['IS_ENTERPRISE'] %>',
         <% if @global_config['IS_ENTERPRISE'] %>

app/views/whatsapp/embedded/embedded_signup.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/inbox', formats: [:json], resource: @inbox

config/installation_config.yml

@@ -126,6 +126,26 @@
   type: boolean
 # ------- End of Facebook Channel Related Config ------- #
 
+# ------- WhatsApp Channel Related Config ------- #
+- name: WHATSAPP_APP_ID
+  display_title: 'WhatsApp App ID'
+  description: 'The Facebook App ID for WhatsApp Business API integration'
+  locked: false
+- name: WHATSAPP_CONFIGURATION_ID
+  display_title: 'WhatsApp Configuration ID'
+  description: 'The Configuration ID for WhatsApp Embedded Signup flow (required for embedded signup)'
+  locked: false
+- name: WHATSAPP_APP_SECRET
+  display_title: 'WhatsApp App Secret'
+  description: 'The App Secret for WhatsApp Embedded Signup flow (required for embedded signup)'
+  locked: false
+- name: WHATSAPP_API_VERSION
+  display_title: 'WhatsApp API Version'
+  description: 'Configure this if you want to use a different WhatsApp API version. Make sure its prefixed with `v`'
+  value: 'v22.0'
+  locked: false
+# ------- End of WhatsApp Channel Related Config ------- #
+
 # MARK: Microsoft Email Channel Config
 - name: AZURE_APP_ID
   display_title: 'Azure App ID'

config/routes.rb

@@ -473,6 +473,12 @@ Rails.application.routes.draw do
   get 'webhooks/instagram', to: 'webhooks/instagram#verify'
   post 'webhooks/instagram', to: 'webhooks/instagram#events'
 
+  namespace :whatsapp do
+    get 'signup', to: 'embedded#new'
+    get 'signup/callback', to: 'embedded#callback'
+    post 'embedded_signup', to: 'embedded#embedded_signup'
+  end
+
   namespace :twitter do
     resource :callback, only: [:show]
   end

enterprise/app/helpers/super_admin/features.yml

@@ -97,6 +97,12 @@ slack:
   enabled: true
   icon: 'icon-slack'
   config_key: 'slack'
+whatsapp_embedded:
+  name: 'WhatsApp Embedded'
+  description: 'Configuration for setting up WhatsApp Embedded Integration'
+  enabled: true
+  icon: 'icon-whatsapp-line'
+  config_key: 'whatsapp_embedded'
 shopify:
   name: 'Shopify'
   description: 'Configuration for setting up Shopify Integration'

spec/controllers/whatsapp/embedded_controller_spec.rb

@@ -0,0 +1,100 @@
+require 'rails_helper'
+
+RSpec.describe 'WhatsApp Embedded API', type: :request do
+  let(:account) { create(:account) }
+  let(:admin) { create(:user, account: account, role: :administrator) }
+
+  describe 'GET /whatsapp/signup' do
+    before do
+      allow(GlobalConfigService).to receive(:load).with('WHATSAPP_APP_ID', '').and_return('test_app_id')
+      allow(GlobalConfigService).to receive(:load).with('WHATSAPP_CONFIGURATION_ID', '').and_return('test_config_id')
+      allow(GlobalConfigService).to receive(:load).with('WHATSAPP_APP_SECRET', '').and_return('test_app_secret')
+      allow(GlobalConfigService).to receive(:load).with('WHATSAPP_API_VERSION', '').and_return('v22.0')
+    end
+
+    context 'when user is authenticated' do
+      it 'returns configuration for embedded signup' do
+        get '/whatsapp/signup',
+            headers: admin.create_new_auth_token,
+            params: { account_id: account.id }
+
+        expect(response).to have_http_status(:success)
+        json_response = response.parsed_body
+        expect(json_response).to include(
+          'status' => 'ready',
+          'app_id' => 'test_app_id',
+          'config_id' => 'test_config_id',
+          'app_secret' => 'test_app_secret'
+        )
+      end
+    end
+
+    context 'when user is not authenticated' do
+      it 'returns unauthorized' do
+        get '/whatsapp/signup', params: { account_id: account.id }
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+  end
+
+  describe 'POST /whatsapp/embedded_signup' do
+    let(:params) do
+      {
+        account_id: account.id,
+        code: 'auth_code_123',
+        business_id: '123456789',
+        waba_id: '987654321',
+        phone_number_id: '555444333'
+      }
+    end
+
+    context 'when user is authenticated' do
+      context 'with missing authorization code' do
+        it 'returns bad request error' do
+          params_without_code = params.except(:code)
+
+          post '/whatsapp/embedded_signup',
+               headers: admin.create_new_auth_token,
+               params: params_without_code
+
+          expect(response).to have_http_status(:bad_request)
+          json_response = response.parsed_body
+          expect(json_response['error']).to eq('Missing authorization code')
+        end
+      end
+
+      context 'with missing business parameters' do
+        it 'returns bad request when business_id is missing' do
+          params_without_business = params.except(:business_id)
+
+          post '/whatsapp/embedded_signup',
+               headers: admin.create_new_auth_token,
+               params: params_without_business
+
+          expect(response).to have_http_status(:bad_request)
+          json_response = response.parsed_body
+          expect(json_response['error']).to include('Missing required parameters')
+        end
+
+        it 'returns bad request when waba_id is missing' do
+          params_without_waba = params.except(:waba_id)
+
+          post '/whatsapp/embedded_signup',
+               headers: admin.create_new_auth_token,
+               params: params_without_waba
+
+          expect(response).to have_http_status(:bad_request)
+          json_response = response.parsed_body
+          expect(json_response['error']).to include('Missing required parameters')
+        end
+      end
+    end
+
+    context 'when user is not authenticated' do
+      it 'returns unauthorized' do
+        post '/whatsapp/embedded_signup', params: params
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+  end
+end

spec/services/whatsapp/embedded_signup_service_spec.rb

@@ -0,0 +1,700 @@
+require 'rails_helper'
+
+describe Whatsapp::EmbeddedSignupService do
+  let(:account) { create(:account) }
+  let(:code) { 'test_authorization_code' }
+  let(:business_id) { 'test_business_id' }
+  let(:waba_id) { 'test_waba_id' }
+  let(:phone_number_id) { 'test_phone_number_id' }
+  let(:access_token) { 'test_access_token' }
+  let(:app_id) { 'test_app_id' }
+  let(:app_secret) { 'test_app_secret' }
+  let(:api_version) { 'v22.0' }
+
+  let(:service) do
+    described_class.new(
+      account: account,
+      code: code,
+      business_id: business_id,
+      waba_id: waba_id,
+      phone_number_id: phone_number_id
+    )
+  end
+
+  before do
+    # Mock global configuration
+    allow(GlobalConfigService).to receive(:load).with('WHATSAPP_APP_ID', '').and_return(app_id)
+    allow(GlobalConfigService).to receive(:load).with('WHATSAPP_APP_SECRET', '').and_return(app_secret)
+    allow(GlobalConfigService).to receive(:load).with('WHATSAPP_API_VERSION', 'v22.0').and_return(api_version)
+    allow(GlobalConfig).to receive(:clear_cache)
+
+    # Mock environment variables - allow any calls to ENV.fetch
+    allow(ENV).to receive(:fetch).and_call_original
+    allow(ENV).to receive(:fetch).with('FRONTEND_URL', nil).and_return('https://app.chatwoot.com')
+    allow(ENV).to receive(:fetch).with('DISABLE_ENTERPRISE', false).and_return(true)
+
+    # Mock ChatwootApp enterprise checks
+    allow(ChatwootApp).to receive(:enterprise?).and_return(false)
+
+    # NOTE: Specific HTTP request stubs are defined in individual test contexts
+  end
+
+  describe '#perform' do
+    context 'when all parameters are valid' do
+      before do
+        # Stub the token exchange
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: hash_including(
+            'client_id' => app_id,
+            'client_secret' => app_secret,
+            'code' => code
+          ))
+          .to_return(
+            status: 200,
+            body: { access_token: access_token }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub the phone numbers fetch
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: {
+              data: [
+                {
+                  id: phone_number_id,
+                  display_phone_number: '1234567890',
+                  verified_name: 'Test Business',
+                  code_verification_status: 'VERIFIED'
+                }
+              ]
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub the token validation
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+          .with(query: hash_including(
+            'input_token' => access_token,
+            'access_token' => "#{app_id}|#{app_secret}"
+          ))
+          .to_return(
+            status: 200,
+            body: {
+              data: {
+                granular_scopes: [
+                  {
+                    scope: 'whatsapp_business_management',
+                    target_ids: [waba_id]
+                  }
+                ]
+              }
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub the provider validation request (WhatsApp Cloud)
+        stub_request(:get, "https://graph.facebook.com/v14.0/#{waba_id}/message_templates")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: { data: [] }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub the phone number registration
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{phone_number_id}/register")
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub the webhook subscription
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'successfully creates a new WhatsApp channel' do
+        expect { service.perform }.not_to raise_error
+
+        channel = Channel::Whatsapp.find_by(account: account, phone_number: '+1234567890')
+        expect(channel).not_to be_nil
+        expect(channel.provider).to eq('whatsapp_cloud')
+        expect(channel.provider_config['api_key']).to eq(access_token)
+        expect(channel.provider_config['phone_number_id']).to eq(phone_number_id)
+        expect(channel.provider_config['business_account_id']).to eq(waba_id)
+        expect(channel.provider_config['source']).to eq('embedded_signup')
+      end
+
+      it 'creates an inbox for the channel' do
+        service.perform
+
+        channel = Channel::Whatsapp.find_by(account: account, phone_number: '+1234567890')
+        inbox = Inbox.find_by(account: account, channel: channel)
+        expect(inbox).not_to be_nil
+        expect(inbox.name).to eq('Test Business WhatsApp')
+      end
+
+      it 'registers the phone number' do
+        service.perform
+
+        expect(WebMock).to have_requested(:post, "https://graph.facebook.com/#{api_version}/#{phone_number_id}/register")
+          .with(
+            body: {
+              messaging_product: 'whatsapp',
+              pin: '212834'
+            }.to_json
+          )
+      end
+
+      it 'sets up webhook subscription' do
+        service.perform
+
+        channel = Channel::Whatsapp.find_by(account: account, phone_number: '+1234567890')
+        callback_url = "https://app.chatwoot.com/webhooks/whatsapp/#{channel.phone_number}"
+
+        expect(WebMock).to have_requested(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            body: hash_including(
+              override_callback_uri: callback_url,
+              verify_token: channel.provider_config['webhook_verify_token']
+            )
+          )
+      end
+    end
+
+    context 'when required parameters are missing' do
+      it 'raises an error when code is missing' do
+        service = described_class.new(
+          account: account,
+          code: '',
+          business_id: business_id,
+          waba_id: waba_id,
+          phone_number_id: phone_number_id
+        )
+
+        expect { service.perform }.to raise_error(ArgumentError, /Code, business_id, waba_id, and phone_number_id are all required/)
+      end
+
+      it 'raises an error when business_id is missing' do
+        service = described_class.new(
+          account: account,
+          code: code,
+          business_id: '',
+          waba_id: waba_id,
+          phone_number_id: phone_number_id
+        )
+
+        expect { service.perform }.to raise_error(ArgumentError, /Code, business_id, waba_id, and phone_number_id are all required/)
+      end
+
+      it 'raises an error when waba_id is missing' do
+        service = described_class.new(
+          account: account,
+          code: code,
+          business_id: business_id,
+          waba_id: '',
+          phone_number_id: phone_number_id
+        )
+
+        expect { service.perform }.to raise_error(ArgumentError, /Code, business_id, waba_id, and phone_number_id are all required/)
+      end
+
+      it 'raises an error when phone_number_id is missing' do
+        service = described_class.new(
+          account: account,
+          code: code,
+          business_id: business_id,
+          waba_id: waba_id,
+          phone_number_id: ''
+        )
+
+        expect { service.perform }.to raise_error(ArgumentError, /Code, business_id, waba_id, and phone_number_id are all required/)
+      end
+    end
+
+    context 'when channel already exists' do
+      before do
+        # Stub all the required requests for successful flow
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: hash_including(
+            'client_id' => app_id,
+            'client_secret' => app_secret,
+            'code' => code
+          ))
+          .to_return(
+            status: 200,
+            body: { access_token: access_token }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: {
+              data: [
+                {
+                  id: phone_number_id,
+                  display_phone_number: '1234567890',
+                  verified_name: 'Test Business',
+                  code_verification_status: 'VERIFIED'
+                }
+              ]
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+          .with(query: hash_including(
+            'input_token' => access_token,
+            'access_token' => "#{app_id}|#{app_secret}"
+          ))
+          .to_return(
+            status: 200,
+            body: {
+              data: {
+                granular_scopes: [
+                  {
+                    scope: 'whatsapp_business_management',
+                    target_ids: [waba_id]
+                  }
+                ]
+              }
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub 360Dialog provider validation (for existing channel creation)
+        stub_request(:post, 'https://waba.360dialog.io/v1/configs/webhook')
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, 'https://waba.360dialog.io/v1/configs/templates')
+          .to_return(
+            status: 200,
+            body: { templates: [] }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Create existing channel
+        create(:channel_whatsapp, account: account, phone_number: '+1234567890')
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/Channel already exists/)
+      end
+    end
+
+    context 'when token exchange fails' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: hash_including(
+            'client_id' => app_id,
+            'client_secret' => app_secret,
+            'code' => code
+          ))
+          .to_return(status: 400, body: { error: 'Invalid code' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/Token exchange failed/)
+      end
+    end
+
+    context 'when token has no access to WABA' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: hash_including(
+            'client_id' => app_id,
+            'client_secret' => app_secret,
+            'code' => code
+          ))
+          .to_return(
+            status: 200,
+            body: { access_token: access_token }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: {
+              data: [
+                {
+                  id: phone_number_id,
+                  display_phone_number: '1234567890',
+                  verified_name: 'Test Business',
+                  code_verification_status: 'VERIFIED'
+                }
+              ]
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+          .with(query: hash_including(
+            'input_token' => access_token,
+            'access_token' => "#{app_id}|#{app_secret}"
+          ))
+          .to_return(
+            status: 200,
+            body: {
+              data: {
+                granular_scopes: [
+                  {
+                    scope: 'whatsapp_business_management',
+                    target_ids: ['different_waba_id']
+                  }
+                ]
+              }
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/Token does not have access to WABA/)
+      end
+    end
+
+    context 'when phone numbers fetch fails' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: hash_including(
+            'client_id' => app_id,
+            'client_secret' => app_secret,
+            'code' => code
+          ))
+          .to_return(
+            status: 200,
+            body: { access_token: access_token }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(status: 400, body: { error: 'Phone numbers fetch failed' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/WABA phone numbers fetch failed/)
+      end
+    end
+
+    context 'when webhook override fails' do
+      before do
+        # Stub all the successful requests
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: hash_including(
+            'client_id' => app_id,
+            'client_secret' => app_secret,
+            'code' => code
+          ))
+          .to_return(
+            status: 200,
+            body: { access_token: access_token }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: {
+              data: [
+                {
+                  id: phone_number_id,
+                  display_phone_number: '1234567890',
+                  verified_name: 'Test Business',
+                  code_verification_status: 'VERIFIED'
+                }
+              ]
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+          .with(query: hash_including(
+            'input_token' => access_token,
+            'access_token' => "#{app_id}|#{app_secret}"
+          ))
+          .to_return(
+            status: 200,
+            body: {
+              data: {
+                granular_scopes: [
+                  {
+                    scope: 'whatsapp_business_management',
+                    target_ids: [waba_id]
+                  }
+                ]
+              }
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:get, "https://graph.facebook.com/v14.0/#{waba_id}/message_templates")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: { data: [] }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{phone_number_id}/register")
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Stub the failing webhook request
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .to_return(status: 400, body: { error: 'Webhook failed' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/Webhook override failed/)
+      end
+    end
+  end
+
+  describe 'private methods' do
+    describe '#exchange_code_for_token' do
+      context 'when token exchange is successful' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+            .with(query: hash_including(
+              'client_id' => app_id,
+              'client_secret' => app_secret,
+              'code' => code
+            ))
+            .to_return(
+              status: 200,
+              body: { access_token: access_token }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'returns the access token' do
+          result = service.send(:exchange_code_for_token)
+          expect(result).to eq(access_token)
+        end
+      end
+
+      context 'when response has no access token' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+            .with(query: hash_including(
+              'client_id' => app_id,
+              'client_secret' => app_secret,
+              'code' => code
+            ))
+            .to_return(
+              status: 200,
+              body: { some_other_field: 'value' }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'raises an error' do
+          expect { service.send(:exchange_code_for_token) }.to raise_error(/No access token in response/)
+        end
+      end
+    end
+
+    describe '#fetch_phone_info_via_waba' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: hash_including('access_token' => access_token))
+          .to_return(
+            status: 200,
+            body: {
+              data: [
+                {
+                  id: phone_number_id,
+                  display_phone_number: '1234567890',
+                  verified_name: 'Test Business',
+                  code_verification_status: 'VERIFIED'
+                }
+              ]
+            }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns formatted phone info' do
+        result = service.send(:fetch_phone_info_via_waba, waba_id, phone_number_id, access_token)
+        expect(result).to eq({
+                               phone_number_id: phone_number_id,
+                               phone_number: '+1234567890',
+                               verified: true,
+                               business_name: 'Test Business'
+                             })
+      end
+
+      context 'when specific phone number is not found' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+            .with(query: hash_including('access_token' => access_token))
+            .to_return(
+              status: 200,
+              body: {
+                data: [
+                  {
+                    id: 'different_phone_id',
+                    display_phone_number: '9876543210',
+                    verified_name: 'Different Business',
+                    code_verification_status: 'VERIFIED'
+                  }
+                ]
+              }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'uses the first available phone number' do
+          result = service.send(:fetch_phone_info_via_waba, waba_id, phone_number_id, access_token)
+          expect(result[:phone_number_id]).to eq('different_phone_id')
+          expect(result[:phone_number]).to eq('+9876543210')
+        end
+      end
+
+      context 'when no phone numbers are available' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+            .with(query: hash_including('access_token' => access_token))
+            .to_return(
+              status: 200,
+              body: { data: [] }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'raises an error' do
+          expect do
+            service.send(:fetch_phone_info_via_waba, waba_id, phone_number_id, access_token)
+          end.to raise_error(/No phone numbers found for WABA/)
+        end
+      end
+    end
+
+    describe '#validate_token_waba_access' do
+      context 'when token has access to WABA' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+            .with(query: hash_including(
+              'input_token' => access_token,
+              'access_token' => "#{app_id}|#{app_secret}"
+            ))
+            .to_return(
+              status: 200,
+              body: {
+                data: {
+                  granular_scopes: [
+                    {
+                      scope: 'whatsapp_business_management',
+                      target_ids: [waba_id]
+                    }
+                  ]
+                }
+              }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'validates successfully when token has access' do
+          expect { service.send(:validate_token_waba_access, access_token, waba_id) }.not_to raise_error
+        end
+      end
+
+      context 'when token validation fails' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+            .with(query: hash_including(
+              'input_token' => access_token,
+              'access_token' => "#{app_id}|#{app_secret}"
+            ))
+            .to_return(status: 400, body: { error: 'Invalid token' }.to_json)
+        end
+
+        it 'raises an error' do
+          expect do
+            service.send(:validate_token_waba_access, access_token, waba_id)
+          end.to raise_error(/Token validation failed/)
+        end
+      end
+
+      context 'when token does not have access to WABA' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+            .with(query: hash_including(
+              'input_token' => access_token,
+              'access_token' => "#{app_id}|#{app_secret}"
+            ))
+            .to_return(
+              status: 200,
+              body: {
+                data: {
+                  granular_scopes: [
+                    {
+                      scope: 'whatsapp_business_management',
+                      target_ids: ['different_waba_id']
+                    }
+                  ]
+                }
+              }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'raises an error when WABA ID is not in target_ids' do
+          expect do
+            service.send(:validate_token_waba_access, access_token, waba_id)
+          end.to raise_error(/Token does not have access to WABA/)
+        end
+      end
+
+      context 'when no WABA scope is found' do
+        before do
+          stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+            .with(query: hash_including(
+              'input_token' => access_token,
+              'access_token' => "#{app_id}|#{app_secret}"
+            ))
+            .to_return(
+              status: 200,
+              body: {
+                data: {
+                  granular_scopes: [
+                    {
+                      scope: 'some_other_scope',
+                      target_ids: ['some_id']
+                    }
+                  ]
+                }
+              }.to_json,
+              headers: { 'Content-Type' => 'application/json' }
+            )
+        end
+
+        it 'raises an error' do
+          expect do
+            service.send(:validate_token_waba_access, access_token, waba_id)
+          end.to raise_error(/No WABA scope found in token/)
+        end
+      end
+    end
+  end
+end