Restructure omni services and add Chatwoot research snapshot

research/chatwoot/spec/services/whatsapp/channel_creation_service_spec.rb

@@ -0,0 +1,129 @@
+require 'rails_helper'
+
+describe Whatsapp::ChannelCreationService do
+  let(:account) { create(:account) }
+  let(:waba_info) { { waba_id: 'test_waba_id', business_name: 'Test Business' } }
+  let(:phone_info) do
+    {
+      phone_number_id: 'test_phone_id',
+      phone_number: '+1234567890',
+      verified: true,
+      business_name: 'Test Business'
+    }
+  end
+  let(:access_token) { 'test_access_token' }
+  let(:service) { described_class.new(account, waba_info, phone_info, access_token) }
+
+  describe '#perform' do
+    before do
+      # Stub the webhook teardown service to prevent HTTP calls during cleanup
+      teardown_service = instance_double(Whatsapp::WebhookTeardownService)
+      allow(Whatsapp::WebhookTeardownService).to receive(:new).and_return(teardown_service)
+      allow(teardown_service).to receive(:perform)
+
+      # Clean up any existing channels to avoid phone number conflicts
+      Channel::Whatsapp.destroy_all
+
+      # Stub the webhook setup service to prevent HTTP calls during tests
+      webhook_service = instance_double(Whatsapp::WebhookSetupService)
+      allow(Whatsapp::WebhookSetupService).to receive(:new).and_return(webhook_service)
+      allow(webhook_service).to receive(:perform)
+
+      # Stub the provider validation and sync_templates
+      allow(Channel::Whatsapp).to receive(:new).and_wrap_original do |method, *args|
+        channel = method.call(*args)
+        allow(channel).to receive(:validate_provider_config)
+        allow(channel).to receive(:sync_templates)
+        channel
+      end
+    end
+
+    context 'when channel does not exist' do
+      it 'creates a new channel' do
+        expect { service.perform }.to change(Channel::Whatsapp, :count).by(1)
+      end
+
+      it 'creates channel with correct attributes' do
+        channel = service.perform
+        expect(channel.phone_number).to eq('+1234567890')
+        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('test_phone_id')
+        expect(channel.provider_config['business_account_id']).to eq('test_waba_id')
+        expect(channel.provider_config['source']).to eq('embedded_signup')
+      end
+
+      it 'creates an inbox for the channel' do
+        channel = service.perform
+        inbox = channel.inbox
+        expect(inbox).not_to be_nil
+        expect(inbox.name).to eq('Test Business WhatsApp')
+        expect(inbox.account).to eq(account)
+      end
+    end
+
+    context 'when channel already exists for the phone number' do
+      let(:different_account) { create(:account) }
+
+      before do
+        create(:channel_whatsapp, account: different_account, phone_number: '+1234567890',
+                                  provider: 'whatsapp_cloud', sync_templates: false, validate_provider_config: false)
+      end
+
+      it 'raises an error even if the channel belongs to a different account' do
+        expect { service.perform }.to raise_error(
+          RuntimeError,
+          I18n.t('errors.whatsapp.phone_number_already_exists', phone_number: '+1234567890')
+        )
+      end
+    end
+
+    context 'when required parameters are missing' do
+      it 'raises error when account is nil' do
+        service = described_class.new(nil, waba_info, phone_info, access_token)
+        expect { service.perform }.to raise_error(ArgumentError, 'Account is required')
+      end
+
+      it 'raises error when waba_info is nil' do
+        service = described_class.new(account, nil, phone_info, access_token)
+        expect { service.perform }.to raise_error(ArgumentError, 'WABA info is required')
+      end
+
+      it 'raises error when phone_info is nil' do
+        service = described_class.new(account, waba_info, nil, access_token)
+        expect { service.perform }.to raise_error(ArgumentError, 'Phone info is required')
+      end
+
+      it 'raises error when access_token is blank' do
+        service = described_class.new(account, waba_info, phone_info, '')
+        expect { service.perform }.to raise_error(ArgumentError, 'Access token is required')
+      end
+    end
+
+    context 'when business_name is in different places' do
+      context 'when business_name is only in phone_info' do
+        let(:waba_info) { { waba_id: 'test_waba_id' } }
+
+        it 'uses business_name from phone_info' do
+          channel = service.perform
+          expect(channel.inbox.name).to eq('Test Business WhatsApp')
+        end
+      end
+
+      context 'when business_name is only in waba_info' do
+        let(:phone_info) do
+          {
+            phone_number_id: 'test_phone_id',
+            phone_number: '+1234567890',
+            verified: true
+          }
+        end
+
+        it 'uses business_name from waba_info' do
+          channel = service.perform
+          expect(channel.inbox.name).to eq('Test Business WhatsApp')
+        end
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/csat_template_service_spec.rb

@@ -0,0 +1,376 @@
+require 'rails_helper'
+
+RSpec.describe Whatsapp::CsatTemplateService do
+  let(:account) { create(:account) }
+  let(:whatsapp_channel) do
+    create(:channel_whatsapp, account: account, provider: 'whatsapp_cloud', sync_templates: false, validate_provider_config: false)
+  end
+  let(:inbox) { create(:inbox, channel: whatsapp_channel, account: account) }
+  let(:service) { described_class.new(whatsapp_channel) }
+
+  let(:expected_template_name) { "customer_satisfaction_survey_#{whatsapp_channel.inbox.id}" }
+  let(:template_config) do
+    {
+      message: 'How would you rate your experience?',
+      button_text: 'Rate Us',
+      language: 'en',
+      base_url: 'https://example.com',
+      template_name: expected_template_name
+    }
+  end
+
+  before do
+    allow(ENV).to receive(:fetch).and_call_original
+    allow(ENV).to receive(:fetch).with('WHATSAPP_CLOUD_BASE_URL', anything).and_return('https://graph.facebook.com')
+  end
+
+  describe '#generate_template_name' do
+    context 'when no existing template' do
+      it 'returns base name as-is' do
+        whatsapp_channel.inbox.update!(csat_config: {})
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq('new_template_name')
+      end
+
+      it 'returns base name when template key is missing' do
+        whatsapp_channel.inbox.update!(csat_config: { 'other_config' => 'value' })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq('new_template_name')
+      end
+    end
+
+    context 'when existing template has no versioned name' do
+      it 'starts versioning from 1' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => expected_template_name }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq("#{expected_template_name}_1")
+      end
+
+      it 'starts versioning from 1 for custom name' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => 'custom_survey' }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq("#{expected_template_name}_1")
+      end
+    end
+
+    context 'when existing template has versioned name' do
+      it 'increments version number' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => "#{expected_template_name}_1" }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq("#{expected_template_name}_2")
+      end
+
+      it 'increments higher version numbers' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => "#{expected_template_name}_5" }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq("#{expected_template_name}_6")
+      end
+
+      it 'handles double digit version numbers' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => "#{expected_template_name}_12" }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq("#{expected_template_name}_13")
+      end
+    end
+
+    context 'when existing template has non-matching versioned name' do
+      it 'starts versioning from 1' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => 'different_survey_3' }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq("#{expected_template_name}_1")
+      end
+    end
+
+    context 'when template name is blank' do
+      it 'returns base name' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => '' }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq('new_template_name')
+      end
+
+      it 'returns base name when template name is nil' do
+        whatsapp_channel.inbox.update!(csat_config: {
+                                         'template' => { 'name' => nil }
+                                       })
+        result = service.send(:generate_template_name, 'new_template_name')
+        expect(result).to eq('new_template_name')
+      end
+    end
+  end
+
+  describe '#build_template_request_body' do
+    it 'builds correct request structure' do
+      result = service.send(:build_template_request_body, template_config)
+
+      expect(result).to eq({
+                             name: expected_template_name,
+                             language: 'en',
+                             category: 'MARKETING',
+                             components: [
+                               {
+                                 type: 'BODY',
+                                 text: 'How would you rate your experience?'
+                               },
+                               {
+                                 type: 'BUTTONS',
+                                 buttons: [
+                                   {
+                                     type: 'URL',
+                                     text: 'Rate Us',
+                                     url: 'https://example.com/survey/responses/{{1}}',
+                                     example: ['12345']
+                                   }
+                                 ]
+                               }
+                             ]
+                           })
+    end
+
+    it 'uses default language when not provided' do
+      config_without_language = template_config.except(:language)
+      result = service.send(:build_template_request_body, config_without_language)
+      expect(result[:language]).to eq('en')
+    end
+
+    it 'uses default button text when not provided' do
+      config_without_button = template_config.except(:button_text)
+      result = service.send(:build_template_request_body, config_without_button)
+      expect(result[:components][1][:buttons][0][:text]).to eq('Please rate us')
+    end
+  end
+
+  describe '#create_template' do
+    let(:mock_response) do
+      # rubocop:disable RSpec/VerifiedDoubles
+      double('response', :success? => true, :body => '{}', '[]' => { 'id' => '123', 'name' => 'template_name' })
+      # rubocop:enable RSpec/VerifiedDoubles
+    end
+
+    before do
+      allow(HTTParty).to receive(:post).and_return(mock_response)
+      inbox.update!(csat_config: {})
+    end
+
+    it 'creates template with generated name' do
+      expected_body = {
+        name: expected_template_name,
+        language: 'en',
+        category: 'MARKETING',
+        components: [
+          {
+            type: 'BODY',
+            text: 'How would you rate your experience?'
+          },
+          {
+            type: 'BUTTONS',
+            buttons: [
+              {
+                type: 'URL',
+                text: 'Rate Us',
+                url: 'https://example.com/survey/responses/{{1}}',
+                example: ['12345']
+              }
+            ]
+          }
+        ]
+      }
+
+      expect(HTTParty).to receive(:post).with(
+        "https://graph.facebook.com/v14.0/#{whatsapp_channel.provider_config['business_account_id']}/message_templates",
+        headers: {
+          'Authorization' => "Bearer #{whatsapp_channel.provider_config['api_key']}",
+          'Content-Type' => 'application/json'
+        },
+        body: expected_body.to_json
+      )
+
+      service.create_template(template_config)
+    end
+
+    it 'returns success response on successful creation' do
+      allow(mock_response).to receive(:[]).with('id').and_return('template_123')
+      allow(mock_response).to receive(:[]).with('name').and_return(expected_template_name)
+
+      result = service.create_template(template_config)
+
+      expect(result).to eq({
+                             success: true,
+                             template_id: 'template_123',
+                             template_name: expected_template_name,
+                             language: 'en',
+                             status: 'PENDING'
+                           })
+    end
+
+    context 'when API call fails' do
+      let(:error_response) do
+        # rubocop:disable RSpec/VerifiedDoubles
+        double('response', success?: false, code: 400, body: '{"error": "Invalid template"}')
+        # rubocop:enable RSpec/VerifiedDoubles
+      end
+
+      before do
+        allow(HTTParty).to receive(:post).and_return(error_response)
+        allow(Rails.logger).to receive(:error)
+      end
+
+      it 'returns error response' do
+        result = service.create_template(template_config)
+
+        expect(result).to eq({
+                               success: false,
+                               error: 'Template creation failed',
+                               response_body: '{"error": "Invalid template"}'
+                             })
+      end
+
+      it 'logs the error' do
+        expect(Rails.logger).to receive(:error).with('WhatsApp template creation failed: 400 - {"error": "Invalid template"}')
+        service.create_template(template_config)
+      end
+    end
+  end
+
+  describe '#delete_template' do
+    it 'makes DELETE request to correct endpoint' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: true, body: '{}')
+      # rubocop:enable RSpec/VerifiedDoubles
+
+      expect(HTTParty).to receive(:delete).with(
+        "https://graph.facebook.com/v14.0/#{whatsapp_channel.provider_config['business_account_id']}/message_templates?name=test_template",
+        headers: {
+          'Authorization' => "Bearer #{whatsapp_channel.provider_config['api_key']}",
+          'Content-Type' => 'application/json'
+        }
+      ).and_return(mock_response)
+
+      result = service.delete_template('test_template')
+      expect(result).to eq({ success: true, response_body: '{}' })
+    end
+
+    it 'uses default template name when none provided' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: true, body: '{}')
+      # rubocop:enable RSpec/VerifiedDoubles
+
+      expect(HTTParty).to receive(:delete).with(
+        "https://graph.facebook.com/v14.0/#{whatsapp_channel.provider_config['business_account_id']}/message_templates?name=#{expected_template_name}",
+        anything
+      ).and_return(mock_response)
+
+      service.delete_template
+    end
+
+    it 'returns failure response when API call fails' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: false, body: '{"error": "Template not found"}')
+      # rubocop:enable RSpec/VerifiedDoubles
+      allow(HTTParty).to receive(:delete).and_return(mock_response)
+
+      result = service.delete_template('test_template')
+      expect(result).to eq({ success: false, response_body: '{"error": "Template not found"}' })
+    end
+  end
+
+  describe '#get_template_status' do
+    it 'makes GET request to correct endpoint' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: true, body: '{}')
+      # rubocop:enable RSpec/VerifiedDoubles
+      allow(mock_response).to receive(:[]).with('data').and_return([{
+                                                                     'id' => '123',
+                                                                     'name' => 'test_template',
+                                                                     'status' => 'APPROVED',
+                                                                     'language' => 'en'
+                                                                   }])
+
+      expect(HTTParty).to receive(:get).with(
+        "https://graph.facebook.com/v14.0/#{whatsapp_channel.provider_config['business_account_id']}/message_templates?name=test_template",
+        headers: {
+          'Authorization' => "Bearer #{whatsapp_channel.provider_config['api_key']}",
+          'Content-Type' => 'application/json'
+        }
+      ).and_return(mock_response)
+
+      service.get_template_status('test_template')
+    end
+
+    it 'returns success response when template exists' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: true, body: '{}')
+      # rubocop:enable RSpec/VerifiedDoubles
+      allow(mock_response).to receive(:[]).with('data').and_return([{
+                                                                     'id' => '123',
+                                                                     'name' => 'test_template',
+                                                                     'status' => 'APPROVED',
+                                                                     'language' => 'en'
+                                                                   }])
+      allow(HTTParty).to receive(:get).and_return(mock_response)
+
+      result = service.get_template_status('test_template')
+
+      expect(result).to eq({
+                             success: true,
+                             template: {
+                               id: '123',
+                               name: 'test_template',
+                               status: 'APPROVED',
+                               language: 'en'
+                             }
+                           })
+    end
+
+    it 'returns failure response when template not found' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: true, body: '{}')
+      # rubocop:enable RSpec/VerifiedDoubles
+      allow(mock_response).to receive(:[]).with('data').and_return([])
+      allow(HTTParty).to receive(:get).and_return(mock_response)
+
+      result = service.get_template_status('test_template')
+      expect(result).to eq({ success: false, error: 'Template not found' })
+    end
+
+    it 'returns failure response when API call fails' do
+      # rubocop:disable RSpec/VerifiedDoubles
+      mock_response = double('response', success?: false, body: '{}')
+      # rubocop:enable RSpec/VerifiedDoubles
+      allow(HTTParty).to receive(:get).and_return(mock_response)
+
+      result = service.get_template_status('test_template')
+      expect(result).to eq({ success: false, error: 'Template not found' })
+    end
+
+    context 'when API raises an exception' do
+      before do
+        allow(HTTParty).to receive(:get).and_raise(StandardError, 'Network error')
+        allow(Rails.logger).to receive(:error)
+      end
+
+      it 'handles exceptions gracefully' do
+        result = service.get_template_status('test_template')
+        expect(result).to eq({ success: false, error: 'Network error' })
+      end
+
+      it 'logs the error' do
+        expect(Rails.logger).to receive(:error).with('Error fetching template status: Network error')
+        service.get_template_status('test_template')
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/embedded_signup_service_spec.rb

