About Facebook Ads Referral Tags

Facebook Ads referral tags allow tracking where exactly users come from to your site or bot. This allows analyzing advertising campaign effectiveness and optimizing marketing strategy.

Context and Problem

In many cases, you need to track traffic sources:

Determining most effective advertising campaigns
Assessing ROI of advertising spend
Optimizing marketing strategy
Personalizing messages based on source

Referral tags solve this task by allowing adding unique parameters to advertising campaign URLs and saving them for further analysis.

Key Concepts

Referral Tag Structure

Referral tags are added to URLs as query parameters:

ref_source=ADS — indicates this is advertising
ref=campaign_name — campaign name
ref_ad_id=123456789 — ID of specific advertising campaign

Saving Tags

Tags from URL are automatically saved in system variables:

ref_source — source (ADS)
ref — campaign name
ref_ad_id — advertising campaign ID

These variables are available in scenarios for use in logic and personalization.

Approach Options

Saving in Variables vs Custom Data

Saving in variables:

✅ Pros: Simple access, automatic saving
❌ Cons: Limited persistence

Saving in Custom Data:

✅ Pros: Permanent storage, analytics possibility
❌ Cons: Requires additional processing

Why we use both approaches: Variables are convenient for quick access in scenarios, and Custom Data — for long-term storage and analytics.

Adopted Solutions

Using Action Jail for Saving

For saving tags in Custom Data, Action Jail is used, which:

Receives tags from URL parameters
Creates or updates Custom Data
Adds additional data (name, phone, messenger)

Automatic Saving in Variables

Tags are automatically saved in system variables when user enters the bot, allowing using them immediately in scenarios.

Implications for Users and Implementation

For Integrators

When using referral tags, it's important to:

Add tags to URL — in Facebook advertising campaigns
Configure Action Jail — for saving tags in Custom Data (optional)
Use tags in scenarios — for personalization and analytics
Create analytics — for tracking campaign effectiveness

Common Errors

Error: Tags are not saved
Problem: Action Jail is not added for processing URL parameters
Solution: Add Action Jail that processes URL parameters when user enters

Error: Tags are lost between sessions
Problem: Tags are saved only in variables, not in Custom Data
Solution: Use Action Jail to save in Custom Data

Error: Cannot track campaign effectiveness
Problem: Tags are not saved for analytics
Solution: Create a table in Custom Data for storing statistics

Usage Examples

URL with Referral Tags

https://www.example.com?ref=campaign_a&ref_source=ADS&ref_ad_id=123456789

Usage in Scenarios

Tags are available as variables:

{{ref_source}} — source (ADS)
{{ref}} — campaign name
{{ref_ad_id}} — advertising campaign ID

Saving in Custom Data

const action_save_referral_data = function() {
    const j = this.getCurrentStateJSON();
    const user_request = j.user_request || {};
    
    const ref_source = user_request.ref_source || null;
    const ref = user_request.ref || null;
    const ref_ad_id = user_request.ref_ad_id || null;
    
    // Create or update custom_data
    if (!j.custom_data) {
        j.custom_data = {};
    }
    
    if (!j.custom_data.referral_stats) {
        j.custom_data.referral_stats = [];
    }
    
    j.custom_data.referral_stats.push({
        ref_source: ref_source,
        ref: ref,
        ref_ad_id: ref_ad_id,
        timestamp: new Date().toISOString(),
        client_name: j.client?.first_name || '',
        client_phone: j.client?.phone || '',
        messenger: this.channel
    });
    
    this.setCurrentStateConstant('custom_data', j.custom_data);
    
    return 'success';
};

Explanation: Launching Scenario from Facebook Ads — configuring scenario launch from advertising
How-to: Create action in Action Jail — how to create custom actions