Feature: Add Facebook Ads Message Template Support for Chatwoot Integration

[bergpinheiro]

Pull Request Description

🚀 Feature: Add Facebook Ads Message Template Support for Chatwoot Integration

This PR adds support for displaying Facebook Ads messages that arrive via WhatsApp in the Chatwoot integration, allowing agents to view and respond specifically to customers interacting with ads.

---

📋 Overview

This feature implements a template system to process Facebook ad messages arriving through WhatsApp, including:

• 📢 Ad Detection - Automatic identification of Facebook ad messages
• 🎨 Formatted Templates - Structured display of ad data
• 🖼️ Image Download - Processing and attaching ad images
• 💬 Content Separation - Clear distinction between ad data and customer messages

---

🔧 Technical Implementation

Main Changes

1. Message handler enhancements (src/apps/chatroot/consumers/waha/message.any.ts)

• Added isFacebookAd() method to detect Facebook ad messages
• Implemented extractAdReply() to extract ad data from the WhatsApp payload
• Created extractAdData() to process and normalize ad data
• Added getFacebookAdMessage() to generate a template-formatted message

2. Template system extension (src/apps/chatroot/i18n/templates.ts)

• Added new template key: WA_TO_CW_MESSAGE_FACEBOOK_AD
• TypeScript interface defined for ad data:

ad data: {
title: string;
body: string;
thumbnailURL: string;
originalImageURL: string;
sourceURL: string;
sourceID: string;
}

3. Internationalization Support

• English template (en-US.yaml):

whatsapp.to.chatwoot.message.facebook.ad: |-
📢 **FACEBOOK AD**
**Title:** {{{adData.title}}}
**Description:** {{{adData.body}}}
**Ad Link:** [View on Facebook]({{{adData.sourceURL}}})
**Ad ID:** {{{adData.sourceID}}}
---
💬 **CUSTOMER MESSAGE:**
{{{payload.body}}}

• Portuguese template (pt-BR.yaml):

whatsapp.to.chatwoot.message.facebook.ad: |-
📢 **FACEBOOK AD FACEBOOK**
**Title:** {{{adData.title}}}
**Description:** {{{adData.body}}}
**Ad Link:** [View on Facebook]({{{adData.sourceURL}}})
**Ad ID:** {{{adData.sourceID}}}
---
💬 **CUSTOMER MESSAGE:**
{{{payload.body}}}

Ad Detection

**4. Verification

• Verification in extendedTextMessage.contextInfo.externalAdReply

5. Data Processing

• Extract ad title, description, and URLs
• Automatically download ad images
• Create an image attachment for display in Chatwoot
• Error handling for image download failures

---

📝 Main Features

Automatic Detection

• ✅ Automatically identifies Facebook ad messages
• ✅ Processes WhatsApp 'externalAdReply' data

Formatted Display

• ✅ Clearly highlighted ad title and description
• ✅ Direct link to view the ad on Facebook
• ✅ Ad ID for referencing and tracking
• ✅ Visual separation between ad data and customer message

Media Processing

• ✅ Automatically download ad images
• ✅ Image attachment as media in Chatwoot conversations
• ✅ Error handling for unavailable images
• ✅ Support Different image URL formats

Internationalization

• ✅ Templates in Portuguese and English
• ✅ Structure prepared to add other languages
• ✅ Consistent formatting with other message types

---

🎯 Use Cases

Customer Service

• Customers who clicked on Facebook ads and sent a message via WhatsApp
• Agents can see the context of the ad that generated the contact
• Better understanding of customer interest based on the ad

---

🔄 Processing Flow

1. Message Reception - WhatsApp receives a message with a Facebook ad
2. Detection - The system identifies an externalAdReply without a payload
3. Extraction - Ad data is extracted and normalized
4. Template - The message is formatted using an internationalized template
5. Download - The ad image is downloaded and attached
6. Display - The formatted message is displayed on the Chatwoot

---

✅ Testing Considerations

• Ad messages are blocked correctly in different

screenshot:

I just hope you enjoy some of the code if it's useful.

[nathanarend]

+1

[Click-Hype]

+1

[devlikepro]

2025.10.1 - Add Facebook Ads message - #1461

[github-actions]

Portuguese

---

Title:

2025.10.1 - Adicionar mensagem de anúncios do Facebook - #1461