fix(whatsapp): match Brazilian ninth-digit phone variants on inbound consolidation (#319)

A contact saved under the wrong ninth-digit variant (e.g. outbound
on_whatsapp normalization was skipped due to a transient provider error)
no longer spawns a duplicate contact and conversation when the reply
arrives with the canonical number. ContactInboxConsolidationService now
matches contact_inboxes and contacts across Brazil/Argentina "9"
variants, preferring exact matches, and self-heals duplicates created
before the fix by merging them on the next inbound message.

Author: gabrieljablonski

app/services/whatsapp/contact_inbox_consolidation_service.rb

@@ -5,6 +5,11 @@
 # 3. If the conversation is deleted/resolved and a new one is created, a new contact_inbox
 #    with source_id = phone is created (since the existing one has LID)
 # 4. This service consolidates these duplicates when a message arrives
+#
+# Phone lookups are ninth-digit-variant aware (Brazil/Argentina): a contact saved
+# with the "wrong" variant (e.g. outbound on_whatsapp normalization was skipped)
+# still matches the canonical number the webhook delivers, instead of spawning a
+# duplicate contact and conversation. Exact matches always win over variants.
 class Whatsapp::ContactInboxConsolidationService
   def initialize(inbox:, phone:, lid:, identifier:)
     @inbox = inbox
@@ -38,7 +43,8 @@ def perform # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComp
   private
 
   def find_phone_contact_inbox
-    @inbox.contact_inboxes.find_by(source_id: @phone)
+    @inbox.contact_inboxes.find_by(source_id: @phone) ||
+      (@inbox.contact_inboxes.find_by(source_id: alternate_phone_variants) if alternate_phone_variants.any?)
   end
 
   def find_lid_contact_inbox
@@ -100,7 +106,7 @@ def migrate_phone_to_lid(phone_contact_inbox)
   # Find contact by phone number and update their contact_inbox source_id to LID
   # This handles the case where contact_inbox has a different source_id (e.g., old format)
   def update_existing_contact_inbox_by_phone
-    existing_contact = @inbox.account.contacts.find_by(phone_number: "+#{@phone}")
+    existing_contact = find_contact_by_phone_variants
     return unless existing_contact
 
     existing_contact_inbox = existing_contact.contact_inboxes.find_by(inbox_id: @inbox.id)
@@ -160,6 +166,22 @@ def adopt_lid_contact_inbox(phone_contact, lid_ci)
     end
   end
 
+  def find_contact_by_phone_variants
+    contacts = @inbox.account.contacts
+    contacts.find_by(phone_number: "+#{@phone}") ||
+      (contacts.find_by(phone_number: alternate_phone_variants.map { |variant| "+#{variant}" }) if alternate_phone_variants.any?)
+  end
+
+  # The other ninth-digit forms @phone may be stored under (Brazil/Argentina).
+  def alternate_phone_variants
+    @alternate_phone_variants ||= begin
+      normalizer = Whatsapp::PhoneNumberNormalizationService::NORMALIZERS
+                   .map(&:new)
+                   .find { |candidate| candidate.handles_country?(@phone) }
+      normalizer ? normalizer.variants(@phone) - [@phone] : []
+    end
+  end
+
   # Resolve identifier conflict by transferring the identifier to the phone-based contact.
   def transfer_identifier_to(target_contact)
     return if target_contact.identifier == @identifier

app/services/whatsapp/phone_normalizers/argentina_phone_normalizer.rb

@@ -10,6 +10,14 @@ def normalize(waid)
     waid.sub(/^549/, '54')
   end
 
+  # An Argentinian mobile number may appear with or without the "9" after the
+  # country code, so both forms are variants of the same line.
+  def variants(waid)
+    return [waid] unless handles_country?(waid)
+
+    [waid, waid.start_with?('549') ? waid.sub(/^549/, '54') : "549#{waid[2..]}"].uniq
+  end
+
   private
 
   def country_code_pattern

app/services/whatsapp/phone_normalizers/base_phone_normalizer.rb

@@ -11,6 +11,12 @@ def normalize(waid)
     raise NotImplementedError, 'Subclasses must implement #normalize'
   end
 
+  # All forms the number may appear as on WhatsApp (including itself).
+  # Country normalizers override this when numbers have known variants.
+  def variants(waid)
+    [waid]
+  end
+
   private
 
   def country_code_pattern

app/services/whatsapp/phone_normalizers/brazil_phone_normalizer.rb

@@ -18,6 +18,20 @@ def normalize(waid)
     normalized_number
   end
 
+  # A Brazilian mobile number may be registered on WhatsApp with or without the
+  # ninth digit, so both forms are variants of the same line.
+  def variants(waid)
+    return [waid] unless handles_country?(waid)
+
+    ddd = waid[COUNTRY_CODE_LENGTH, DDD_LENGTH]
+    number = waid[(COUNTRY_CODE_LENGTH + DDD_LENGTH)..]
+
+    candidates = [waid]
+    candidates << "55#{ddd}9#{number}" if number.length == 8
+    candidates << "55#{ddd}#{number[1..]}" if number.length == 9 && number.start_with?('9')
+    candidates
+  end
+
   private
 
   def country_code_pattern

spec/services/whatsapp/contact_inbox_consolidation_service_spec.rb

@@ -272,5 +272,93 @@
         end
       end
     end
+
+    context 'when the stored phone carries the Brazilian ninth digit and the webhook delivers the canonical number without it' do
+      let(:phone) { '551112345678' }
+      let(:stored_phone) { '5511912345678' }
+
+      context 'when a phone-based contact_inbox exists under the other variant' do
+        let!(:contact) { create(:contact, account: inbox.account, phone_number: "+#{stored_phone}") }
+        let!(:phone_contact_inbox) { create(:contact_inbox, inbox: inbox, contact: contact, source_id: stored_phone) }
+
+        it 'migrates the contact_inbox to lid and aligns the phone to the canonical number' do
+          service = described_class.new(inbox: inbox, phone: phone, lid: lid, identifier: identifier)
+
+          expect { service.perform }.not_to change(ContactInbox, :count)
+
+          expect(phone_contact_inbox.reload.source_id).to eq(lid)
+          expect(contact.reload.identifier).to eq(identifier)
+          expect(contact.phone_number).to eq("+#{phone}")
+        end
+
+        it 'prefers an exact source_id match over a variant' do
+          exact_contact = create(:contact, account: inbox.account, phone_number: "+#{phone}")
+          exact_contact_inbox = create(:contact_inbox, inbox: inbox, contact: exact_contact, source_id: phone)
+
+          described_class.new(inbox: inbox, phone: phone, lid: lid, identifier: identifier).perform
+
+          expect(exact_contact_inbox.reload.source_id).to eq(lid)
+          expect(phone_contact_inbox.reload.source_id).to eq(stored_phone)
+        end
+
+        it 'merges a duplicate lid contact created by a previous reply back into the variant phone contact' do
+          lid_contact = create(:contact, account: inbox.account, phone_number: "+#{phone}", identifier: identifier, name: lid)
+          lid_contact_inbox = create(:contact_inbox, inbox: inbox, contact: lid_contact, source_id: lid)
+          lid_conversation = create(:conversation, inbox: inbox, contact: lid_contact, contact_inbox: lid_contact_inbox)
+
+          described_class.new(inbox: inbox, phone: phone, lid: lid, identifier: identifier).perform
+
+          expect(ContactInbox.exists?(lid_contact_inbox.id)).to be(false)
+          expect(Contact.exists?(lid_contact.id)).to be(false)
+          expect(phone_contact_inbox.reload.source_id).to eq(lid)
+          expect(contact.reload.identifier).to eq(identifier)
+          expect(contact.phone_number).to eq("+#{phone}")
+          expect(lid_conversation.reload.contact_id).to eq(contact.id)
+          expect(lid_conversation.contact_inbox_id).to eq(phone_contact_inbox.id)
+        end
+      end
+
+      context 'when the contact exists under the other variant without a phone-based contact_inbox' do
+        let!(:contact) { create(:contact, account: inbox.account, phone_number: "+#{stored_phone}") }
+        let!(:old_contact_inbox) { create(:contact_inbox, inbox: inbox, contact: contact, source_id: '999999999') }
+
+        it 'updates the existing contact_inbox source_id to lid' do
+          described_class.new(inbox: inbox, phone: phone, lid: lid, identifier: identifier).perform
+
+          expect(old_contact_inbox.reload.source_id).to eq(lid)
+          expect(contact.reload.identifier).to eq(identifier)
+        end
+      end
+    end
+
+    context 'when the stored phone misses the Brazilian ninth digit and the webhook delivers it' do
+      let(:phone) { '5511912345678' }
+      let(:stored_phone) { '551112345678' }
+
+      let!(:contact) { create(:contact, account: inbox.account, phone_number: "+#{stored_phone}") }
+      let!(:phone_contact_inbox) { create(:contact_inbox, inbox: inbox, contact: contact, source_id: stored_phone) }
+
+      it 'migrates the contact_inbox to lid and aligns the phone to the canonical number' do
+        described_class.new(inbox: inbox, phone: phone, lid: lid, identifier: identifier).perform
+
+        expect(phone_contact_inbox.reload.source_id).to eq(lid)
+        expect(contact.reload.phone_number).to eq("+#{phone}")
+      end
+    end
+
+    context 'when the stored phone uses a different Argentinian "9" variant' do
+      let(:phone) { '541112345678' }
+      let(:stored_phone) { '5491112345678' }
+
+      let!(:contact) { create(:contact, account: inbox.account, phone_number: "+#{stored_phone}") }
+      let!(:phone_contact_inbox) { create(:contact_inbox, inbox: inbox, contact: contact, source_id: stored_phone) }
+
+      it 'migrates the contact_inbox to lid and aligns the phone to the canonical number' do
+        described_class.new(inbox: inbox, phone: phone, lid: lid, identifier: identifier).perform
+
+        expect(phone_contact_inbox.reload.source_id).to eq(lid)
+        expect(contact.reload.phone_number).to eq("+#{phone}")
+      end
+    end
   end
 end

spec/services/whatsapp/incoming_message_baileys_service_spec.rb

@@ -998,6 +998,25 @@
           expect(contact.phone_number).to eq('+5511912345678')
         end
 
+        it 'reuses a contact saved with the Brazilian ninth digit when the reply arrives without it' do
+          # Regression: the agent saved the number with the ninth digit and outbound
+          # normalization was skipped; the reply delivers the canonical number without
+          # it and must not spawn a duplicate contact in a new conversation.
+          raw_message[:key][:remoteJidAlt] = '551112345678@s.whatsapp.net'
+          contact = create(:contact, account: inbox.account, phone_number: '+5511912345678', identifier: nil)
+          contact_inbox = create(:contact_inbox, inbox: inbox, contact: contact, source_id: '5511912345678')
+          conversation = create(:conversation, inbox: inbox, contact: contact, contact_inbox: contact_inbox)
+
+          expect do
+            described_class.new(inbox: inbox, params: params).perform
+          end.not_to change(Contact, :count)
+
+          expect(contact_inbox.reload.source_id).to eq('12345678')
+          expect(contact.reload.identifier).to eq('12345678@lid')
+          expect(contact.phone_number).to eq('+551112345678')
+          expect(conversation.reload.messages.last.content).to eq('Hello from Baileys')
+        end
+
         it 'does not update contact_inbox if source_id is already LID' do
           contact = create(:contact, account: inbox.account, phone_number: '+5511912345678', identifier: '12345678@lid')
           contact_inbox = create(:contact_inbox, inbox: inbox, contact: contact, source_id: '12345678')