@@ -0,0 +1,243 @@
+require 'rails_helper'
+
+describe Whatsapp::EmbeddedSignupService do
+  let(:account) { create(:account) }
+  let(:params) do
+    {
+      code: 'test_authorization_code',
+      business_id: 'test_business_id',
+      waba_id: 'test_waba_id',
+      phone_number_id: 'test_phone_number_id'
+    }
+  end
+  let(:service) { described_class.new(account: account, params: params) }
+  let(:access_token) { 'test_access_token' }
+  let(:phone_info) do
+    {
+      phone_number_id: params[:phone_number_id],
+      phone_number: '+1234567890',
+      verified: true,
+      business_name: 'Test Business'
+    }
+  end
+  let(:channel) { instance_double(Channel::Whatsapp) }
+
+  describe '#perform' do
+    before do
+      allow(GlobalConfig).to receive(:clear_cache)
+
+      # Mock service dependencies
+      token_exchange = instance_double(Whatsapp::TokenExchangeService)
+      allow(Whatsapp::TokenExchangeService).to receive(:new).with(params[:code]).and_return(token_exchange)
+      allow(token_exchange).to receive(:perform).and_return(access_token)
+
+      phone_service = instance_double(Whatsapp::PhoneInfoService)
+      allow(Whatsapp::PhoneInfoService).to receive(:new)
+        .with(params[:waba_id], params[:phone_number_id], access_token).and_return(phone_service)
+      allow(phone_service).to receive(:perform).and_return(phone_info)
+
+      validation_service = instance_double(Whatsapp::TokenValidationService)
+      allow(Whatsapp::TokenValidationService).to receive(:new)
+        .with(access_token, params[:waba_id]).and_return(validation_service)
+      allow(validation_service).to receive(:perform)
+
+      channel_creation = instance_double(Whatsapp::ChannelCreationService)
+      allow(Whatsapp::ChannelCreationService).to receive(:new)
+        .with(account, { waba_id: params[:waba_id], business_name: 'Test Business' }, phone_info, access_token)
+        .and_return(channel_creation)
+      allow(channel_creation).to receive(:perform).and_return(channel)
+
+      allow(channel).to receive(:setup_webhooks)
+      allow(channel).to receive(:phone_number).and_return('+1234567890')
+
+      health_service = instance_double(Whatsapp::HealthService)
+      allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+      allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                          platform_type: 'CLOUD_API',
+                                                                          throughput: { 'level' => 'STANDARD' },
+                                                                          messaging_limit_tier: 'TIER_1000'
+                                                                        })
+    end
+
+    it 'creates channel and sets up webhooks' do
+      expect(channel).to receive(:setup_webhooks)
+
+      result = service.perform
+      expect(result).to eq(channel)
+    end
+
+    it 'checks health status after channel creation' do
+      health_service = instance_double(Whatsapp::HealthService)
+      allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+      expect(health_service).to receive(:fetch_health_status)
+
+      service.perform
+    end
+
+    context 'when channel is in pending state' do
+      it 'prompts reauthorization for pending channel' do
+        health_service = instance_double(Whatsapp::HealthService)
+        allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'NOT_APPLICABLE',
+                                                                            throughput: { 'level' => 'STANDARD' },
+                                                                            messaging_limit_tier: 'TIER_1000'
+                                                                          })
+
+        expect(channel).to receive(:prompt_reauthorization!)
+        service.perform
+      end
+
+      it 'prompts reauthorization when throughput level is NOT_APPLICABLE' do
+        health_service = instance_double(Whatsapp::HealthService)
+        allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'CLOUD_API',
+                                                                            throughput: { 'level' => 'NOT_APPLICABLE' },
+                                                                            messaging_limit_tier: 'TIER_1000'
+                                                                          })
+
+        expect(channel).to receive(:prompt_reauthorization!)
+        service.perform
+      end
+    end
+
+    context 'when channel is healthy' do
+      it 'does not prompt reauthorization for healthy channel' do
+        expect(channel).not_to receive(:prompt_reauthorization!)
+        service.perform
+      end
+    end
+
+    context 'when parameters are invalid' do
+      it 'raises ArgumentError for missing parameters' do
+        invalid_service = described_class.new(account: account, params: { code: '', business_id: '', waba_id: '' })
+        expect { invalid_service.perform }.to raise_error(ArgumentError, /Required parameters are missing/)
+      end
+    end
+
+    context 'when service fails' do
+      it 'logs and re-raises errors' do
+        token_exchange = instance_double(Whatsapp::TokenExchangeService)
+        allow(Whatsapp::TokenExchangeService).to receive(:new).and_return(token_exchange)
+        allow(token_exchange).to receive(:perform).and_raise('Token error')
+
+        expect(Rails.logger).to receive(:error).with('[WHATSAPP] Embedded signup failed: Token error')
+        expect { service.perform }.to raise_error('Token error')
+      end
+
+      it 'prompts reauthorization when webhook setup fails' do
+        # Create a real channel to test the actual webhook failure behavior
+        real_channel = create(:channel_whatsapp, account: account, phone_number: '+1234567890',
+                                                 validate_provider_config: false, sync_templates: false)
+
+        # Mock the channel creation to return our real channel
+        channel_creation = instance_double(Whatsapp::ChannelCreationService)
+        allow(Whatsapp::ChannelCreationService).to receive(:new).and_return(channel_creation)
+        allow(channel_creation).to receive(:perform).and_return(real_channel)
+
+        # Mock webhook setup to fail
+        allow(real_channel).to receive(:perform_webhook_setup).and_raise('Webhook setup error')
+
+        # Verify channel is not marked for reauthorization initially
+        expect(real_channel.reauthorization_required?).to be false
+
+        # The service completes successfully even if webhook fails (webhook error is rescued in setup_webhooks)
+        result = service.perform
+        expect(result).to eq(real_channel)
+
+        # Verify the channel is now marked for reauthorization
+        expect(real_channel.reauthorization_required?).to be true
+      end
+    end
+
+    context 'with reauthorization flow' do
+      let(:inbox_id) { 123 }
+      let(:reauth_service) { instance_double(Whatsapp::ReauthorizationService) }
+      let(:service_with_inbox) do
+        described_class.new(account: account, params: params, inbox_id: inbox_id)
+      end
+
+      before do
+        allow(Whatsapp::ReauthorizationService).to receive(:new).with(
+          account: account,
+          inbox_id: inbox_id,
+          phone_number_id: params[:phone_number_id],
+          business_id: params[:business_id]
+        ).and_return(reauth_service)
+        allow(reauth_service).to receive(:perform).with(access_token, phone_info).and_return(channel)
+
+        allow(channel).to receive(:phone_number).and_return('+1234567890')
+
+        health_service = instance_double(Whatsapp::HealthService)
+        allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'CLOUD_API',
+                                                                            throughput: { 'level' => 'STANDARD' },
+                                                                            messaging_limit_tier: 'TIER_1000'
+                                                                          })
+      end
+
+      it 'uses ReauthorizationService and sets up webhooks' do
+        expect(reauth_service).to receive(:perform)
+        expect(channel).to receive(:setup_webhooks)
+
+        result = service_with_inbox.perform
+        expect(result).to eq(channel)
+      end
+
+      context 'with real channel requiring reauthorization' do
+        let(:inbox) { create(:inbox, account: account) }
+        let(:whatsapp_channel) do
+          create(:channel_whatsapp, account: account, phone_number: '+1234567890',
+                                    validate_provider_config: false, sync_templates: false)
+        end
+        let(:service_with_real_inbox) { described_class.new(account: account, params: params, inbox_id: inbox.id) }
+
+        before do
+          inbox.update!(channel: whatsapp_channel)
+          whatsapp_channel.prompt_reauthorization!
+
+          setup_reauthorization_mocks
+          setup_health_service_mock
+        end
+
+        it 'clears reauthorization flag when reauthorization completes' do
+          expect(whatsapp_channel.reauthorization_required?).to be true
+          result = service_with_real_inbox.perform
+          expect(result).to eq(whatsapp_channel)
+          expect(whatsapp_channel.reauthorization_required?).to be false
+        end
+
+        private
+
+        def setup_reauthorization_mocks
+          reauth_service = instance_double(Whatsapp::ReauthorizationService)
+          allow(Whatsapp::ReauthorizationService).to receive(:new).with(
+            account: account,
+            inbox_id: inbox.id,
+            phone_number_id: params[:phone_number_id],
+            business_id: params[:business_id]
+          ).and_return(reauth_service)
+
+          allow(reauth_service).to receive(:perform) do
+            whatsapp_channel.reauthorized!
+            whatsapp_channel
+          end
+
+          allow(whatsapp_channel).to receive(:setup_webhooks).and_return(true)
+        end
+
+        def setup_health_service_mock
+          health_service = instance_double(Whatsapp::HealthService)
+          allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+          allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                              platform_type: 'CLOUD_API',
+                                                                              throughput: { 'level' => 'STANDARD' },
+                                                                              messaging_limit_tier: 'TIER_1000'
+                                                                            })
+        end
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/facebook_api_client_spec.rb

