Manage Facebook Ads Custom Audiences with WSO2 Micro Integrator

logo

Managing and automating Facebook Ads Custom Audience operations is essential for large-scale digital marketing campaigns. This blog demonstrates how to use the Facebook Ads connector with WSO2 Micro Integrator (MI) to programmatically fetch audiences, filter by name, and add or remove users — both manually and in bulk via CSV.

🛠️ Tools & Docs:

• WSO2 Micro Integrator Quick Start
• Facebook Access Token Guide
• Access Token Debugger
• Graph API Explorer

🔌 Connector Setup

You’ll need to configure a configKey with a valid access token to authorize requests to the Facebook Marketing API. This token must have the required permissions for ads_management.

fbads connection

📥 Fetch All Custom Audiences

This operation retrieves all custom audiences associated with a given Ad Account.

fetch all audiences

Integration Sequence:

<inSequence>
    <facebookAds.getCustomAudiences configKey="FBCONNECTION1">
        <adAccountId>{${payload.adAccountId}}</adAccountId>
    </facebookAds.getCustomAudiences>
    <respond />
</inSequence>

Sample Input:

{
    "adAccountId": "xxxxxxxxxxxxxxxxx"
}

Sample Output:

{
    "data": [
        {
            "id": "xxxxxxxxxxxxxxxxx",
            "name": "Audience from MI",
            "description": "Audience to test adding users",
            "account_id": "xxxxxxxxxxxx",
            "subtype": "CUSTOM",
            "delivery_status": {
                "code": 300,
                "description": "The audience is too small to be used in campaign creation."
            },
            "data_source": {
                "type": "UNKNOWN",
                "sub_type": "ANYTHING",
                "creation_params": "[]"
            },
            "customer_file_source": "USER_PROVIDED_ONLY",
            "retention_days": 0
        },
        {
            "id": "xxxxxxxxxxxxxxx",
            "name": "Audience from MI",
            "description": "Audience to test adding users",
            "account_id": "xxxxxxxxxxx",
            "subtype": "CUSTOM",
            "delivery_status": {
                "code": 300,
                "description": "The audience is too small to be used in campaign."
            },
            "data_source": {
                "type": "UNKNOWN",
                "sub_type": "ANYTHING",
                "creation_params": "[]"
            },
            "customer_file_source": "USER_PROVIDED_ONLY",
            "retention_days": 0
        }
    ]
}

🔎 Filter Audiences by Name

You can narrow down results by specifying an audience name.

filter audience

Integration Sequence:

<inSequence>
    <facebookAds.getCustomAudiences configKey="FBCONNECTION1">
        <adAccountId>{${payload.account_id}}</adAccountId>
        <filterByName>{${payload.filter_name}}</filterByName>
    </facebookAds.getCustomAudiences>
    <respond />
</inSequence>

Sample Input:

{
    "account_id": "xxxxxxxxxxxxxx",
    "filter_name": "Custom Audience With Users"
}

Sample Output:

{
    "data": [
        {
            "id": "xxxxxxxxxxxxxxxx",
            "name": "Custom Audience With Users",
            "description": "Audience to test adding users",
            "account_id": "xxxxxxxxxxxxxxxx",
            "subtype": "CUSTOM",
            "delivery_status": {
                "code": 300,
                "description": "The audience is too small to be used in campaign creation."
            },
            "data_source": {
                "type": "UNKNOWN",
                "sub_type": "ANYTHING",
                "creation_params": "[]"
            },
            "customer_file_source": "USER_PROVIDED_ONLY",
            "retention_days": 0
        }
    ]
}

Empty Result Example:

{
    "data": []
}

👥 Add Users to Custom Audience (JSON Input)

This operation adds hashed or raw user information to a specified audience.

⚠️ Every user object in the JSON array should have the same set of fields defined with or without values. The schema defined internally to be sent to the Facebook Ads REST API is for all the user records. The missing values can be left empty/””.

add users

Integration Sequence:

<inSequence>
    <facebookAds.addUsersToAudience configKey="FBCONNECTION1">
        <customAudienceId>{${payload.audienceId}}</customAudienceId>
        <properties>{${payload.properties}}</properties>
        <inputStructure>JSON_ARRAY</inputStructure>
    </facebookAds.addUsersToAudience>
    <respond />
</inSequence>

Valid Sample Input:

{
    "audienceId": "xxxxxxxxxxxxxxx",
    "properties": [
        {
            "email": "elizabetho@fb.com",
            "phone": "1-(650)-561-5622",
            "fn": "Elizabeth",
            "ln": "Olsen",
            "zip": "94046",
            "ct": "Menlo Park",
            "st": "CA",
            "country": "US",
            "dob": "10\/21\/68",
            "doby": 1968,
            "gen": "F",
            "age": 48,
            "uid": 1234567890
        },
        {
            "email": "andrewj@fb.com",
            "phone": "1-(212) 736-3100",
            "fn": "Andrew",
            "ln": "Jamison",
            "zip": "10118",
            "ct": "New York",
            "st": "NY",
            "country": "US",
            "dob": "10\/17\/78",
            "doby": 1978,
            "gen": "M",
            "age": 38,
            "uid": 1443637309
        }
    ]
}

Hashed Input Example: Hashed data must use SHA256 and retain the same field structure.

