fix(chatwoot): handle missing remoteJidAlt for LID contacts without crashing

[abdulsametkarakayali]

Problem

When a WhatsApp contact sends messages with addressingMode: 'lid' but remoteJidAlt is missing, Chatwoot createConversation can still drop the message.

develop already has resolveLidToPhone / saveLidMapping and safer splits. The remaining gap: if resolveLidToPhone fails and remoteJidAlt is absent, phoneNumber stays undefined and conversation creation returns null (Contact not created or found). findContactByIdentifier also called client.get, which throws t.get is not a function.

Fix

• Fall back to remoteJid (the LID itself) when remoteJidAlt is absent so conversation creation can proceed.
• Skip Chatwoot phone_number for @lid identifiers (Sourcery).
• Skip phone-number contact mapping when this is a LID fallback (isLid && !remoteJidAlt) so we do not overwrite an unrelated phone contact (Sourcery).
• Search LID-fallback contacts by identifier, not a fake phone number.
• Replace client.get in findContactByIdentifier with contacts.search + contacts/filter.
• Keep downstream .split() calls optional-chained and wrap LID mapping in try/catch.

Notes

Replaces #2718, which targeted main. This branch is based on current develop.

Related: #1872, #2324.

Summary by Sourcery

Handle unresolved WhatsApp LID contacts safely so messages can continue creating Chatwoot conversations without corrupting phone contact mappings.

Bug Fixes:

• Prevent Chatwoot conversation creation from failing when LID contacts lack a remote phone identifier.
• Avoid persisting unresolved LID values as fake phone numbers or overwriting unrelated phone contacts.
• Improve contact lookup reliability for LID identifiers using supported search and filtering APIs.

Enhancements:

• Harden contact and participant handling against missing JIDs and lookup failures.

[sourcery-ai]

Reviewer's Guide

Updates Chatwoot conversation handling so unresolved WhatsApp LID contacts can be created using the LID as an identifier without persisting fake phone numbers, while making contact searches, mapping, and downstream JID parsing resilient to missing data and API failures.

Sequence diagram for unresolved LID conversation creation

sequenceDiagram
    participant WA as WhatsApp
    participant CW as ChatwootService
    participant Search as Chatwoot contact search
    participant C as Chatwoot conversation creation

    WA->>CW: createConversation(remoteJid, remoteJidAlt?)
    CW->>CW: resolveLidToPhone()
    alt phone resolution succeeds
        CW->>CW: findContact(phoneNumber)
    else unresolved LID or missing remoteJidAlt
        CW->>CW: phoneNumber = remoteJid
        CW->>Search: findContactByIdentifier(remoteJid)
        Search->>Search: contacts.search(q)
        Search->>Search: POST contacts/filter
        Search-->>CW: matching LID contact or null
    end
    CW->>C: create/update conversation using LID identifier
    C-->>CW: conversation result

Loading

Flow diagram for safe LID contact mapping

flowchart TD
    A[Receive LID message] --> B{LID resolved to phone?}
    B -->|Yes| C[Update phone contact mapping]
    B -->|No| D[Fallback phoneNumber to remoteJid]
    D --> E[Skip phone_number for @lid]
    E --> F[Skip phone contact mapping]
    F --> G[Search contact by identifier]
    C --> H[Create or update conversation]
    G --> H
    H --> I[Optional JID parsing prevents missing-data crash]

Loading

File-Level Changes

Change	Details	Files
Preserve unresolved LID identifiers as conversation/contact identifiers instead of treating them as phone numbers.	Fall back to remoteJid when LID resolution and remoteJidAlt are unavailable. Omit Chatwoot phone_number for @lid identifiers. Search fallback contacts by their identifier rather than a derived phone number. Prevent fallback processing from overwriting or mapping unrelated phone contacts.	src/api/integrations/chatbot/chatwoot/services/chatwoot.service.ts
Make contact lookup and conversation creation resilient to API, mapping, and missing-JID failures.	Replace the invalid client.get lookup with contacts.search and a contacts/filter request. Handle alternate Chatwoot response payload shapes and log lookup failures. Wrap LID contact mapping in try/catch and make JID split operations optional. Use participant fallbacks and guard profile/contact lookups when participant identifiers are absent.	src/api/integrations/chatbot/chatwoot/services/chatwoot.service.ts

Possibly linked issues

• #enhancement: The PR directly implements the issue’s primary recommendation by safely falling back when remoteJidAlt is missing.
• #META: The PR directly fixes a Chatwoot symptom covered by the umbrella issue: unresolved @lid identifiers without alternate JIDs.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Needs a human reviewer. If the LID fallback or revised contact lookup is wrong, Chatwoot could create or update a contact with an incorrect identifier, and the resulting persisted contact or conversation data would remain after reverting. Those records are bounded and can be corrected or rebuilt, rather than causing an irreversible external side effect.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[socramreysa]

Running into this exact crash in prod (we track develop, currently on 2.4.0-rc2). Some @lid contacts just never send remoteJidAlt, so line 642 in chatwoot.service.ts ends up calling .split() on undefined and the message gets swallowed by the catch block. Took us a while to figure out because nothing retries or surfaces the drop.

We've been running a local backport of the same fallback idea on 2.3.7 since the end of September (both remoteJidAlt and participantAlt) and haven't seen the crash since, so it holds up in practice.

Is there anything holding the review? Happy to test or provide more details if useful. Messages silently disappearing for those contacts is the worst kind of bug to have in production.