@@ -0,0 +1,274 @@
+require 'rails_helper'
+
+describe Whatsapp::FacebookApiClient do
+  let(:access_token) { 'test_access_token' }
+  let(:api_client) { described_class.new(access_token) }
+  let(:api_version) { 'v22.0' }
+  let(:app_id) { 'test_app_id' }
+  let(:app_secret) { 'test_app_secret' }
+
+  before do
+    allow(GlobalConfigService).to receive(:load).with('WHATSAPP_API_VERSION', 'v22.0').and_return(api_version)
+    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)
+  end
+
+  describe '#exchange_code_for_token' do
+    let(:code) { 'test_code' }
+
+    context 'when successful' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: { client_id: app_id, client_secret: app_secret, code: code })
+          .to_return(
+            status: 200,
+            body: { access_token: 'new_token' }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns the response data' do
+        result = api_client.exchange_code_for_token(code)
+        expect(result['access_token']).to eq('new_token')
+      end
+    end
+
+    context 'when failed' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/oauth/access_token")
+          .with(query: { 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 { api_client.exchange_code_for_token(code) }.to raise_error(/Token exchange failed/)
+      end
+    end
+  end
+
+  describe '#fetch_phone_numbers' do
+    let(:waba_id) { 'test_waba_id' }
+
+    context 'when successful' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: { access_token: access_token })
+          .to_return(
+            status: 200,
+            body: { data: [{ id: '123', display_phone_number: '1234567890' }] }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns the phone numbers data' do
+        result = api_client.fetch_phone_numbers(waba_id)
+        expect(result['data']).to be_an(Array)
+        expect(result['data'].first['id']).to eq('123')
+      end
+    end
+
+    context 'when failed' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/#{waba_id}/phone_numbers")
+          .with(query: { access_token: access_token })
+          .to_return(status: 403, body: { error: 'Access denied' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { api_client.fetch_phone_numbers(waba_id) }.to raise_error(/WABA phone numbers fetch failed/)
+      end
+    end
+  end
+
+  describe '#debug_token' do
+    let(:input_token) { 'test_input_token' }
+    let(:app_access_token) { "#{app_id}|#{app_secret}" }
+
+    context 'when successful' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+          .with(query: { input_token: input_token, access_token: app_access_token })
+          .to_return(
+            status: 200,
+            body: { data: { app_id: app_id, is_valid: true } }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns the debug token data' do
+        result = api_client.debug_token(input_token)
+        expect(result['data']['is_valid']).to be(true)
+      end
+    end
+
+    context 'when failed' do
+      before do
+        stub_request(:get, "https://graph.facebook.com/#{api_version}/debug_token")
+          .with(query: { input_token: input_token, access_token: app_access_token })
+          .to_return(status: 400, body: { error: 'Invalid token' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { api_client.debug_token(input_token) }.to raise_error(/Token validation failed/)
+      end
+    end
+  end
+
+  describe '#register_phone_number' do
+    let(:phone_number_id) { 'test_phone_id' }
+    let(:pin) { '123456' }
+
+    context 'when successful' do
+      before do
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{phone_number_id}/register")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
+            body: { messaging_product: 'whatsapp', pin: pin }.to_json
+          )
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns success response' do
+        result = api_client.register_phone_number(phone_number_id, pin)
+        expect(result['success']).to be(true)
+      end
+    end
+
+    context 'when failed' do
+      before do
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{phone_number_id}/register")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
+            body: { messaging_product: 'whatsapp', pin: pin }.to_json
+          )
+          .to_return(status: 400, body: { error: 'Registration failed' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { api_client.register_phone_number(phone_number_id, pin) }.to raise_error(/Phone registration failed/)
+      end
+    end
+  end
+
+  describe '#subscribe_waba_webhook' do
+    let(:waba_id) { 'test_waba_id' }
+    let(:callback_url) { 'https://example.com/webhook' }
+    let(:verify_token) { 'test_verify_token' }
+
+    context 'when successful' do
+      before do
+        # Step 1: Subscribe app to WABA (no body)
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' }
+          )
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Step 2: Override callback URL (with body)
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
+            body: { override_callback_uri: callback_url, verify_token: verify_token,
+                    subscribed_fields: %w[messages smb_message_echoes] }.to_json
+          )
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns success response' do
+        result = api_client.subscribe_waba_webhook(waba_id, callback_url, verify_token)
+        expect(result['success']).to be(true)
+      end
+    end
+
+    context 'when app subscription fails' do
+      before do
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' }
+          )
+          .to_return(status: 400, body: { error: 'App subscription to WABA failed' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { api_client.subscribe_waba_webhook(waba_id, callback_url, verify_token) }.to raise_error(/App subscription to WABA failed/)
+      end
+    end
+
+    context 'when callback override fails' do
+      before do
+        # Step 1 succeeds
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' }
+          )
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+
+        # Step 2 fails
+        stub_request(:post, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
+            body: { override_callback_uri: callback_url, verify_token: verify_token,
+                    subscribed_fields: %w[messages smb_message_echoes] }.to_json
+          )
+          .to_return(status: 400, body: { error: 'Webhook callback override failed' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { api_client.subscribe_waba_webhook(waba_id, callback_url, verify_token) }.to raise_error(/Webhook callback override failed/)
+      end
+    end
+  end
+
+  describe '#unsubscribe_waba_webhook' do
+    let(:waba_id) { 'test_waba_id' }
+
+    context 'when successful' do
+      before do
+        stub_request(:delete, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' }
+          )
+          .to_return(
+            status: 200,
+            body: { success: true }.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'returns success response' do
+        result = api_client.unsubscribe_waba_webhook(waba_id)
+        expect(result['success']).to be(true)
+      end
+    end
+
+    context 'when failed' do
+      before do
+        stub_request(:delete, "https://graph.facebook.com/#{api_version}/#{waba_id}/subscribed_apps")
+          .with(
+            headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' }
+          )
+          .to_return(status: 400, body: { error: 'Webhook unsubscription failed' }.to_json)
+      end
+
+      it 'raises an error' do
+        expect { api_client.unsubscribe_waba_webhook(waba_id) }.to raise_error(/Webhook unsubscription failed/)
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/incoming_message_service_spec.rb

@@ -0,0 +1,527 @@
+require 'rails_helper'
+
+describe Whatsapp::IncomingMessageService do
+  describe '#perform' do
+    before do
+      stub_request(:post, 'https://waba.360dialog.io/v1/configs/webhook')
+    end
+
+    after do
+      # The atomic dedup lock lives in Redis and is not rolled back by
+      # transactional fixtures. Clean up any keys created during the test.
+      Redis::Alfred.scan_each(match: 'MESSAGE_SOURCE_KEY::*') do |key|
+        Redis::Alfred.delete(key)
+      end
+    end
+
+    let!(:whatsapp_channel) { create(:channel_whatsapp, sync_templates: false) }
+    let(:wa_id) { '2423423243' }
+    let!(:params) do
+      {
+        'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => wa_id }],
+        'messages' => [{ 'from' => wa_id, 'id' => 'SDFADSf23sfasdafasdfa', 'text' => { 'body' => 'Test' },
+                         'timestamp' => '1633034394', 'type' => 'text' }]
+      }.with_indifferent_access
+    end
+
+    context 'when valid text message params' do
+      it 'creates appropriate conversations, message and contacts' do
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('Test')
+      end
+
+      it 'appends to last conversation when if conversation already exists' do
+        contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: params[:messages].first[:from])
+        2.times.each { create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox) }
+        last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        # no new conversation should be created
+        expect(whatsapp_channel.inbox.conversations.count).to eq(3)
+        # message appended to the last conversation
+        expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+      end
+
+      it 'reopen last conversation if last conversation is resolved and lock to single conversation is enabled' do
+        whatsapp_channel.inbox.update(lock_to_single_conversation: true)
+        contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: params[:messages].first[:from])
+        last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        last_conversation.update(status: 'resolved')
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        # no new conversation should be created
+        expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+        # message appended to the last conversation
+        expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+        expect(last_conversation.reload.status).to eq('open')
+      end
+
+      it 'creates a new conversation if last conversation is resolved and lock to single conversation is disabled' do
+        whatsapp_channel.inbox.update(lock_to_single_conversation: false)
+        contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: params[:messages].first[:from])
+        last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        last_conversation.update(status: 'resolved')
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        # new conversation should be created
+        expect(whatsapp_channel.inbox.conversations.count).to eq(2)
+        expect(contact_inbox.conversations.last.messages.last.content).to eq(params[:messages].first[:text][:body])
+      end
+
+      it 'will not create a new conversation if last conversation is not resolved and lock to single conversation is disabled' do
+        whatsapp_channel.inbox.update(lock_to_single_conversation: false)
+        contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: params[:messages].first[:from])
+        last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        last_conversation.update(status: Conversation.statuses.except('resolved').keys.sample)
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        # new conversation should be created
+        expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+        expect(contact_inbox.conversations.last.messages.last.content).to eq(params[:messages].first[:text][:body])
+      end
+
+      it 'will not create duplicate messages when same message is received' do
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.messages.count).to eq(1)
+
+        # this shouldn't create a duplicate message
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.messages.count).to eq(1)
+      end
+    end
+
+    context 'when unsupported message types' do
+      it 'ignores type ephemeral and does not create ghost conversation' do
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => '2423423243' }],
+          'messages' => [{ 'from' => '2423423243', 'id' => 'SDFADSf23sfasdafasdfa', 'text' => { 'body' => 'Test' },
+                           'timestamp' => '1633034394', 'type' => 'ephemeral' }]
+        }.with_indifferent_access
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).to eq(0)
+        expect(Contact.count).to eq(0)
+        expect(whatsapp_channel.inbox.messages.count).to eq(0)
+      end
+
+      it 'ignores type unsupported and does not create ghost conversation' do
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => '2423423243' }],
+          'messages' => [{
+            'errors' => [{ 'code': 131_051, 'title': 'Message type is currently not supported.' }],
+            :from => '2423423243', :id => 'wamid.SDFADSf23sfasdafasdfa',
+            :timestamp => '1667047370', :type => 'unsupported'
+          }]
+        }.with_indifferent_access
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).to eq(0)
+        expect(Contact.count).to eq(0)
+        expect(whatsapp_channel.inbox.messages.count).to eq(0)
+      end
+    end
+
+    context 'when valid status params' do
+      let(:from) { '2423423243' }
+      let(:contact_inbox) { create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: from) }
+      let(:params) do
+        {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => from }],
+          'messages' => [{ 'from' => from, 'id' => from, 'text' => { 'body' => 'Test' },
+                           'timestamp' => '1633034394', 'type' => 'text' }]
+        }.with_indifferent_access
+      end
+
+      before do
+        create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+      end
+
+      it 'update status message to read' do
+        status_params = {
+          'statuses' => [{ 'recipient_id' => from, 'id' => from, 'status' => 'read' }]
+        }.with_indifferent_access
+        message = Message.find_by!(source_id: from)
+        expect(message.status).to eq('sent')
+        described_class.new(inbox: whatsapp_channel.inbox, params: status_params).perform
+        expect(message.reload.status).to eq('read')
+      end
+
+      it 'update status message to failed' do
+        status_params = {
+          'statuses' => [{ 'recipient_id' => from, 'id' => from, 'status' => 'failed',
+                           'errors' => [{ 'code': 123, 'title': 'abc' }] }]
+        }.with_indifferent_access
+
+        message = Message.find_by!(source_id: from)
+        expect(message.status).to eq('sent')
+        described_class.new(inbox: whatsapp_channel.inbox, params: status_params).perform
+        expect(message.reload.status).to eq('failed')
+        expect(message.external_error).to eq('123: abc')
+      end
+
+      it 'will not throw error if unsupported status' do
+        status_params = {
+          'statuses' => [{ 'recipient_id' => from, 'id' => from, 'status' => 'deleted',
+                           'errors' => [{ 'code': 123, 'title': 'abc' }] }]
+        }.with_indifferent_access
+
+        message = Message.find_by!(source_id: from)
+        expect(message.status).to eq('sent')
+        expect { described_class.new(inbox: whatsapp_channel.inbox, params: status_params).perform }.not_to raise_error
+      end
+    end
+
+    context 'when valid interactive message params' do
+      it 'creates appropriate conversations, message and contacts' do
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => '2423423243' }],
+          'messages' => [{ 'from' => '2423423243', 'id' => 'SDFADSf23sfasdafasdfa',
+                           :interactive => {
+                             'button_reply': {
+                               'id': '1',
+                               'title': 'First Button'
+                             },
+                             'type': 'button_reply'
+                           },
+                           'timestamp' => '1633034394', 'type' => 'interactive' }]
+        }.with_indifferent_access
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('First Button')
+      end
+    end
+
+    # ref: https://github.com/chatwoot/chatwoot/issues/3795#issuecomment-1018057318
+    context 'when valid template button message params' do
+      it 'creates appropriate conversations, message and contacts' do
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => '2423423243' }],
+          'messages' => [{ 'from' => '2423423243', 'id' => 'SDFADSf23sfasdafasdfa',
+                           'button' => {
+                             'text' => 'Yes this is a button'
+                           },
+                           'timestamp' => '1633034394', 'type' => 'button' }]
+        }.with_indifferent_access
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('Yes this is a button')
+      end
+    end
+
+    context 'when valid attachment message params' do
+      it 'creates appropriate conversations, message and contacts' do
+        stub_request(:get, whatsapp_channel.media_url('b1c68f38-8734-4ad3-b4a1-ef0c10d683')).to_return(
+          status: 200,
+          body: File.read('spec/assets/sample.png'),
+          headers: {}
+        )
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => '2423423243' }],
+          'messages' => [{ 'from' => '2423423243', 'id' => 'SDFADSf23sfasdafasdfa',
+                           'image' => { 'id' => 'b1c68f38-8734-4ad3-b4a1-ef0c10d683',
+                                        'mime_type' => 'image/jpeg',
+                                        'sha256' => '29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db',
+                                        'caption' => 'Check out my product!' },
+                           'timestamp' => '1633034394', 'type' => 'image' }]
+        }.with_indifferent_access
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('Check out my product!')
+        expect(whatsapp_channel.inbox.messages.first.attachments.present?).to be true
+      end
+    end
+
+    context 'when valid location message params' do
+      it 'creates appropriate conversations, message and contacts' do
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Sojan Jose' }, 'wa_id' => '2423423243' }],
+          'messages' => [{ 'from' => '2423423243', 'id' => 'SDFADSf23sfasdafasdfa',
+                           'location' => { 'id' => 'b1c68f38-8734-4ad3-b4a1-ef0c10d683',
+                                           :address => 'San Francisco, CA, USA',
+                                           :latitude => 37.7893768,
+                                           :longitude => -122.3895553,
+                                           :name => 'Bay Bridge',
+                                           :url => 'http://location_url.test' },
+                           'timestamp' => '1633034394', 'type' => 'location' }]
+        }.with_indifferent_access
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        location_attachment = whatsapp_channel.inbox.messages.first.attachments.first
+        expect(location_attachment.file_type).to eq('location')
+        expect(location_attachment.fallback_title).to eq('Bay Bridge, San Francisco, CA, USA')
+        expect(location_attachment.coordinates_lat).to eq(37.7893768)
+        expect(location_attachment.coordinates_long).to eq(-122.3895553)
+        expect(location_attachment.external_url).to eq('http://location_url.test')
+      end
+    end
+
+    context 'when valid contact message params' do
+      it 'creates appropriate message and attachments' do
+        params = { 'contacts' => [{ 'profile' => { 'name' => 'Kedar' }, 'wa_id' => '919746334593' }],
+                   'messages' => [{ 'from' => '919446284490',
+                                    'id' => 'wamid.SDFADSf23sfasdafasdfa',
+                                    'timestamp' => '1675823265',
+                                    'type' => 'contacts',
+                                    'contacts' => [
+                                      {
+                                        'name' => { 'formatted_name' => 'Apple Inc.' },
+                                        'phones' => [{ 'phone' => '+911800', 'type' => 'MAIN' }]
+                                      },
+                                      { 'name' => { 'first_name' => 'Chatwoot', 'formatted_name' => 'Chatwoot' },
+                                        'phones' => [{ 'phone' => '+1 (415) 341-8386' }] }
+                                    ] }] }.with_indifferent_access
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(Contact.all.first.name).to eq('Kedar')
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+
+        m1 = whatsapp_channel.inbox.messages.first
+        expect(m1.content).to eq('Apple Inc.')
+        expect(m1.attachments.first.fallback_title).to eq('+911800')
+        expect(m1.attachments.first.meta).to eq({})
+
+        m2 = whatsapp_channel.inbox.messages.last
+        expect(m2.content).to eq('Chatwoot')
+        expect(m2.attachments.first.meta).to eq({ 'firstName' => 'Chatwoot' })
+      end
+    end
+
+    # ref: https://github.com/chatwoot/chatwoot/issues/5840
+    describe 'When the incoming waid is a brazilian number in new format with 9 included' do
+      let(:wa_id) { '5541988887777' }
+
+      it 'creates appropriate conversations, message and contacts if contact does not exit' do
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('Test')
+        expect(whatsapp_channel.inbox.contact_inboxes.first.source_id).to eq(wa_id)
+      end
+
+      it 'appends to existing contact if contact inbox exists' do
+        contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: wa_id)
+        last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        # no new conversation should be created
+        expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+        # message appended to the last conversation
+        expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+      end
+    end
+
+    describe 'When incoming waid is a brazilian number in old format without the 9 included' do
+      let(:wa_id) { '554188887777' }
+
+      context 'when a contact inbox exists in the old format without 9 included' do
+        it 'appends to existing contact' do
+          contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: wa_id)
+          last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+          described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+          # no new conversation should be created
+          expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+          # message appended to the last conversation
+          expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+        end
+      end
+
+      context 'when a contact inbox exists in the new format with 9 included' do
+        it 'appends to existing contact' do
+          contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: '5541988887777')
+          last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+          described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+          # no new conversation should be created
+          expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+          # message appended to the last conversation
+          expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+        end
+      end
+
+      context 'when a contact inbox does not exist in the new format with 9 included' do
+        it 'creates contact inbox with the incoming waid' do
+          described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+          expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+          expect(Contact.all.first.name).to eq('Sojan Jose')
+          expect(whatsapp_channel.inbox.messages.first.content).to eq('Test')
+          expect(whatsapp_channel.inbox.contact_inboxes.first.source_id).to eq(wa_id)
+        end
+      end
+    end
+
+    describe 'When the incoming waid is an Argentine number with 9 after country code' do
+      let(:wa_id) { '5491123456789' }
+
+      it 'creates appropriate conversations, message and contacts if contact does not exist' do
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('Test')
+        expect(whatsapp_channel.inbox.contact_inboxes.first.source_id).to eq(wa_id)
+      end
+
+      it 'appends to existing contact if contact inbox exists with normalized format' do
+        # Normalized format removes the 9 after country code
+        normalized_wa_id = '541123456789'
+        contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: normalized_wa_id)
+        last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        # no new conversation should be created
+        expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+        # message appended to the last conversation
+        expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+        # should use the normalized wa_id from existing contact
+        expect(whatsapp_channel.inbox.contact_inboxes.first.source_id).to eq(normalized_wa_id)
+      end
+    end
+
+    describe 'When incoming waid is an Argentine number without 9 after country code' do
+      let(:wa_id) { '541123456789' }
+
+      context 'when a contact inbox exists with the same format' do
+        it 'appends to existing contact' do
+          contact_inbox = create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: wa_id)
+          last_conversation = create(:conversation, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+          described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+          # no new conversation should be created
+          expect(whatsapp_channel.inbox.conversations.count).to eq(1)
+          # message appended to the last conversation
+          expect(last_conversation.messages.last.content).to eq(params[:messages].first[:text][:body])
+        end
+      end
+
+      context 'when a contact inbox does not exist' do
+        it 'creates contact inbox with the incoming waid' do
+          described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+          expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+          expect(Contact.all.first.name).to eq('Sojan Jose')
+          expect(whatsapp_channel.inbox.messages.first.content).to eq('Test')
+          expect(whatsapp_channel.inbox.contact_inboxes.first.source_id).to eq(wa_id)
+        end
+      end
+    end
+
+    describe 'when another worker already holds the dedup lock' do
+      it 'skips message creation' do
+        params = { 'contacts' => [{ 'profile' => { 'name' => 'Kedar' }, 'wa_id' => '919746334593' }],
+                   'messages' => [{ 'from' => '919446284490',
+                                    'id' => 'wamid.SDFADSf23sfasdafasdfa',
+                                    'timestamp' => '1675823265',
+                                    'type' => 'contacts',
+                                    'contacts' => [
+                                      {
+                                        'name' => { 'formatted_name' => 'Apple Inc.' },
+                                        'phones' => [{ 'phone' => '+911800', 'type' => 'MAIN' }]
+                                      },
+                                      { 'name' => { 'first_name' => 'Chatwoot', 'formatted_name' => 'Chatwoot' },
+                                        'phones' => [{ 'phone' => '+1 (415) 341-8386' }] }
+                                    ] }] }.with_indifferent_access
+
+        # Simulate another worker holding the lock
+        lock = Whatsapp::MessageDedupLock.new('wamid.SDFADSf23sfasdafasdfa')
+        expect(lock.acquire!).to be_truthy
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.messages.count).to eq(0)
+      ensure
+        key = format(Redis::RedisKeys::MESSAGE_SOURCE_KEY, id: 'wamid.SDFADSf23sfasdafasdfa')
+        Redis::Alfred.delete(key)
+      end
+    end
+
+    context 'when profile name is available for contact updates' do
+      let(:wa_id) { '1234567890' }
+      let(:phone_number) { "+#{wa_id}" }
+
+      it 'updates existing contact name when current name matches phone number' do
+        # Create contact with phone number as name
+        existing_contact = create(:contact,
+                                  account: whatsapp_channel.inbox.account,
+                                  name: phone_number,
+                                  phone_number: phone_number)
+        create(:contact_inbox,
+               contact: existing_contact,
+               inbox: whatsapp_channel.inbox,
+               source_id: wa_id)
+
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Jane Smith' }, 'wa_id' => wa_id }],
+          'messages' => [{ 'from' => wa_id, 'id' => 'message123', 'text' => { 'body' => 'Hello' },
+                           'timestamp' => '1633034394', 'type' => 'text' }]
+        }.with_indifferent_access
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        existing_contact.reload
+        expect(existing_contact.name).to eq('Jane Smith')
+      end
+
+      it 'does not update contact name when current name is different from phone number' do
+        # Create contact with human name
+        existing_contact = create(:contact,
+                                  account: whatsapp_channel.inbox.account,
+                                  name: 'John Doe',
+                                  phone_number: phone_number)
+        create(:contact_inbox,
+               contact: existing_contact,
+               inbox: whatsapp_channel.inbox,
+               source_id: wa_id)
+
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Jane Smith' }, 'wa_id' => wa_id }],
+          'messages' => [{ 'from' => wa_id, 'id' => 'message123', 'text' => { 'body' => 'Hello' },
+                           'timestamp' => '1633034394', 'type' => 'text' }]
+        }.with_indifferent_access
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        existing_contact.reload
+        expect(existing_contact.name).to eq('John Doe') # Should not change
+      end
+
+      it 'updates contact name when current name matches formatted phone number' do
+        formatted_number = TelephoneNumber.parse(phone_number).international_number
+
+        # Create contact with formatted phone number as name
+        existing_contact = create(:contact,
+                                  account: whatsapp_channel.inbox.account,
+                                  name: formatted_number,
+                                  phone_number: phone_number)
+        create(:contact_inbox,
+               contact: existing_contact,
+               inbox: whatsapp_channel.inbox,
+               source_id: wa_id)
+
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => 'Alice Johnson' }, 'wa_id' => wa_id }],
+          'messages' => [{ 'from' => wa_id, 'id' => 'message123', 'text' => { 'body' => 'Hello' },
+                           'timestamp' => '1633034394', 'type' => 'text' }]
+        }.with_indifferent_access
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        existing_contact.reload
+        expect(existing_contact.name).to eq('Alice Johnson')
+      end
+
+      it 'does not update when profile name is blank' do
+        # Create contact with phone number as name
+        existing_contact = create(:contact,
+                                  account: whatsapp_channel.inbox.account,
+                                  name: phone_number,
+                                  phone_number: phone_number)
+        create(:contact_inbox,
+               contact: existing_contact,
+               inbox: whatsapp_channel.inbox,
+               source_id: wa_id)
+
+        params = {
+          'contacts' => [{ 'profile' => { 'name' => '' }, 'wa_id' => wa_id }],
+          'messages' => [{ 'from' => wa_id, 'id' => 'message123', 'text' => { 'body' => 'Hello' },
+                           'timestamp' => '1633034394', 'type' => 'text' }]
+        }.with_indifferent_access
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        existing_contact.reload
+        expect(existing_contact.name).to eq(phone_number) # Should not change
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/incoming_message_whatsapp_cloud_service_spec.rb