{
    "audienceId": "xxxxxxxxxxxxxxx",
    "properties": [
        {
            "email": "2e1d3f5a9c4b6e7f8a1b2c3d4e5f67890123456789abcdef0123456789abcdef0",
            "phone": "",
            "madid": "",
            "fn": "3f4a5b6c7d8e9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef1",
            "ln": "4a5b6c7d8e9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef012",
            "zip": "5b6c7d8e9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef01234",
            "ct": "6c7d8e9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456",
            "st": "7d8e9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef012345678",
            "country": "8e9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef01234567890",
            "dob": "9f0a1b2c3d4e5f67890123456789abcdef0123456789abcdef01234567890abc",
            "doby": "0a1b2c3d4e5f67890123456789abcdef0123456789abcdef01234567890abcdef",
            "gen": "1b2c3d4e5f67890123456789abcdef0123456789abcdef01234567890abcdef012",
            "age": "2c3d4e5f67890123456789abcdef0123456789abcdef01234567890abcdef01234",
            "uid": "3d4e5f67890123456789abcdef0123456789abcdef01234567890abcdef0123456"
        },
        {
            "email": "",
            "phone": "",
            "madid": "",
            "fn": "4e5f67890123456789abcdef0123456789abcdef01234567890abcdef01234567",
            "ln": "5f67890123456789abcdef0123456789abcdef01234567890abcdef0123456789",
            "zip": "67890123456789abcdef0123456789abcdef01234567890abcdef01234567890a",
            "ct": "",
            "st": "7890123456789abcdef0123456789abcdef01234567890abcdef01234567890ab",
            "country": "",
            "dob": "890123456789abcdef0123456789abcdef01234567890abcdef01234567890abc",
            "doby": "90123456789abcdef0123456789abcdef01234567890abcdef01234567890abcd",
            "gen": "0123456789abcdef0123456789abcdef01234567890abcdef01234567890abcde",
            "age": "123456789abcdef0123456789abcdef01234567890abcdef01234567890abcdef0",
            "uid": "23456789abcdef0123456789abcdef01234567890abcdef01234567890abcdef01"
        }
    ]
}

📁 Add Users from CSV File

Ideal for bulk uploads.

add users from csv

Integration Sequence:

<inSequence>
    <property name="audienceId" scope="default" type="STRING"
        expression="json-eval($.audienceId)" />
    <property name="filePath" scope="default" type="STRING"
        expression="json-eval($.filePath)" />
    <file.read configKey="FILE_CON">
        <path>{get-property('filePath')}</path>
        <readMode>Complete File</readMode>
        <includeResultTo>Message Body</includeResultTo>
        <enableStreaming>false</enableStreaming>
        <enableLock>false</enableLock>
        <maxRetries>3</maxRetries>
        <retryDelay>2000</retryDelay>
        <encoding>UTF-8</encoding>
    </file.read>
    <CSV.csvToJson>
        <headerPresent>Present</headerPresent>
        <csvEmptyValues>Empty</csvEmptyValues>
        <skipHeader>false</skipHeader>
    </CSV.csvToJson>
    <facebookAds.addUsersToAudience configKey="FACEBOOKCONN">
        <customAudienceId>{get-property('audienceId')}</customAudienceId>
        <properties>{json-eval($.)}</properties>
  <inputStructure>JSON_ARRAY</inputStructure>
    </facebookAds.addUsersToAudience>
    <respond />
</inSequence>

Sample Input:

{
  "audienceId": "xxxxxxxxxxxxxxx",
  "filePath": "/data.txt"
}

Sample Output:

200 OK
{
    "audience_id": "xxxxxxxxxxxxxxxxxx",
    "session_id": "xxxxxxxxxxxxxxxx",
    "num_received": 1001,
    "num_invalid_entries": 0,
    "invalid_entry_samples": {}
}

📝 CSV Tips:

• Use a consistent header row
• Missing values must be represented as empty strings ("")
• Facebook CSV guidelines

🗑️ Remove Users from Custom Audience (CSV Input)

To revoke access for users in a custom audience.

remove users

Integration Sequence:

<inSequence>
    <property name="audienceId" scope="default" type="STRING"
        expression="json-eval($.audienceId)" />
    <property name="filePath" scope="default" type="STRING"
        expression="json-eval($.filePath)" />
    <file.read configKey="FILE_CON">
        <path>{get-property('filePath')}</path>
        <readMode>Complete File</readMode>
        <includeResultTo>Message Body</includeResultTo>
        <enableStreaming>false</enableStreaming>
        <enableLock>false</enableLock>
        <maxRetries>3</maxRetries>
        <retryDelay>2000</retryDelay>
        <encoding>UTF-8</encoding>
    </file.read>
    <CSV.csvToJson>
        <headerPresent>Present</headerPresent>
        <csvEmptyValues>Empty</csvEmptyValues>
        <skipHeader>false</skipHeader>
    </CSV.csvToJson>
    <facebookAds.removeUsersFromAudience configKey="FACEBOOKCONN">
        <customAudienceId>{get-property('audienceId')}</customAudienceId>
        <properties>{json-eval($.)}</properties>
   <inputStructure>JSON_ARRAY</inputStructure>
    </facebookAds.removeUsersFromAudience>
    <respond />
</inSequence>

Sample Input:

{
  "audienceId": "xxxxxxxxxxxxxxx",
  "filePath": "/data.txt"
}

Sample Output:

200 OK
{
    "audience_id": "xxxxxxxxxxxxxxxxx",
    "session_id": "xxxxxxxxxxxxxxxx",
    "num_received": 1001,
    "num_invalid_entries": 0,
    "invalid_entry_samples": {}
}

🔗 References

• Facebook Marketing API Overview
• WSO2 File Connector Docs
• WSO2 CSV Module Docs
• User Schema Guide for Facebook Audiences

Using WSO2 MI with Facebook Ads APIs allows for modular, repeatable, and scalable audience management — critical for modern ad automation workflows.