v2026.2.6

Release date: February 13, 2026

---

✨ New Features

🎯 Facebook Conversions API - Automatic Tracking

Complete implementation of Facebook Conversions API (CAPI) for server-side conversion tracking, allowing each CRM stage change to automatically trigger conversion events to Facebook.

What is it for?

• Precise Tracking: Events sent directly from server to Facebook, more reliable than browser-side pixels
• Ad Optimization: Facebook receives real-time conversion data and optimizes campaigns automatically
• Perfect Attribution: System automatically identifies which ad the customer came from through tracking data
• High Match Rate: Sends encrypted email, phone, name, IP and Click ID for better user matching on Facebook

How to use?

1. Configure your UTM Campaign:

   • Go to UTM Menu → Campaigns
   • Create a new campaign
   • IMPORTANT: Enter the Facebook Campaign ID (e.g., 120233174044090606)
   • Configure the Facebook Pixel (ID + Access Token)

2. Configure Events in CRM Stages:

   • Go to CRM → Manage Stages
   • In each important stage (Qualified Lead, Purchased, etc.)
   • Enable "Conversion Event"
   • Select platform: Facebook
   • Choose the appropriate event type
   • Configure value and currency (or let it use customer's sale_price)

3. Automatic Tracking:

   • Customer clicks on Facebook "Click to WhatsApp" ad
   • WhatsApp sends tracking data in first message
   • System automatically identifies campaign by ID
   • Customer is linked to campaign
   • When changing stage → event sent to Facebook!

Supported Events

19 standard Facebook Conversions API events:

Category	Events
Purchase	Purchase, InitiateCheckout, AddToCart, AddToWishlist, AddPaymentInfo
Lead	Lead, CompleteRegistration, Contact
Interest	ViewContent, Search
Scheduling	Schedule, StartTrial
Action	Subscribe, SubmitApplication, CustomizeProduct
Special	Donate, FindLocation, PageView, Other

Data Sent Automatically

Customer Data (SHA256 encrypted):

• ✉️ Email
• 📱 WhatsApp/Phone
• 👤 Name (first and last)
• 🆔 Customer ID

Event Data:

• 🎯 Event Type (Purchase, Lead, etc.)
• 💰 Conversion Value
• 💵 Currency (BRL, USD, etc.)
• 📝 Stage Name
• 📂 Funnel Category

Ad Data (tracking):

• 🔗 Click ID (fbclid/ctwa_clid)
• 🆔 Ad ID
• 📢 Campaign ID
• 📰 Ad Title and Text
• 🌐 Source URL

Technical Data:

• 🌍 Customer IP
• 🖥️ User Agent (browser/device)
• ⏰ Precise Timestamp

Automatic Origin Identification

How the system identifies where the customer came from:

1. Customer clicks "Click to WhatsApp" ad
   ↓
2. WhatsApp adds INVISIBLE data to first message:
   - sourceID: Facebook Campaign ID
   - ctwaClid: Unique click ID
   - adTitle, adBody, thumbnailURL
   - messageTimestamp
   ↓
3. Customer sends message (e.g., "Hello, I want to know more")
   ↓
4. System receives message + invisible data
   ↓
5. System searches: "Campaign with sourceID = 120233..."
   ↓
6. Customer automatically linked to campaign!

Important: Tracking data comes only in the first message!

Chat Alerts

System automatically saves alerts in chat when:

• ❌ Customer has no associated UTM campaign
• ❌ Pixel not configured or inactive
• ❌ Invalid access token
• ❌ Facebook API error (with complete error details)

Action Source: physical_store

Uses action_source: 'physical_store' (offline events) which:

• ✅ Works with existing Pixel (no need to create Dataset)
• ✅ Supports ALL 19 standard events
• ✅ Allows including all tracking fields
• ✅ Production-ready without additional configuration

---

🔧 Technical Improvements

Conversion Architecture

• Service Layer: conversion-events-service.js with multi-platform support
• Event Dispatching: Modular system for Facebook, Google Ads and TikTok
• Error Handling: Robust handling with structured logs and Sentry
• Deduplication: Unique Event ID based on SHA256 hash
• Match Quality: Estimated Event Match Quality Score calculation
• Encryption: Sensitive data encrypted with AES-256
• Hashing: PII hashed with SHA256 per GDPR

Frontend

• StageModal.tsx: Complete interface to configure multiple events
• Multi-Event Support: Array of events (Facebook, Google, TikTok simultaneously)
• Intuitive UI/UX: Form with validation and informative hints
• Translations: Full support in PT, EN and ES for all 19 events

Backend

• Customer Stage Service: Automatic integration when changing stage
• UTM Tracking: Automatic contact lookup in customer_contacts
• Fallback Logic: Smart priority (customer → stage → default)
• Webhook Integration: Automatic data extraction from WhatsApp
• Campaign Matching: Linking by metadata sourceID

Database

• Migration: Conversion of utm_event from object to array (multi-event support)
• JSONB: Flexible structure for UTM metadata and event configuration
• Backward Compatibility: Automatic migration of existing data

---

📚 Documentation

GUIA_CONVERSOES.md (New)

Complete guide for end users with:

• ✅ Step-by-step setup
• ✅ Explanation of all 19 available events
• ✅ Use case tables for each event
• ✅ Complete visual tracking flow
• ✅ Detailed explanation of invisible data
• ✅ How system identifies origin (sourceID, ctwaClid)
• ✅ Extensive troubleshooting and FAQ
• ✅ Complete practical example (e-commerce)
• ✅ Best practices and checklist
• ✅ Executive summary of key points

CONVERSION_EVENTS.md (Updated)

Complete technical documentation:

• 📊 System architecture
• 🔌 Facebook CAPI integration
• 📈 Event Match Quality and optimization
• 🔐 Security and encryption
• 🚨 Chat alert system
• ⚙️ Campaign and pixel configuration
• 🧪 Payload examples and tests

---

🎯 Benefits

• ✅ 100% Automatic Tracking: Customer automatically linked when clicking ad
• ✅ Zero Manual Configuration: No need to manually mark where they came from
• ✅ Accurate Data: sourceID ensures correct campaign identification
• ✅ Unique Click ID: ctwa_clid enables precise tracking of each click
• ✅ Automatic Optimization: Facebook optimizes ads based on real conversions
• ✅ Measurable ROI: See exactly which ads generate sales
• ✅ High Match Rate: Multiple identification fields (email, phone, Click ID)
• ✅ Total Transparency: Chat alerts show any errors
• ✅ Multi-Event: Configure different events for each stage
• ✅ Scalable: Future support for Google Ads and TikTok

---

🔄 Migration

-- Automatic migration of utm_event from object to array
-- Supports multiple simultaneous event configuration

File: 20260212100000_migrate_utm_event_to_array.sql

---

🚀 Getting Started

1. Read the guide: Access docs/GUIA_CONVERSOES.md
2. Configure your first campaign: UTM Menu → Campaigns
3. Add Facebook Campaign ID: E.g., 120233174044090606
4. Configure Pixel: ID + Access Token
5. Configure events in stages: CRM → Manage Stages
6. Test: Move a customer who came from an ad to another stage
7. Verify: Facebook Events Manager

---

⚠️ Important

• 🎯 Campaign ID is required: Without it, system won't automatically link
• 📱 Only Click to WhatsApp Ads: Regular ads don't send tracking data
• 💬 First message is crucial: Data comes only in customer's first message
• 🔑 Valid token: Check if Facebook Access Token is active
• ✅ Production Tested: System working with action_source: physical_store

---

Estimated setup time: 10-15 minutes
Impact: High - Reduction in ad costs and increase in conversions
Priority: 🔥 Essential for Facebook Ads users