@@ -0,0 +1,212 @@
+require 'rails_helper'
+
+describe Whatsapp::IncomingMessageWhatsappCloudService do
+  describe '#perform' do
+    after do
+      Redis::Alfred.scan_each(match: 'MESSAGE_SOURCE_KEY::*') { |key| Redis::Alfred.delete(key) }
+    end
+
+    let!(:whatsapp_channel) { create(:channel_whatsapp, provider: 'whatsapp_cloud', sync_templates: false, validate_provider_config: false) }
+    let(:params) do
+      {
+        phone_number: whatsapp_channel.phone_number,
+        object: 'whatsapp_business_account',
+        entry: [{
+          changes: [{
+            value: {
+              contacts: [{ profile: { name: 'Sojan Jose' }, wa_id: '2423423243' }],
+              messages: [{
+                from: '2423423243',
+                image: {
+                  id: 'b1c68f38-8734-4ad3-b4a1-ef0c10d683',
+                  mime_type: 'image/jpeg',
+                  sha256: '29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db',
+                  caption: 'Check out my product!'
+                },
+                timestamp: '1664799904', type: 'image'
+              }]
+            }
+          }]
+        }]
+      }.with_indifferent_access
+    end
+
+    context 'when valid attachment message params' do
+      it 'creates appropriate conversations, message and contacts' do
+        stub_media_url_request
+        stub_sample_png_request
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect_conversation_created
+        expect_contact_name
+        expect_message_content
+        expect_message_has_attachment
+      end
+
+      it 'increments reauthorization count if fetching attachment fails' do
+        stub_request(
+          :get,
+          whatsapp_channel.media_url('b1c68f38-8734-4ad3-b4a1-ef0c10d683')
+        ).to_return(
+          status: 401
+        )
+
+        described_class.new(inbox: whatsapp_channel.inbox, params: params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.first.content).to eq('Check out my product!')
+        expect(whatsapp_channel.inbox.messages.first.attachments.present?).to be false
+        expect(whatsapp_channel.authorization_error_count).to eq(1)
+      end
+    end
+
+    context 'when invalid attachment message params' do
+      let(:error_params) do
+        {
+          phone_number: whatsapp_channel.phone_number,
+          object: 'whatsapp_business_account',
+          entry: [{
+            changes: [{
+              value: {
+                contacts: [{ profile: { name: 'Sojan Jose' }, wa_id: '2423423243' }],
+                messages: [{
+                  from: '2423423243',
+                  image: {
+                    id: 'b1c68f38-8734-4ad3-b4a1-ef0c10d683',
+                    mime_type: 'image/jpeg',
+                    sha256: '29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db',
+                    caption: 'Check out my product!'
+                  },
+                  errors: [{
+                    code: 400,
+                    details: 'Last error was: ServerThrottle. Http request error: HTTP response code said error. See logs for details',
+                    title: 'Media download failed: Not retrying as download is not retriable at this time'
+                  }],
+                  timestamp: '1664799904', type: 'image'
+                }]
+              }
+            }]
+          }]
+        }.with_indifferent_access
+      end
+
+      it 'with attachment errors' do
+        described_class.new(inbox: whatsapp_channel.inbox, params: error_params).perform
+        expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+        expect(Contact.all.first.name).to eq('Sojan Jose')
+        expect(whatsapp_channel.inbox.messages.count).to eq(0)
+      end
+    end
+
+    context 'when invalid params' do
+      it 'will not throw error' do
+        described_class.new(inbox: whatsapp_channel.inbox, params: { phone_number: whatsapp_channel.phone_number,
+                                                                     object: 'whatsapp_business_account', entry: {} }).perform
+        expect(whatsapp_channel.inbox.conversations.count).to eq(0)
+        expect(Contact.all.first).to be_nil
+        expect(whatsapp_channel.inbox.messages.count).to eq(0)
+      end
+    end
+
+    context 'when message is a reply (has context)' do
+      let(:reply_params) do
+        {
+          phone_number: whatsapp_channel.phone_number,
+          object: 'whatsapp_business_account',
+          entry: [{
+            changes: [{
+              value: {
+                contacts: [{ profile: { name: 'Pranav' }, wa_id: '16503071063' }],
+                messages: [{
+                  context: {
+                    from: '16503071063',
+                    id: 'wamid.ORIGINAL_MESSAGE_ID'
+                  },
+                  from: '16503071063',
+                  id: 'wamid.REPLY_MESSAGE_ID',
+                  timestamp: '1770407829',
+                  text: { body: 'This is a reply' },
+                  type: 'text'
+                }]
+              }
+            }]
+          }]
+        }.with_indifferent_access
+      end
+
+      context 'when the original message exists in Chatwoot' do
+        it 'sets in_reply_to to reference the existing message' do
+          # Create a conversation and the original message that will be replied to first
+          contact = create(:contact, phone_number: '+16503071063', account: whatsapp_channel.account)
+          contact_inbox = create(:contact_inbox, contact: contact, inbox: whatsapp_channel.inbox, source_id: '16503071063')
+          conversation = create(:conversation, contact: contact, inbox: whatsapp_channel.inbox, contact_inbox: contact_inbox)
+
+          original_message = create(:message,
+                                    conversation: conversation,
+                                    source_id: 'wamid.ORIGINAL_MESSAGE_ID',
+                                    content: 'Original message')
+
+          described_class.new(inbox: whatsapp_channel.inbox, params: reply_params).perform
+
+          reply_message = whatsapp_channel.inbox.messages.last
+          expect(reply_message.content).to eq('This is a reply')
+          expect(reply_message.content_attributes['in_reply_to']).to eq(original_message.id)
+          expect(reply_message.content_attributes['in_reply_to_external_id']).to eq('wamid.ORIGINAL_MESSAGE_ID')
+        end
+      end
+
+      context 'when the original message does not exist in Chatwoot' do
+        it 'does not set in_reply_to (discards the reply reference)' do
+          described_class.new(inbox: whatsapp_channel.inbox, params: reply_params).perform
+
+          reply_message = whatsapp_channel.inbox.messages.last
+          expect(reply_message.content).to eq('This is a reply')
+          expect(reply_message.content_attributes['in_reply_to']).to be_nil
+          expect(reply_message.content_attributes['in_reply_to_external_id']).to be_nil
+        end
+      end
+    end
+  end
+
+  # Métodos auxiliares para reduzir o tamanho do exemplo
+
+  def stub_media_url_request
+    stub_request(
+      :get,
+      whatsapp_channel.media_url('b1c68f38-8734-4ad3-b4a1-ef0c10d683')
+    ).to_return(
+      status: 200,
+      body: {
+        messaging_product: 'whatsapp',
+        url: 'https://chatwoot-assets.local/sample.png',
+        mime_type: 'image/jpeg',
+        sha256: 'sha256',
+        file_size: 'SIZE',
+        id: 'b1c68f38-8734-4ad3-b4a1-ef0c10d683'
+      }.to_json,
+      headers: { 'content-type' => 'application/json' }
+    )
+  end
+
+  def stub_sample_png_request
+    stub_request(:get, 'https://chatwoot-assets.local/sample.png').to_return(
+      status: 200,
+      body: File.read('spec/assets/sample.png')
+    )
+  end
+
+  def expect_conversation_created
+    expect(whatsapp_channel.inbox.conversations.count).not_to eq(0)
+  end
+
+  def expect_contact_name
+    expect(Contact.all.first.name).to eq('Sojan Jose')
+  end
+
+  def expect_message_content
+    expect(whatsapp_channel.inbox.messages.first.content).to eq('Check out my product!')
+  end
+
+  def expect_message_has_attachment
+    expect(whatsapp_channel.inbox.messages.first.attachments.present?).to be true
+  end
+end

research/chatwoot/spec/services/whatsapp/message_dedup_lock_spec.rb

@@ -0,0 +1,43 @@
+require 'rails_helper'
+
+describe Whatsapp::MessageDedupLock do
+  let(:source_id) { "wamid.test_#{SecureRandom.hex(8)}" }
+  let(:lock) { described_class.new(source_id) }
+  let(:redis_key) { format(Redis::RedisKeys::MESSAGE_SOURCE_KEY, id: source_id) }
+
+  after { Redis::Alfred.delete(redis_key) }
+
+  describe '#acquire!' do
+    it 'returns truthy on first acquire' do
+      expect(lock.acquire!).to be_truthy
+    end
+
+    it 'returns falsy on second acquire for the same source_id' do
+      lock.acquire!
+      expect(described_class.new(source_id).acquire!).to be_falsy
+    end
+
+    it 'allows different source_ids to acquire independently' do
+      lock.acquire!
+      other = described_class.new("wamid.other_#{SecureRandom.hex(8)}")
+      expect(other.acquire!).to be_truthy
+    end
+
+    it 'lets exactly one thread win when two race for the same source_id' do
+      results = Concurrent::Array.new
+      barrier = Concurrent::CyclicBarrier.new(2)
+
+      threads = Array.new(2) do
+        Thread.new do
+          barrier.wait
+          results << described_class.new(source_id).acquire!
+        end
+      end
+
+      threads.each(&:join)
+
+      wins = results.count { |r| r }
+      expect(wins).to eq(1), "Expected exactly 1 winner but got #{wins}. Results: #{results.inspect}"
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/oneoff_campaign_service_spec.rb

@@ -0,0 +1,180 @@
+require 'rails_helper'
+
+describe Whatsapp::OneoffCampaignService do
+  let(:account) { create(:account) }
+  let!(:whatsapp_channel) do
+    create(:channel_whatsapp, account: account, provider: 'whatsapp_cloud', validate_provider_config: false, sync_templates: false)
+  end
+  let!(:whatsapp_inbox) { whatsapp_channel.inbox }
+  let(:label1) { create(:label, account: account) }
+  let(:label2) { create(:label, account: account) }
+  let!(:campaign) do
+    create(:campaign, inbox: whatsapp_inbox, account: account,
+                      audience: [{ type: 'Label', id: label1.id }, { type: 'Label', id: label2.id }],
+                      template_params: template_params)
+  end
+  let(:template_params) do
+    {
+      'name' => 'ticket_status_updated',
+      'namespace' => '23423423_2342423_324234234_2343224',
+      'category' => 'UTILITY',
+      'language' => 'en',
+      'processed_params' => { 'body' => { 'name' => 'John', 'ticket_id' => '2332' } }
+    }
+  end
+
+  before do
+    # Stub HTTP requests to WhatsApp API
+    stub_request(:post, /graph\.facebook\.com.*messages/)
+      .to_return(status: 200, body: { messages: [{ id: 'message_id_123' }] }.to_json, headers: { 'Content-Type' => 'application/json' })
+
+    # Ensure the service uses our mocked channel object by stubbing the whole delegation chain
+    # Using allow_any_instance_of here because the service is instantiated within individual tests
+    # and we need to mock the delegated channel method for proper test isolation
+    allow_any_instance_of(described_class).to receive(:channel).and_return(whatsapp_channel) # rubocop:disable RSpec/AnyInstance
+  end
+
+  describe '#perform' do
+    before do
+      # Enable WhatsApp campaigns feature flag for all tests
+      account.enable_features!(:whatsapp_campaign)
+    end
+
+    context 'when campaign validation fails' do
+      it 'raises error if campaign is completed' do
+        campaign.completed!
+
+        expect { described_class.new(campaign: campaign).perform }.to raise_error 'Completed Campaign'
+      end
+
+      it 'raises error when campaign is not a WhatsApp campaign' do
+        sms_channel = create(:channel_sms, account: account)
+        sms_inbox = create(:inbox, channel: sms_channel, account: account)
+        invalid_campaign = create(:campaign, inbox: sms_inbox, account: account)
+
+        expect { described_class.new(campaign: invalid_campaign).perform }
+          .to raise_error "Invalid campaign #{invalid_campaign.id}"
+      end
+
+      it 'raises error when campaign is not oneoff' do
+        allow(campaign).to receive(:one_off?).and_return(false)
+
+        expect { described_class.new(campaign: campaign).perform }.to raise_error "Invalid campaign #{campaign.id}"
+      end
+
+      it 'raises error when channel provider is not whatsapp_cloud' do
+        whatsapp_channel.update!(provider: 'default')
+
+        expect { described_class.new(campaign: campaign).perform }.to raise_error 'WhatsApp Cloud provider required'
+      end
+
+      it 'raises error when WhatsApp campaigns feature is not enabled' do
+        account.disable_features!(:whatsapp_campaign)
+
+        expect { described_class.new(campaign: campaign).perform }.to raise_error 'WhatsApp campaigns feature not enabled'
+      end
+    end
+
+    context 'when campaign is valid' do
+      it 'marks campaign as completed' do
+        described_class.new(campaign: campaign).perform
+
+        expect(campaign.reload.completed?).to be true
+      end
+
+      it 'processes contacts with matching labels' do
+        contact_with_label1, contact_with_label2, contact_with_both_labels =
+          create_list(:contact, 3, :with_phone_number, account: account)
+        contact_with_label1.update_labels([label1.title])
+        contact_with_label2.update_labels([label2.title])
+        contact_with_both_labels.update_labels([label1.title, label2.title])
+
+        expect(whatsapp_channel).to receive(:send_template).exactly(3).times
+
+        described_class.new(campaign: campaign).perform
+      end
+
+      it 'skips contacts without phone numbers' do
+        contact_without_phone = create(:contact, account: account, phone_number: nil)
+        contact_without_phone.update_labels([label1.title])
+
+        expect(whatsapp_channel).not_to receive(:send_template)
+
+        described_class.new(campaign: campaign).perform
+      end
+
+      it 'uses template processor service to process templates' do
+        contact = create(:contact, :with_phone_number, account: account)
+        contact.update_labels([label1.title])
+
+        expect(Whatsapp::TemplateProcessorService).to receive(:new)
+          .with(channel: whatsapp_channel, template_params: template_params)
+          .and_call_original
+
+        described_class.new(campaign: campaign).perform
+      end
+
+      it 'sends template message with correct parameters' do
+        contact = create(:contact, :with_phone_number, account: account)
+        contact.update_labels([label1.title])
+
+        expect(whatsapp_channel).to receive(:send_template).with(
+          contact.phone_number,
+          hash_including(
+            name: 'ticket_status_updated',
+            namespace: '23423423_2342423_324234234_2343224',
+            lang_code: 'en',
+            parameters: array_including(
+              hash_including(
+                type: 'body',
+                parameters: array_including(
+                  hash_including(type: 'text', parameter_name: 'name', text: 'John'),
+                  hash_including(type: 'text', parameter_name: 'ticket_id', text: '2332')
+                )
+              )
+            )
+          ),
+          nil
+        )
+
+        described_class.new(campaign: campaign).perform
+      end
+    end
+
+    context 'when template_params is missing' do
+      let(:template_params) { nil }
+
+      it 'skips contacts and logs error' do
+        contact = create(:contact, :with_phone_number, account: account)
+        contact.update_labels([label1.title])
+
+        expect(Rails.logger).to receive(:error)
+          .with("Skipping contact #{contact.name} - no template_params found for WhatsApp campaign")
+        expect(whatsapp_channel).not_to receive(:send_template)
+
+        described_class.new(campaign: campaign).perform
+      end
+    end
+
+    context 'when send_template raises an error' do
+      it 'logs error and continues processing remaining contacts' do
+        contact_error, contact_success = create_list(:contact, 2, :with_phone_number, account: account)
+        contact_error.update_labels([label1.title])
+        contact_success.update_labels([label1.title])
+        error_message = 'WhatsApp API error'
+
+        allow(whatsapp_channel).to receive(:send_template).and_return(nil)
+
+        expect(whatsapp_channel).to receive(:send_template).with(contact_error.phone_number, anything, nil).and_raise(StandardError, error_message)
+        expect(whatsapp_channel).to receive(:send_template).with(contact_success.phone_number, anything, nil).once
+
+        expect(Rails.logger).to receive(:error)
+          .with("Failed to send WhatsApp template message to #{contact_error.phone_number}: #{error_message}")
+        expect(Rails.logger).to receive(:error).with(/Backtrace:/)
+
+        described_class.new(campaign: campaign).perform
+        expect(campaign.reload.completed?).to be true
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/phone_info_service_spec.rb

@@ -0,0 +1,147 @@
+require 'rails_helper'
+
+describe Whatsapp::PhoneInfoService do
+  let(:waba_id) { 'test_waba_id' }
+  let(:phone_number_id) { 'test_phone_number_id' }
+  let(:access_token) { 'test_access_token' }
+  let(:service) { described_class.new(waba_id, phone_number_id, access_token) }
+  let(:api_client) { instance_double(Whatsapp::FacebookApiClient) }
+
+  before do
+    allow(Whatsapp::FacebookApiClient).to receive(:new).with(access_token).and_return(api_client)
+  end
+
+  describe '#perform' do
+    let(:phone_response) do
+      {
+        'data' => [
+          {
+            'id' => phone_number_id,
+            'display_phone_number' => '1234567890',
+            'verified_name' => 'Test Business',
+            'code_verification_status' => 'VERIFIED'
+          }
+        ]
+      }
+    end
+
+    context 'when all parameters are valid' do
+      before do
+        allow(api_client).to receive(:fetch_phone_numbers).with(waba_id).and_return(phone_response)
+      end
+
+      it 'returns formatted phone info' do
+        result = service.perform
+        expect(result).to eq({
+                               phone_number_id: phone_number_id,
+                               phone_number: '+1234567890',
+                               verified: true,
+                               business_name: 'Test Business'
+                             })
+      end
+    end
+
+    context 'when phone_number_id is not provided' do
+      let(:phone_number_id) { nil }
+      let(:phone_response) do
+        {
+          'data' => [
+            {
+              'id' => 'first_phone_id',
+              'display_phone_number' => '1234567890',
+              'verified_name' => 'Test Business',
+              'code_verification_status' => 'VERIFIED'
+            }
+          ]
+        }
+      end
+
+      before do
+        allow(api_client).to receive(:fetch_phone_numbers).with(waba_id).and_return(phone_response)
+      end
+
+      it 'uses the first available phone number' do
+        result = service.perform
+        expect(result[:phone_number_id]).to eq('first_phone_id')
+      end
+    end
+
+    context 'when specific phone_number_id is not found' do
+      let(:phone_number_id) { 'different_id' }
+      let(:phone_response) do
+        {
+          'data' => [
+            {
+              'id' => 'available_phone_id',
+              'display_phone_number' => '9876543210',
+              'verified_name' => 'Different Business',
+              'code_verification_status' => 'VERIFIED'
+            }
+          ]
+        }
+      end
+
+      before do
+        allow(api_client).to receive(:fetch_phone_numbers).with(waba_id).and_return(phone_response)
+      end
+
+      it 'uses the first available phone number as fallback' do
+        result = service.perform
+        expect(result[:phone_number_id]).to eq('available_phone_id')
+        expect(result[:phone_number]).to eq('+9876543210')
+      end
+    end
+
+    context 'when no phone numbers are available' do
+      let(:phone_response) { { 'data' => [] } }
+
+      before do
+        allow(api_client).to receive(:fetch_phone_numbers).with(waba_id).and_return(phone_response)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/No phone numbers found for WABA/)
+      end
+    end
+
+    context 'when waba_id is blank' do
+      let(:waba_id) { '' }
+
+      it 'raises ArgumentError' do
+        expect { service.perform }.to raise_error(ArgumentError, 'WABA ID is required')
+      end
+    end
+
+    context 'when access_token is blank' do
+      let(:access_token) { '' }
+
+      it 'raises ArgumentError' do
+        expect { service.perform }.to raise_error(ArgumentError, 'Access token is required')
+      end
+    end
+
+    context 'when phone number has special characters' do
+      let(:phone_response) do
+        {
+          'data' => [
+            {
+              'id' => phone_number_id,
+              'display_phone_number' => '+1 (234) 567-8900',
+              'verified_name' => 'Test Business',
+              'code_verification_status' => 'VERIFIED'
+            }
+          ]
+        }
+      end
+
+      before do
+        allow(api_client).to receive(:fetch_phone_numbers).with(waba_id).and_return(phone_response)
+      end
+
+      it 'sanitizes the phone number' do
+        result = service.perform
+        expect(result[:phone_number]).to eq('+12345678900')
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/populate_template_parameters_service_spec.rb

@@ -0,0 +1,70 @@
+require 'rails_helper'
+
+describe Whatsapp::PopulateTemplateParametersService do
+  let(:service) { described_class.new }
+
+  describe '#normalize_url' do
+    it 'normalizes URLs with spaces' do
+      url_with_spaces = 'https://example.com/path with spaces'
+      normalized = service.send(:normalize_url, url_with_spaces)
+
+      expect(normalized).to eq('https://example.com/path%20with%20spaces')
+    end
+
+    it 'handles URLs with special characters' do
+      url = 'https://example.com/path?query=test value'
+      normalized = service.send(:normalize_url, url)
+
+      expect(normalized).to include('https://example.com/path')
+      expect(normalized).not_to include(' ')
+    end
+
+    it 'returns valid URLs unchanged' do
+      url = 'https://example.com/valid-path'
+      normalized = service.send(:normalize_url, url)
+
+      expect(normalized).to eq(url)
+    end
+  end
+
+  describe '#build_media_parameter' do
+    context 'when URL contains spaces' do
+      it 'normalizes the URL before building media parameter' do
+        url_with_spaces = 'https://example.com/image with spaces.jpg'
+        result = service.build_media_parameter(url_with_spaces, 'IMAGE')
+
+        expect(result[:type]).to eq('image')
+        expect(result[:image][:link]).to eq('https://example.com/image%20with%20spaces.jpg')
+      end
+    end
+
+    context 'when URL contains special characters in query string' do
+      it 'normalizes the URL correctly' do
+        url = 'https://example.com/video.mp4?title=My Video'
+        result = service.build_media_parameter(url, 'VIDEO', 'test_video')
+
+        expect(result[:type]).to eq('video')
+        expect(result[:video][:link]).not_to include(' ')
+      end
+    end
+
+    context 'when URL is already valid' do
+      it 'builds media parameter without changing URL' do
+        url = 'https://example.com/document.pdf'
+        result = service.build_media_parameter(url, 'DOCUMENT', 'test.pdf')
+
+        expect(result[:type]).to eq('document')
+        expect(result[:document][:link]).to eq(url)
+        expect(result[:document][:filename]).to eq('test.pdf')
+      end
+    end
+
+    context 'when URL is blank' do
+      it 'returns nil' do
+        result = service.build_media_parameter('', 'IMAGE')
+
+        expect(result).to be_nil
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/providers/whatsapp360_dialog_service_spec.rb

@@ -0,0 +1,81 @@
+## the older specs are covered in send in spec/services/whatsapp/send_on_whatsapp_service_spec.rb
+require 'rails_helper'
+
+describe Whatsapp::Providers::Whatsapp360DialogService do
+  subject(:service) { described_class.new(whatsapp_channel: whatsapp_channel) }
+
+  let!(:whatsapp_channel) { create(:channel_whatsapp, sync_templates: false, validate_provider_config: false) }
+  let(:response_headers) { { 'Content-Type' => 'application/json' } }
+  let(:whatsapp_response) { { messages: [{ id: 'message_id' }] } }
+
+  describe '#sync_templates' do
+    context 'when called' do
+      it 'updates message_templates_last_updated even when template request fails' do
+        stub_request(:get, 'https://waba.360dialog.io/v1/configs/templates')
+          .to_return(status: 401)
+
+        timstamp = whatsapp_channel.reload.message_templates_last_updated
+        subject.sync_templates
+        expect(whatsapp_channel.reload.message_templates_last_updated).not_to eq(timstamp)
+      end
+    end
+  end
+
+  describe '#send_interactive message' do
+    context 'when called' do
+      it 'calls message endpoints with button payload when number of items is less than or equal to 3' do
+        message = create(:message, message_type: :outgoing, content: 'test',
+                                   inbox: whatsapp_channel.inbox, content_type: 'input_select',
+                                   content_attributes: {
+                                     items: [
+                                       { title: 'Burito', value: 'Burito' },
+                                       { title: 'Pasta', value: 'Pasta' },
+                                       { title: 'Sushi', value: 'Sushi' }
+                                     ]
+                                   })
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            body: {
+              to: '+123456789',
+              interactive: {
+                type: 'button',
+                body: {
+                  text: 'test'
+                },
+                action: '{"buttons":[{"type":"reply","reply":{"id":"Burito","title":"Burito"}},{"type":"reply",' \
+                        '"reply":{"id":"Pasta","title":"Pasta"}},{"type":"reply","reply":{"id":"Sushi","title":"Sushi"}}]}'
+              }, type: 'interactive'
+            }.to_json
+          ).to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+
+      it 'calls message endpoints with list payload when number of items is greater than 3' do
+        items = %w[Burito Pasta Sushi Salad].map { |i| { title: i, value: i } }
+        message = create(:message, message_type: :outgoing, content: 'test', inbox: whatsapp_channel.inbox,
+                                   content_type: 'input_select', content_attributes: { items: items })
+
+        expected_action = {
+          button: I18n.t('conversations.messages.whatsapp.list_button_label'),
+          sections: [{ rows: %w[Burito Pasta Sushi Salad].map { |i| { id: i, title: i } } }]
+        }.to_json
+
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            body: {
+              to: '+123456789',
+              interactive: {
+                type: 'list',
+                body: {
+                  text: 'test'
+                },
+                action: expected_action
+              },
+              type: 'interactive'
+            }.to_json
+          ).to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/providers/whatsapp_cloud_service_spec.rb

@@ -0,0 +1,403 @@
+require 'rails_helper'
+
+describe Whatsapp::Providers::WhatsappCloudService do
+  subject(:service) { described_class.new(whatsapp_channel: whatsapp_channel) }
+
+  let(:conversation) { create(:conversation, inbox: whatsapp_channel.inbox) }
+  let(:whatsapp_channel) { create(:channel_whatsapp, provider: 'whatsapp_cloud', validate_provider_config: false, sync_templates: false) }
+
+  let(:message) do
+    create(:message, conversation: conversation, message_type: :outgoing, content: 'test', inbox: whatsapp_channel.inbox, source_id: 'external_id')
+  end
+
+  let(:message_with_reply) do
+    create(:message, conversation: conversation, message_type: :outgoing, content: 'reply', inbox: whatsapp_channel.inbox,
+                     content_attributes: { in_reply_to: message.id })
+  end
+
+  let(:response_headers) { { 'Content-Type' => 'application/json' } }
+  let(:whatsapp_response) { { messages: [{ id: 'message_id' }] } }
+
+  before do
+    stub_request(:get, 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key')
+  end
+
+  describe '#send_message' do
+    context 'when called' do
+      it 'calls message endpoints for normal messages' do
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: {
+              messaging_product: 'whatsapp',
+              context: nil,
+              to: '+123456789',
+              text: { body: message.content },
+              type: 'text'
+            }.to_json
+          )
+          .to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+
+      it 'calls message endpoints for a reply to messages' do
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: {
+              messaging_product: 'whatsapp',
+              context: {
+                message_id: message.source_id
+              },
+              to: '+123456789',
+              text: { body: message_with_reply.content },
+              type: 'text'
+            }.to_json
+          )
+          .to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message_with_reply)).to eq 'message_id'
+      end
+
+      it 'calls message endpoints for image attachment message messages' do
+        attachment = message.attachments.new(account_id: message.account_id, file_type: :image)
+        attachment.file.attach(io: Rails.root.join('spec/assets/avatar.png').open, filename: 'avatar.png', content_type: 'image/png')
+
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: hash_including({
+                                   messaging_product: 'whatsapp',
+                                   to: '+123456789',
+                                   type: 'image',
+                                   image: WebMock::API.hash_including({ caption: message.content, link: anything })
+                                 })
+          )
+          .to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+
+      it 'calls message endpoints for document attachment message messages' do
+        attachment = message.attachments.new(account_id: message.account_id, file_type: :file)
+        attachment.file.attach(io: Rails.root.join('spec/assets/sample.pdf').open, filename: 'sample.pdf', content_type: 'application/pdf')
+
+        # ref: https://github.com/bblimke/webmock/issues/900
+        # reason for Webmock::API.hash_including
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: hash_including({
+                                   messaging_product: 'whatsapp',
+                                   to: '+123456789',
+                                   type: 'document',
+                                   document: WebMock::API.hash_including({ filename: 'sample.pdf', caption: message.content, link: anything })
+                                 })
+          )
+          .to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+    end
+  end
+
+  describe '#send_interactive message' do
+    context 'when called' do
+      it 'calls message endpoints with button payload when number of items is less than or equal to 3' do
+        message = create(:message, message_type: :outgoing, content: 'test',
+                                   inbox: whatsapp_channel.inbox, content_type: 'input_select',
+                                   content_attributes: {
+                                     items: [
+                                       { title: 'Burito', value: 'Burito' },
+                                       { title: 'Pasta', value: 'Pasta' },
+                                       { title: 'Sushi', value: 'Sushi' }
+                                     ]
+                                   })
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: {
+              messaging_product: 'whatsapp', to: '+123456789',
+              interactive: {
+                type: 'button',
+                body: {
+                  text: 'test'
+                },
+                action: '{"buttons":[{"type":"reply","reply":{"id":"Burito","title":"Burito"}},{"type":"reply",' \
+                        '"reply":{"id":"Pasta","title":"Pasta"}},{"type":"reply","reply":{"id":"Sushi","title":"Sushi"}}]}'
+              }, type: 'interactive'
+            }.to_json
+          ).to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+
+      it 'calls message endpoints with list payload when number of items is greater than 3' do
+        items = %w[Burito Pasta Sushi Salad].map { |i| { title: i, value: i } }
+        message = create(:message, message_type: :outgoing, content: 'test', inbox: whatsapp_channel.inbox,
+                                   content_type: 'input_select', content_attributes: { items: items })
+
+        expected_action = {
+          button: I18n.t('conversations.messages.whatsapp.list_button_label'),
+          sections: [{ rows: %w[Burito Pasta Sushi Salad].map { |i| { id: i, title: i } } }]
+        }.to_json
+
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: {
+              messaging_product: 'whatsapp', to: '+123456789',
+              interactive: {
+                type: 'list',
+                body: {
+                  text: 'test'
+                },
+                action: expected_action
+              },
+              type: 'interactive'
+            }.to_json
+          ).to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+        expect(service.send_message('+123456789', message)).to eq 'message_id'
+      end
+    end
+  end
+
+  describe '#send_template' do
+    let(:template_info) do
+      {
+        name: 'test_template',
+        namespace: 'test_namespace',
+        lang_code: 'en_US',
+        parameters: [{ type: 'text', text: 'test' }]
+      }
+    end
+
+    let(:template_body) do
+      {
+        messaging_product: 'whatsapp',
+        recipient_type: 'individual', # Added recipient_type field
+        to: '+123456789',
+        type: 'template',
+        template: {
+          name: template_info[:name],
+          language: {
+            policy: 'deterministic',
+            code: template_info[:lang_code]
+          },
+          components: template_info[:parameters] # Changed to use parameters directly (enhanced format)
+        }
+      }
+    end
+
+    context 'when called' do
+      it 'calls message endpoints with template params for template messages' do
+        stub_request(:post, 'https://graph.facebook.com/v13.0/123456789/messages')
+          .with(
+            body: template_body.to_json
+          )
+          .to_return(status: 200, body: whatsapp_response.to_json, headers: response_headers)
+
+        expect(service.send_template('+123456789', template_info, message)).to eq('message_id')
+      end
+    end
+  end
+
+  describe '#sync_templates' do
+    context 'when called' do
+      it 'updated the message templates' do
+        stub_request(:get, 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key')
+          .to_return(
+            { status: 200, headers: response_headers,
+              body: { data: [
+                { id: '123456789', name: 'test_template' }
+              ], paging: { next: 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key' } }.to_json },
+            { status: 200, headers: response_headers,
+              body: { data: [
+                { id: '123456789', name: 'next_template' }
+              ], paging: { next: 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key' } }.to_json },
+            { status: 200, headers: response_headers,
+              body: { data: [
+                { id: '123456789', name: 'last_template' }
+              ], paging: { prev: 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key' } }.to_json }
+          )
+
+        timstamp = whatsapp_channel.reload.message_templates_last_updated
+        expect(subject.sync_templates).to be(true)
+        expect(whatsapp_channel.reload.message_templates.first).to eq({ id: '123456789', name: 'test_template' }.stringify_keys)
+        expect(whatsapp_channel.reload.message_templates.second).to eq({ id: '123456789', name: 'next_template' }.stringify_keys)
+        expect(whatsapp_channel.reload.message_templates.last).to eq({ id: '123456789', name: 'last_template' }.stringify_keys)
+        expect(whatsapp_channel.reload.message_templates_last_updated).not_to eq(timstamp)
+      end
+
+      it 'updates message_templates_last_updated even when template request fails' do
+        stub_request(:get, 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key')
+          .to_return(status: 401)
+
+        timstamp = whatsapp_channel.reload.message_templates_last_updated
+        subject.sync_templates
+        expect(whatsapp_channel.reload.message_templates_last_updated).not_to eq(timstamp)
+      end
+    end
+  end
+
+  describe '#validate_provider_config' do
+    context 'when called' do
+      it 'returns true if valid' do
+        stub_request(:get, 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key')
+        expect(subject.validate_provider_config?).to be(true)
+        expect(whatsapp_channel.errors.present?).to be(false)
+      end
+
+      it 'returns false if invalid' do
+        stub_request(:get, 'https://graph.facebook.com/v14.0/123456789/message_templates?access_token=test_key').to_return(status: 401)
+        expect(subject.validate_provider_config?).to be(false)
+      end
+    end
+  end
+
+  describe 'Ability to configure Base URL' do
+    context 'when environment variable WHATSAPP_CLOUD_BASE_URL is not set' do
+      it 'uses the default base url' do
+        expect(subject.send(:api_base_path)).to eq('https://graph.facebook.com')
+      end
+    end
+
+    context 'when environment variable WHATSAPP_CLOUD_BASE_URL is set' do
+      it 'uses the base url from the environment variable' do
+        with_modified_env WHATSAPP_CLOUD_BASE_URL: 'http://test.com' do
+          expect(subject.send(:api_base_path)).to eq('http://test.com')
+        end
+      end
+    end
+  end
+
+  describe '#handle_error' do
+    let(:error_message) { 'Invalid message format' }
+    let(:error_response) do
+      {
+        'error' => {
+          'message' => error_message,
+          'code' => 100
+        }
+      }
+    end
+
+    let(:error_response_object) do
+      instance_double(
+        HTTParty::Response,
+        body: error_response.to_json,
+        parsed_response: error_response
+      )
+    end
+
+    before do
+      allow(Rails.logger).to receive(:error)
+    end
+
+    context 'when there is a message' do
+      it 'logs error and updates message status' do
+        service.instance_variable_set(:@message, message)
+        service.send(:handle_error, error_response_object, message)
+
+        expect(message.reload.status).to eq('failed')
+        expect(message.reload.external_error).to eq(error_message)
+      end
+    end
+
+    context 'when error message is blank' do
+      let(:error_response_object) do
+        instance_double(
+          HTTParty::Response,
+          body: '{}',
+          parsed_response: {}
+        )
+      end
+
+      it 'logs error but does not update message' do
+        service.instance_variable_set(:@message, message)
+        service.send(:handle_error, error_response_object, message)
+
+        expect(message.reload.status).not_to eq('failed')
+        expect(message.reload.external_error).to be_nil
+      end
+    end
+  end
+
+  describe 'CSAT template methods' do
+    let(:mock_csat_template_service) { instance_double(Whatsapp::CsatTemplateService) }
+    let(:expected_template_name) { "customer_satisfaction_survey_#{whatsapp_channel.inbox.id}" }
+    let(:template_config) do
+      {
+        name: expected_template_name,
+        language: 'en',
+        category: 'UTILITY'
+      }
+    end
+
+    before do
+      allow(Whatsapp::CsatTemplateService).to receive(:new)
+        .with(whatsapp_channel)
+        .and_return(mock_csat_template_service)
+    end
+
+    describe '#create_csat_template' do
+      it 'delegates to csat_template_service with correct config' do
+        allow(mock_csat_template_service).to receive(:create_template)
+          .with(template_config)
+          .and_return({ success: true, template_id: '123' })
+
+        result = service.create_csat_template(template_config)
+
+        expect(mock_csat_template_service).to have_received(:create_template).with(template_config)
+        expect(result).to eq({ success: true, template_id: '123' })
+      end
+    end
+
+    describe '#delete_csat_template' do
+      it 'delegates to csat_template_service with default template name' do
+        allow(mock_csat_template_service).to receive(:delete_template)
+          .with(expected_template_name)
+          .and_return({ success: true })
+
+        result = service.delete_csat_template
+
+        expect(mock_csat_template_service).to have_received(:delete_template).with(expected_template_name)
+        expect(result).to eq({ success: true })
+      end
+
+      it 'delegates to csat_template_service with custom template name' do
+        custom_template_name = 'custom_csat_template'
+        allow(mock_csat_template_service).to receive(:delete_template)
+          .with(custom_template_name)
+          .and_return({ success: true })
+
+        result = service.delete_csat_template(custom_template_name)
+
+        expect(mock_csat_template_service).to have_received(:delete_template).with(custom_template_name)
+        expect(result).to eq({ success: true })
+      end
+    end
+
+    describe '#get_template_status' do
+      it 'delegates to csat_template_service with template name' do
+        template_name = 'customer_survey_template'
+        expected_response = { success: true, template: { status: 'APPROVED' } }
+        allow(mock_csat_template_service).to receive(:get_template_status)
+          .with(template_name)
+          .and_return(expected_response)
+
+        result = service.get_template_status(template_name)
+
+        expect(mock_csat_template_service).to have_received(:get_template_status).with(template_name)
+        expect(result).to eq(expected_response)
+      end
+    end
+
+    describe 'csat_template_service memoization' do
+      it 'creates and memoizes the csat_template_service instance' do
+        allow(Whatsapp::CsatTemplateService).to receive(:new)
+          .with(whatsapp_channel)
+          .and_return(mock_csat_template_service)
+        allow(mock_csat_template_service).to receive(:get_template_status)
+          .and_return({ success: true })
+
+        # Call multiple methods that use the service
+        service.get_template_status('test1')
+        service.get_template_status('test2')
+
+        # Verify the service was only instantiated once
+        expect(Whatsapp::CsatTemplateService).to have_received(:new).once
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/send_on_whatsapp_service_spec.rb

@@ -0,0 +1,384 @@
+require 'rails_helper'
+
+describe Whatsapp::SendOnWhatsappService do
+  template_params = {
+    name: 'sample_shipping_confirmation',
+    namespace: '23423423_2342423_324234234_2343224',
+    language: 'en_US',
+    category: 'Marketing',
+    processed_params: { 'body' => { '1' => '3' } }
+  }
+
+  describe '#perform' do
+    before do
+      stub_request(:post, 'https://waba.360dialog.io/v1/configs/webhook')
+      stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+    end
+
+    context 'when a valid message' do
+      let(:whatsapp_request) { instance_double(HTTParty::Response) }
+      let!(:whatsapp_channel) { create(:channel_whatsapp, sync_templates: false) }
+
+      let!(:contact_inbox) { create(:contact_inbox, inbox: whatsapp_channel.inbox, source_id: '123456789') }
+      let!(:conversation) { create(:conversation, contact_inbox: contact_inbox, inbox: whatsapp_channel.inbox) }
+      let(:api_key) { 'test_key' }
+      let(:headers) { { 'D360-API-KEY' => api_key, 'Content-Type' => 'application/json' } }
+      let(:template_body) do
+        {
+          to: '123456789',
+          template: {
+            name: 'sample_shipping_confirmation',
+            namespace: '23423423_2342423_324234234_2343224',
+            language: { 'policy': 'deterministic', 'code': 'en_US' },
+            components: [{ 'type': 'body', 'parameters': [{ 'type': 'text', 'text': '3' }] }]
+          },
+          type: 'template'
+        }
+      end
+
+      let(:named_template_body) do
+        {
+          messaging_product: 'whatsapp',
+          recipient_type: 'individual',
+          to: '123456789',
+          type: 'template',
+          template: {
+            name: 'ticket_status_updated',
+            language: { 'policy': 'deterministic', 'code': 'en_US' },
+            components: [{ 'type': 'body',
+                           'parameters': [{ 'type': 'text', parameter_name: 'last_name', 'text': 'Dale' },
+                                          { 'type': 'text', parameter_name: 'ticket_id', 'text': '2332' }] }]
+          }
+        }
+      end
+
+      let(:success_response) { { 'messages' => [{ 'id' => '123456789' }] }.to_json }
+
+      it 'calls channel.send_message when with in 24 hour limit' do
+        # to handle the case of 24 hour window limit.
+        create(:message, message_type: :incoming, content: 'test',
+                         conversation: conversation, account: conversation.account)
+        message = create(:message, message_type: :outgoing, content: 'test',
+                                   conversation: conversation, account: conversation.account)
+
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: { 'to' => '123456789', 'text' => { 'body' => 'test' }, 'type' => 'text' }.to_json
+          )
+          .to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'marks message as failed when template name is blank' do
+        processor = instance_double(Whatsapp::TemplateProcessorService)
+        allow(Whatsapp::TemplateProcessorService).to receive(:new).and_return(processor)
+        allow(processor).to receive(:call).and_return([nil, nil, nil, nil])
+
+        invalid_template_params = {
+          name: '',
+          namespace: 'test_namespace',
+          language: 'en_US',
+          category: 'UTILITY',
+          processed_params: { '1' => 'test' }
+        }
+
+        message = create(:message,
+                         additional_attributes: { template_params: invalid_template_params },
+                         conversation: conversation,
+                         message_type: :outgoing,
+                         account: conversation.account)
+
+        described_class.new(message: message).perform
+
+        expect(message.reload.status).to eq('failed')
+        expect(message.reload.external_error).to eq('Template not found or invalid template name')
+      end
+
+      it 'calls channel.send_template when after 24 hour limit' do
+        message = create(:message, message_type: :outgoing, content: 'Your package has been shipped. It will be delivered in 3 business days.',
+                                   conversation: conversation, additional_attributes: { template_params: template_params },
+                                   account: conversation.account)
+
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: template_body.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'calls channel.send_template if template_params are present' do
+        message = create(:message, additional_attributes: { template_params: template_params },
+                                   content: 'Your package will be delivered in 3 business days.', conversation: conversation, message_type: :outgoing,
+                                   account: conversation.account)
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: template_body.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'calls channel.send_template with named params if template parameter type is NAMED' do
+        whatsapp_cloud_channel = create(:channel_whatsapp, provider: 'whatsapp_cloud', sync_templates: false, validate_provider_config: false)
+        cloud_contact_inbox = create(:contact_inbox, inbox: whatsapp_cloud_channel.inbox, source_id: '123456789')
+        cloud_conversation = create(:conversation, contact_inbox: cloud_contact_inbox, inbox: whatsapp_cloud_channel.inbox)
+
+        named_template_params = {
+          name: 'ticket_status_updated',
+          language: 'en_US',
+          category: 'UTILITY',
+          processed_params: { 'body' => { 'last_name' => 'Dale', 'ticket_id' => '2332' } }
+        }
+
+        stub_request(:post, "https://graph.facebook.com/v13.0/#{whatsapp_cloud_channel.provider_config['phone_number_id']}/messages")
+          .with(
+            :headers => {
+              'Accept' => '*/*',
+              'Accept-Encoding' => 'gzip;q=1.0,deflate;q=0.6,identity;q=0.3',
+              'Content-Type' => 'application/json',
+              'Authorization' => "Bearer #{whatsapp_cloud_channel.provider_config['api_key']}",
+              'User-Agent' => 'Ruby'
+            },
+            :body => named_template_body.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+        message = create(:message,
+                         additional_attributes: { template_params: named_template_params },
+                         content: 'Your package will be delivered in 3 business days.', conversation: cloud_conversation, message_type: :outgoing,
+                         account: cloud_conversation.account)
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'calls channel.send_template when template has regexp characters' do
+        regexp_template_params = build_template_params('customer_yes_no', '2342384942_32423423_23423fdsdaf23', 'ar', {})
+        arabic_content = 'عميلنا العزيز الرجاء الرد على هذه الرسالة بكلمة *نعم* للرد على إستفساركم من قبل خدمة العملاء.'
+        message = create_message_with_template(arabic_content, regexp_template_params)
+        stub_template_request(regexp_template_params, [])
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'handles template with header parameters' do
+        processed_params = {
+          'body' => { '1' => '3' },
+          'header' => { 'media_url' => 'https://example.com/image.jpg', 'media_type' => 'image' }
+        }
+        header_template_params = build_sample_template_params(processed_params)
+        message = create_message_with_template('', header_template_params)
+
+        components = [
+          { type: 'header', parameters: [{ type: 'image', image: { link: 'https://example.com/image.jpg' } }] },
+          { type: 'body', parameters: [{ type: 'text', text: '3' }] }
+        ]
+        stub_sample_template_request(components)
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'handles empty processed_params gracefully' do
+        empty_template_params = {
+          name: 'sample_shipping_confirmation',
+          namespace: '23423423_2342423_324234234_2343224',
+          language: 'en_US',
+          category: 'SHIPPING_UPDATE',
+          processed_params: {}
+        }
+
+        message = create(:message, additional_attributes: { template_params: empty_template_params },
+                                   conversation: conversation, message_type: :outgoing, account: conversation.account)
+
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: {
+              to: '123456789',
+              template: {
+                name: 'sample_shipping_confirmation',
+                namespace: '23423423_2342423_324234234_2343224',
+                language: { 'policy': 'deterministic', 'code': 'en_US' },
+                components: []
+              },
+              type: 'template'
+            }.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'handles template with button parameters' do
+        processed_params = {
+          'body' => { '1' => '3' },
+          'buttons' => [{ 'type' => 'url', 'parameter' => 'https://track.example.com/123' }]
+        }
+        button_template_params = build_sample_template_params(processed_params)
+        message = create_message_with_template('', button_template_params)
+
+        components = [
+          { type: 'body', parameters: [{ type: 'text', text: '3' }] },
+          { type: 'button', sub_type: 'url', index: 0, parameters: [{ type: 'text', text: 'https://track.example.com/123' }] }
+        ]
+        stub_sample_template_request(components)
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'processes template parameters correctly via integration' do
+        processed_params = {
+          'body' => { '1' => '5' },
+          'footer' => { 'text' => 'Thank you' }
+        }
+        complex_template_params = build_sample_template_params(processed_params)
+        message = create_message_with_template('', complex_template_params)
+
+        components = [
+          { type: 'body', parameters: [{ type: 'text', text: '5' }] },
+          { type: 'footer', parameters: [{ type: 'text', text: 'Thank you' }] }
+        ]
+        stub_sample_template_request(components)
+
+        expect { described_class.new(message: message).perform }.not_to raise_error
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'handles edge case with missing template gracefully' do
+        # Test the service behavior when template is not found
+        missing_template_params = {
+          'name' => 'non_existent_template',
+          'namespace' => 'missing_namespace',
+          'language' => 'en_US',
+          'category' => 'UTILITY',
+          'processed_params' => { 'body' => { '1' => 'test' } }
+        }
+
+        service = Whatsapp::TemplateProcessorService.new(
+          channel: whatsapp_channel,
+          template_params: missing_template_params
+        )
+
+        expect { service.call }.not_to raise_error
+        name, namespace, language, processed_params = service.call
+        expect(name).to eq('non_existent_template')
+        expect(namespace).to eq('missing_namespace')
+        expect(language).to eq('en_US')
+        expect(processed_params).to be_nil
+      end
+
+      it 'handles template with blank parameter values correctly' do
+        processed_params = {
+          'body' => { '1' => '', '2' => 'valid_value', '3' => nil },
+          'header' => { 'media_url' => '', 'media_type' => 'image' }
+        }
+        blank_values_template_params = build_sample_template_params(processed_params)
+        message = create_message_with_template('', blank_values_template_params)
+
+        components = [{ type: 'body', parameters: [{ type: 'text', text: 'valid_value' }] }]
+        stub_sample_template_request(components)
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      it 'handles nil template_params gracefully' do
+        # Test service behavior when template_params is completely nil
+        message = create(:message, additional_attributes: {},
+                                   conversation: conversation, message_type: :outgoing)
+
+        # Should send regular message, not template
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: {
+              to: '123456789',
+              text: { body: message.content },
+              type: 'text'
+            }.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+
+        expect { described_class.new(message: message).perform }.not_to raise_error
+      end
+
+      it 'processes template with rich text formatting' do
+        processed_params = { 'body' => { '1' => '*Bold text* and _italic text_' } }
+        rich_text_template_params = build_sample_template_params(processed_params)
+        message = create_message_with_template('', rich_text_template_params)
+
+        components = [{ type: 'body', parameters: [{ type: 'text', text: '*Bold text* and _italic text_' }] }]
+        stub_sample_template_request(components)
+
+        described_class.new(message: message).perform
+        expect(message.reload.source_id).to eq('123456789')
+      end
+
+      private
+
+      def build_template_params(name, namespace, language, processed_params)
+        {
+          name: name,
+          namespace: namespace,
+          language: language,
+          category: 'SHIPPING_UPDATE',
+          processed_params: processed_params
+        }
+      end
+
+      def create_message_with_template(content, template_params)
+        create(:message,
+               message_type: :outgoing,
+               content: content,
+               conversation: conversation,
+               additional_attributes: { template_params: template_params })
+      end
+
+      def stub_template_request(template_params, components)
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: {
+              to: '123456789',
+              template: {
+                name: template_params[:name],
+                namespace: template_params[:namespace],
+                language: { 'policy': 'deterministic', 'code': template_params[:language] },
+                components: components
+              },
+              type: 'template'
+            }.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+      end
+
+      def build_sample_template_params(processed_params)
+        build_template_params('sample_shipping_confirmation', '23423423_2342423_324234234_2343224', 'en_US', processed_params)
+      end
+
+      def stub_sample_template_request(components)
+        stub_request(:post, 'https://waba.360dialog.io/v1/messages')
+          .with(
+            headers: headers,
+            body: {
+              to: '123456789',
+              template: {
+                name: 'sample_shipping_confirmation',
+                namespace: '23423423_2342423_324234234_2343224',
+                language: { 'policy': 'deterministic', 'code': 'en_US' },
+                components: components
+              },
+              type: 'template'
+            }.to_json
+          ).to_return(status: 200, body: success_response, headers: { 'content-type' => 'application/json' })
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/template_parameter_converter_service_spec.rb

@@ -0,0 +1,261 @@
+require 'rails_helper'
+
+describe Whatsapp::TemplateParameterConverterService do
+  let(:template) do
+    {
+      'name' => 'test_template',
+      'language' => 'en',
+      'components' => [
+        {
+          'type' => 'BODY',
+          'text' => 'Hello {{1}}, your order {{2}} is ready!'
+        }
+      ]
+    }
+  end
+
+  let(:media_template) do
+    {
+      'name' => 'media_template',
+      'language' => 'en',
+      'components' => [
+        {
+          'type' => 'HEADER',
+          'format' => 'IMAGE'
+        },
+        {
+          'type' => 'BODY',
+          'text' => 'Check out {{1}}!'
+        }
+      ]
+    }
+  end
+
+  let(:button_template) do
+    {
+      'name' => 'button_template',
+      'language' => 'en',
+      'components' => [
+        {
+          'type' => 'BODY',
+          'text' => 'Visit our website!'
+        },
+        {
+          'type' => 'BUTTONS',
+          'buttons' => [
+            {
+              'type' => 'URL',
+              'url' => 'https://example.com/{{1}}'
+            },
+            {
+              'type' => 'COPY_CODE'
+            }
+          ]
+        }
+      ]
+    }
+  end
+
+  describe '#normalize_to_enhanced' do
+    context 'when already enhanced format' do
+      let(:enhanced_params) do
+        {
+          'processed_params' => {
+            'body' => { '1' => 'John', '2' => 'Order123' }
+          }
+        }
+      end
+
+      it 'returns unchanged' do
+        converter = described_class.new(enhanced_params, template)
+        result = converter.normalize_to_enhanced
+        expect(result).to eq(enhanced_params)
+      end
+    end
+
+    context 'when legacy array format' do
+      let(:legacy_array_params) do
+        {
+          'processed_params' => %w[John Order123]
+        }
+      end
+
+      it 'converts to enhanced format' do
+        converter = described_class.new(legacy_array_params, template)
+        result = converter.normalize_to_enhanced
+
+        expect(result['processed_params']).to eq({
+                                                   'body' => { '1' => 'John', '2' => 'Order123' }
+                                                 })
+        expect(result['format_version']).to eq('legacy')
+      end
+    end
+
+    context 'when legacy flat hash format' do
+      let(:legacy_hash_params) do
+        {
+          'processed_params' => { '1' => 'John', '2' => 'Order123' }
+        }
+      end
+
+      it 'converts to enhanced format' do
+        converter = described_class.new(legacy_hash_params, template)
+        result = converter.normalize_to_enhanced
+
+        expect(result['processed_params']).to eq({
+                                                   'body' => { '1' => 'John', '2' => 'Order123' }
+                                                 })
+        expect(result['format_version']).to eq('legacy')
+      end
+    end
+
+    context 'when legacy hash with all body parameters' do
+      let(:legacy_hash_params) do
+        {
+          'processed_params' => {
+            '1' => 'Product',
+            'customer_name' => 'John'
+          }
+        }
+      end
+
+      it 'converts to enhanced format with body only' do
+        converter = described_class.new(legacy_hash_params, media_template)
+        result = converter.normalize_to_enhanced
+
+        expect(result['processed_params']).to eq({
+                                                   'body' => {
+                                                     '1' => 'Product',
+                                                     'customer_name' => 'John'
+                                                   }
+                                                 })
+        expect(result['format_version']).to eq('legacy')
+      end
+    end
+
+    context 'when processed_params is nil (parameter-less templates)' do
+      let(:nil_params) do
+        {
+          'processed_params' => nil
+        }
+      end
+
+      let(:parameterless_template) do
+        {
+          'name' => 'test_no_params_template',
+          'language' => 'en',
+          'parameter_format' => 'POSITIONAL',
+          'id' => '9876543210987654',
+          'status' => 'APPROVED',
+          'category' => 'UTILITY',
+          'previous_category' => 'MARKETING',
+          'sub_category' => 'CUSTOM',
+          'components' => [
+            {
+              'type' => 'BODY',
+              'text' => 'Thank you for contacting us! Your request has been processed successfully. Have a great day! 🙂'
+            }
+          ]
+        }
+      end
+
+      it 'converts nil to empty enhanced format' do
+        converter = described_class.new(nil_params, parameterless_template)
+        result = converter.normalize_to_enhanced
+
+        expect(result['processed_params']).to eq({})
+        expect(result['format_version']).to eq('legacy')
+      end
+
+      it 'does not raise ArgumentError for nil processed_params' do
+        expect do
+          converter = described_class.new(nil_params, parameterless_template)
+          converter.normalize_to_enhanced
+        end.not_to raise_error
+      end
+    end
+
+    context 'when invalid format' do
+      let(:invalid_params) do
+        {
+          'processed_params' => 'invalid_string'
+        }
+      end
+
+      it 'raises ArgumentError' do
+        expect do
+          converter = described_class.new(invalid_params, template)
+          converter.normalize_to_enhanced
+        end.to raise_error(ArgumentError, /Unknown legacy format/)
+      end
+    end
+  end
+
+  describe '#enhanced_format?' do
+    it 'returns true for valid enhanced format' do
+      enhanced = { 'body' => { '1' => 'test' } }
+      converter = described_class.new({}, template)
+      expect(converter.send(:enhanced_format?, enhanced)).to be true
+    end
+
+    it 'returns false for array' do
+      converter = described_class.new({}, template)
+      expect(converter.send(:enhanced_format?, ['test'])).to be false
+    end
+
+    it 'returns false for flat hash' do
+      converter = described_class.new({}, template)
+      expect(converter.send(:enhanced_format?, { '1' => 'test' })).to be false
+    end
+
+    it 'returns false for invalid structure' do
+      invalid = { 'body' => 'not_a_hash' }
+      converter = described_class.new({}, template)
+      expect(converter.send(:enhanced_format?, invalid)).to be false
+    end
+  end
+
+  describe 'simplified conversion methods' do
+    describe '#convert_legacy_to_enhanced' do
+      it 'handles nil processed_params without raising error' do
+        converter = described_class.new({}, template)
+        result = converter.send(:convert_legacy_to_enhanced, nil, template)
+        expect(result).to eq({})
+      end
+
+      it 'returns empty hash for parameter-less templates' do
+        parameterless_template = {
+          'name' => 'no_params_template',
+          'language' => 'en',
+          'components' => [{ 'type' => 'BODY', 'text' => 'Hello World!' }]
+        }
+
+        converter = described_class.new({}, parameterless_template)
+        result = converter.send(:convert_legacy_to_enhanced, nil, parameterless_template)
+        expect(result).to eq({})
+      end
+    end
+
+    describe '#convert_array_to_body_params' do
+      it 'converts empty array' do
+        converter = described_class.new({}, template)
+        result = converter.send(:convert_array_to_body_params, [])
+        expect(result).to eq({})
+      end
+
+      it 'converts array to numbered body parameters' do
+        converter = described_class.new({}, template)
+        result = converter.send(:convert_array_to_body_params, %w[John Order123])
+        expect(result).to eq({ '1' => 'John', '2' => 'Order123' })
+      end
+    end
+
+    describe '#convert_hash_to_body_params' do
+      it 'converts hash to body parameters' do
+        converter = described_class.new({}, template)
+        result = converter.send(:convert_hash_to_body_params, { 'name' => 'John', 'order' => '123' })
+        expect(result).to eq({ 'name' => 'John', 'order' => '123' })
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/token_exchange_service_spec.rb

@@ -0,0 +1,45 @@
+require 'rails_helper'
+
+describe Whatsapp::TokenExchangeService do
+  let(:code) { 'test_authorization_code' }
+  let(:service) { described_class.new(code) }
+  let(:api_client) { instance_double(Whatsapp::FacebookApiClient) }
+
+  before do
+    allow(Whatsapp::FacebookApiClient).to receive(:new).and_return(api_client)
+  end
+
+  describe '#perform' do
+    context 'when code is valid' do
+      let(:token_response) { { 'access_token' => 'new_access_token' } }
+
+      before do
+        allow(api_client).to receive(:exchange_code_for_token).with(code).and_return(token_response)
+      end
+
+      it 'returns the access token' do
+        expect(service.perform).to eq('new_access_token')
+      end
+    end
+
+    context 'when code is blank' do
+      let(:service) { described_class.new('') }
+
+      it 'raises ArgumentError' do
+        expect { service.perform }.to raise_error(ArgumentError, 'Authorization code is required')
+      end
+    end
+
+    context 'when response has no access token' do
+      let(:token_response) { { 'error' => 'Invalid code' } }
+
+      before do
+        allow(api_client).to receive(:exchange_code_for_token).with(code).and_return(token_response)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/No access token in response/)
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/token_validation_service_spec.rb

@@ -0,0 +1,99 @@
+require 'rails_helper'
+
+describe Whatsapp::TokenValidationService do
+  let(:access_token) { 'test_access_token' }
+  let(:waba_id) { 'test_waba_id' }
+  let(:service) { described_class.new(access_token, waba_id) }
+  let(:api_client) { instance_double(Whatsapp::FacebookApiClient) }
+
+  before do
+    allow(Whatsapp::FacebookApiClient).to receive(:new).with(access_token).and_return(api_client)
+  end
+
+  describe '#perform' do
+    context 'when token has access to WABA' do
+      let(:debug_response) do
+        {
+          'data' => {
+            'granular_scopes' => [
+              {
+                'scope' => 'whatsapp_business_management',
+                'target_ids' => [waba_id, 'another_waba_id']
+              }
+            ]
+          }
+        }
+      end
+
+      before do
+        allow(api_client).to receive(:debug_token).with(access_token).and_return(debug_response)
+      end
+
+      it 'validates successfully' do
+        expect { service.perform }.not_to raise_error
+      end
+    end
+
+    context 'when token does not have access to WABA' do
+      let(:debug_response) do
+        {
+          'data' => {
+            'granular_scopes' => [
+              {
+                'scope' => 'whatsapp_business_management',
+                'target_ids' => ['different_waba_id']
+              }
+            ]
+          }
+        }
+      end
+
+      before do
+        allow(api_client).to receive(:debug_token).with(access_token).and_return(debug_response)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error(/Token does not have access to WABA/)
+      end
+    end
+
+    context 'when no WABA scope is found' do
+      let(:debug_response) do
+        {
+          'data' => {
+            'granular_scopes' => [
+              {
+                'scope' => 'some_other_scope',
+                'target_ids' => ['some_id']
+              }
+            ]
+          }
+        }
+      end
+
+      before do
+        allow(api_client).to receive(:debug_token).with(access_token).and_return(debug_response)
+      end
+
+      it 'raises an error' do
+        expect { service.perform }.to raise_error('No WABA scope found in token')
+      end
+    end
+
+    context 'when access_token is blank' do
+      let(:access_token) { '' }
+
+      it 'raises ArgumentError' do
+        expect { service.perform }.to raise_error(ArgumentError, 'Access token is required')
+      end
+    end
+
+    context 'when waba_id is blank' do
+      let(:waba_id) { '' }
+
+      it 'raises ArgumentError' do
+        expect { service.perform }.to raise_error(ArgumentError, 'WABA ID is required')
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/webhook_setup_service_spec.rb

@@ -0,0 +1,328 @@
+require 'rails_helper'
+
+describe Whatsapp::WebhookSetupService do
+  let(:channel) do
+    create(:channel_whatsapp,
+           phone_number: '+1234567890',
+           provider_config: {
+             'phone_number_id' => '123456789',
+             'webhook_verify_token' => 'test_verify_token',
+             'source' => 'embedded_signup'
+           },
+           provider: 'whatsapp_cloud',
+           sync_templates: false,
+           validate_provider_config: false)
+  end
+  let(:waba_id) { 'test_waba_id' }
+  let(:access_token) { 'test_access_token' }
+  let(:service) { described_class.new(channel, waba_id, access_token) }
+  let(:api_client) { instance_double(Whatsapp::FacebookApiClient) }
+  let(:health_service) { instance_double(Whatsapp::HealthService) }
+
+  before do
+    # Stub webhook teardown to prevent HTTP calls during cleanup
+    stub_request(:delete, /graph.facebook.com/).to_return(status: 200, body: '{}', headers: {})
+
+    # Clean up any existing channels to avoid phone number conflicts
+    Channel::Whatsapp.destroy_all
+    allow(Whatsapp::FacebookApiClient).to receive(:new).and_return(api_client)
+    allow(Whatsapp::HealthService).to receive(:new).and_return(health_service)
+
+    # Default stubs for phone_number_verified? and health service
+    allow(api_client).to receive(:phone_number_verified?).and_return(false)
+    allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                        platform_type: 'APPLICABLE',
+                                                                        throughput: { level: 'APPLICABLE' }
+                                                                      })
+  end
+
+  describe '#perform' do
+    context 'when phone number is NOT verified (should register)' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number).with('123456789', 223_456)
+        allow(api_client).to receive(:subscribe_waba_webhook)
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'registers the phone number and sets up webhook' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number).with('123456789', 223_456)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'test_verify_token')
+          service.perform
+        end
+      end
+    end
+
+    context 'when phone number IS verified AND fully provisioned (should NOT register)' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'APPLICABLE',
+                                                                            throughput: { level: 'APPLICABLE' }
+                                                                          })
+        allow(api_client).to receive(:subscribe_waba_webhook)
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
+      end
+
+      it 'does NOT register phone, but sets up webhook' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).not_to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'test_verify_token')
+          service.perform
+        end
+      end
+    end
+
+    context 'when phone number IS verified BUT needs registration (pending provisioning)' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'NOT_APPLICABLE',
+                                                                            throughput: { level: 'APPLICABLE' }
+                                                                          })
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number).with('123456789', 223_456)
+        allow(api_client).to receive(:subscribe_waba_webhook)
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'registers the phone number due to pending provisioning state' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number).with('123456789', 223_456)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'test_verify_token')
+          service.perform
+        end
+      end
+    end
+
+    context 'when phone number needs registration due to throughput level' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'APPLICABLE',
+                                                                            throughput: { level: 'NOT_APPLICABLE' }
+                                                                          })
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number).with('123456789', 223_456)
+        allow(api_client).to receive(:subscribe_waba_webhook)
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'registers the phone number due to throughput not applicable' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number).with('123456789', 223_456)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'test_verify_token')
+          service.perform
+        end
+      end
+    end
+
+    context 'when phone_number_verified? raises error' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_raise('API down')
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'APPLICABLE',
+                                                                            throughput: { level: 'APPLICABLE' }
+                                                                          })
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number)
+        allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'tries to register phone (due to verification error) and proceeds with webhook setup' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+          expect { service.perform }.not_to raise_error
+        end
+      end
+    end
+
+    context 'when health service raises error' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(health_service).to receive(:fetch_health_status).and_raise('Health API down')
+        allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
+      end
+
+      it 'does not register phone (conservative approach) and proceeds with webhook setup' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).not_to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+          expect { service.perform }.not_to raise_error
+        end
+      end
+    end
+
+    context 'when phone registration fails (not blocking)' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number).and_raise('Registration failed')
+        allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'continues with webhook setup even if registration fails' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+          expect { service.perform }.not_to raise_error
+        end
+      end
+    end
+
+    context 'when webhook setup fails (should raise)' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number)
+        allow(api_client).to receive(:subscribe_waba_webhook).and_raise('Webhook failed')
+      end
+
+      it 'raises an error' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+          expect { service.perform }.to raise_error(/Webhook setup failed/)
+        end
+      end
+    end
+
+    context 'when required parameters are missing' do
+      it 'raises error when channel is nil' do
+        service_invalid = described_class.new(nil, waba_id, access_token)
+        expect { service_invalid.perform }.to raise_error(ArgumentError, 'Channel is required')
+      end
+
+      it 'raises error when waba_id is blank' do
+        service_invalid = described_class.new(channel, '', access_token)
+        expect { service_invalid.perform }.to raise_error(ArgumentError, 'WABA ID is required')
+      end
+
+      it 'raises error when access_token is blank' do
+        service_invalid = described_class.new(channel, waba_id, '')
+        expect { service_invalid.perform }.to raise_error(ArgumentError, 'Access token is required')
+      end
+    end
+
+    context 'when PIN already exists' do
+      before do
+        channel.provider_config['verification_pin'] = 123_456
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
+        allow(api_client).to receive(:register_phone_number)
+        allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'reuses existing PIN' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number).with('123456789', 123_456)
+          expect(SecureRandom).not_to receive(:random_number)
+          service.perform
+        end
+      end
+    end
+
+    context 'when webhook setup fails and should trigger reauthorization' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(api_client).to receive(:subscribe_waba_webhook).and_raise('Invalid access token')
+      end
+
+      it 'raises error with webhook setup failure message' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect { service.perform }.to raise_error(/Webhook setup failed: Invalid access token/)
+        end
+      end
+
+      it 'logs the webhook setup failure' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(Rails.logger).to receive(:error).with('[WHATSAPP] Webhook setup failed: Invalid access token')
+          expect { service.perform }.to raise_error(/Webhook setup failed/)
+        end
+      end
+    end
+
+    context 'when used during reauthorization flow' do
+      let(:existing_channel) do
+        create(:channel_whatsapp,
+               phone_number: '+1234567890',
+               provider_config: {
+                 'phone_number_id' => '123456789',
+                 'webhook_verify_token' => 'existing_verify_token',
+                 'business_id' => 'existing_business_id',
+                 'waba_id' => 'existing_waba_id',
+                 'source' => 'embedded_signup'
+               },
+               provider: 'whatsapp_cloud',
+               sync_templates: false,
+               validate_provider_config: false)
+      end
+      let(:new_access_token) { 'new_access_token' }
+      let(:service_reauth) { described_class.new(existing_channel, waba_id, new_access_token) }
+
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'APPLICABLE',
+                                                                            throughput: { level: 'APPLICABLE' }
+                                                                          })
+        allow(api_client).to receive(:subscribe_waba_webhook)
+          .with(waba_id, anything, 'existing_verify_token').and_return({ 'success' => true })
+      end
+
+      it 'successfully reauthorizes with new access token' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).not_to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'existing_verify_token')
+          service_reauth.perform
+        end
+      end
+
+      it 'uses the existing webhook verify token during reauthorization' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, anything, 'existing_verify_token')
+          service_reauth.perform
+        end
+      end
+    end
+
+    context 'when webhook setup is successful in creation flow' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
+        allow(health_service).to receive(:fetch_health_status).and_return({
+                                                                            platform_type: 'APPLICABLE',
+                                                                            throughput: { level: 'APPLICABLE' }
+                                                                          })
+        allow(api_client).to receive(:subscribe_waba_webhook)
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
+      end
+
+      it 'completes successfully without errors' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect { service.perform }.not_to raise_error
+        end
+      end
+
+      it 'does not log any errors' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(Rails.logger).not_to receive(:error)
+          service.perform
+        end
+      end
+    end
+  end
+end

research/chatwoot/spec/services/whatsapp/webhook_teardown_service_spec.rb

@@ -0,0 +1,84 @@
+require 'rails_helper'
+
+RSpec.describe Whatsapp::WebhookTeardownService do
+  describe '#perform' do
+    let(:channel) { create(:channel_whatsapp, validate_provider_config: false, sync_templates: false) }
+    let(:service) { described_class.new(channel) }
+
+    context 'when channel is whatsapp_cloud with embedded_signup' do
+      before do
+        # Stub webhook setup to prevent HTTP calls during channel update
+        allow(channel).to receive(:setup_webhooks).and_return(true)
+
+        channel.update!(
+          provider: 'whatsapp_cloud',
+          provider_config: {
+            'source' => 'embedded_signup',
+            'business_account_id' => 'test_waba_id',
+            'api_key' => 'test_api_key'
+          }
+        )
+      end
+
+      it 'calls unsubscribe_waba_webhook on Facebook API client' do
+        api_client = instance_double(Whatsapp::FacebookApiClient)
+        allow(Whatsapp::FacebookApiClient).to receive(:new).with('test_api_key').and_return(api_client)
+        allow(api_client).to receive(:unsubscribe_waba_webhook).with('test_waba_id')
+
+        service.perform
+
+        expect(api_client).to have_received(:unsubscribe_waba_webhook).with('test_waba_id')
+      end
+
+      it 'handles errors gracefully without raising' do
+        api_client = instance_double(Whatsapp::FacebookApiClient)
+        allow(Whatsapp::FacebookApiClient).to receive(:new).and_return(api_client)
+        allow(api_client).to receive(:unsubscribe_waba_webhook).and_raise(StandardError, 'API Error')
+
+        expect { service.perform }.not_to raise_error
+      end
+    end
+
+    context 'when channel is not whatsapp_cloud' do
+      before do
+        channel.update!(provider: 'default')
+      end
+
+      it 'does not attempt to unsubscribe webhook' do
+        expect(Whatsapp::FacebookApiClient).not_to receive(:new)
+
+        service.perform
+      end
+    end
+
+    context 'when channel is whatsapp_cloud but not embedded_signup' do
+      before do
+        channel.update!(
+          provider: 'whatsapp_cloud',
+          provider_config: { 'source' => 'manual' }
+        )
+      end
+
+      it 'does not attempt to unsubscribe webhook' do
+        expect(Whatsapp::FacebookApiClient).not_to receive(:new)
+
+        service.perform
+      end
+    end
+
+    context 'when required config is missing' do
+      before do
+        channel.update!(
+          provider: 'whatsapp_cloud',
+          provider_config: { 'source' => 'embedded_signup' }
+        )
+      end
+
+      it 'does not attempt to unsubscribe webhook' do
+        expect(Whatsapp::FacebookApiClient).not_to receive(:new)
+
+        service.perform
+      end
+    end
+  end
+end