Social Media

Metaads

Learn how to use Metaads with Composio

Overview

SLUG: METAADS

Description

Meta Ads API

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
stringDefaults to ads_read,ads_management
bearer_token
string
bearer_token
stringRequired

Connecting to Metaads

Create an auth config

Use the dashboard to create an auth config for the Metaads toolkit. This allows you to connect multiple Metaads accounts to Composio for agents to use.

1

Select App

Navigate to the Metaads toolkit page and click “Setup Integration”.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Integration”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2from composio.types import auth_scheme
3
4# Replace these with your actual values
5metaads_auth_config_id = "ac_YOUR_METAADS_CONFIG_ID" # Auth config ID created above
6user_id = "0000-0000-0000"  # UUID from database/application
7
8composio = Composio()
9
10
11def authenticate_toolkit(user_id: str, auth_config_id: str):
12    connection_request = composio.connected_accounts.initiate(
13        user_id=user_id,
14        auth_config_id=auth_config_id,
15    )
16
17    print(
18        f"Visit this URL to authenticate Metaads: {connection_request.redirect_url}"
19    )
20
21    # This will wait for the auth flow to be completed
22    connection_request.wait_for_connection(timeout=15)
23    return connection_request.id
24
25
26connection_id = authenticate_toolkit(user_id, metaads_auth_config_id)
27
28# You can also verify the connection status using:
29connected_account = composio.connected_accounts.get(connection_id)
30print(f"Connected account: {connected_account}")

Using API Key

1from composio import Composio
2from composio.types import auth_scheme
3
4# Replace these with your actual values
5metaads_auth_config_id = "ac_YOUR_METAADS_CONFIG_ID" # Auth config ID created above
6user_id = "0000-0000-0000"  # UUID from database/app
7
8composio = Composio()
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11    # Replace this with a method to retrieve an API key from the user.
12    # Or supply your own.
13    user_api_key = input("[!] Enter API key")
14
15    connection_request = composio.connected_accounts.initiate(
16        user_id=user_id,
17        auth_config_id=auth_config_id,
18        config={"auth_scheme": "API_KEY", "val": user_api_key}
19    )
20
21    # API Key authentication is immediate - no redirect needed
22    print(f"Successfully connected Metaads for user {user_id}")
23    print(f"Connection status: {connection_request.status}")
24    
25    return connection_request.id
26
27
28connection_id = authenticate_toolkit(user_id, metaads_auth_config_id)
29
30# You can verify the connection using:
31connected_account = composio.connected_accounts.get(connection_id)
32print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Metaads toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["METAADS"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Create Ad

Description

Create a new ad within an ad set using the meta marketing api. supports various ad formats including image, video, carousel, and collection ads.

Action Parameters

ad_set_id
stringRequired
bid_amount
integer
creative
objectRequired
name
stringRequired
status
stringDefaults to PAUSED
tracking_specs
array

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Ad Creative

Description

Create a new ad creative using the meta marketing api. ad creatives are reusable visual and interactive elements that define how your ad looks and behaves: - can be used in multiple ads - support various formats (image, video, carousel) - include text, media, and call-to-action buttons - must follow meta's ad policies

Action Parameters

account_id
stringRequired
creative
objectRequired
name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Ad Set

Description

Create a new ad set within a campaign using the meta marketing api. supports detailed targeting options, budgets, and optimization goals.

Action Parameters

bid_amount
integerRequired
billing_event
stringRequired
campaign_id
stringRequired
daily_budget
number
end_time
string
lifetime_budget
number
name
stringRequired
optimization_goal
stringRequired
start_time
string
status
stringDefaults to PAUSED
targeting
objectRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Campaign

Description

Create a new advertising campaign using the meta marketing api. supports various campaign objectives, budgets, and bidding strategies.

Action Parameters

account_id
stringRequired
bid_strategy
stringDefaults to LOWEST_COST_WITHOUT_CAP
daily_budget
number
lifetime_budget
number
name
stringRequired
objective
stringRequired
special_ad_categories
array
status
stringDefaults to PAUSED

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Custom Audience

Description

Create a new custom audience using the meta marketing api. supports various types of custom audiences including customer lists, website visitors, and app users.

Action Parameters

account_id
stringRequired
content_type
string
customer_file
array
customer_file_source
string
description
string
name
stringRequired
prefill
booleanDefaults to True
retention_days
integer
rule
object
subtype
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Insights

Description

Get insights data for a meta ads object (ad account, campaign, ad set, or ad) using the meta marketing api. supports various metrics, breakdowns, and filtering options with flexible date ranges.

Action Parameters

action_attribution_windows
arrayDefaults to ['7d_click', '1d_view']
breakdowns
array
date_preset
string
fields
arrayDefaults to ['impressions', 'clicks', 'spend']
filtering
array
level
stringDefaults to account
object_id
stringRequired
sort
array
time_range
object

Action Response

data
arrayRequired
error
string
paging
object
successful
booleanRequired

Tool Name: Update Campaign

Description

Update an existing advertising campaign using the meta marketing api. allows modification of campaign properties like name, status, budget, and bidding strategy. only the fields that need to be updated should be included in the request.

Action Parameters

bid_strategy
string
campaign_id
stringRequired
daily_budget
number
lifetime_budget
number
name
string
special_ad_categories
array
spend_cap
number
status
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Ad Creative

Description

Delete ad creative

Action Parameters

creative_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Campaign

Description

Delete an advertising campaign using the meta marketing api. this marks the campaign as deleted, which prevents it from delivering ads. note that deleted campaigns are not permanently removed from meta's systems and can still be viewed in reports.

Action Parameters

campaign_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Ad Creative

Description

Get ad creative

Action Parameters

creative_id
stringRequired
fields
arrayDefaults to ['id', 'name', 'status', 'object_story_spec']

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Pause Campaign

Description

Pause an advertising campaign using the meta marketing api. this stops the campaign from delivering ads but allows it to be resumed later. all child ad sets and ads will also be paused with an effective status of campaign paused.

Action Parameters

campaign_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Preview Ad Creative

Description

Preview ad creative

Action Parameters

creative_id
stringRequired
thumbnail_height
integerDefaults to 120
thumbnail_width
integerDefaults to 150

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Read Ad Sets

Description

Retrieve ad sets from a meta ad account using the marketing api. returns information about the ad sets including their status, targeting, and other properties.

Action Parameters

ad_account_id
stringRequired
date_preset
string
effective_status
array
fields
arrayDefaults to ['name', 'id', 'status']
is_completed
boolean
limit
integerDefaults to 50
time_range_since
string
time_range_until
string
updated_since
integer

Action Response

data
arrayRequired
error
string
paging_next
string
paging_previous
string
successful
booleanRequired
total_count
integer

Tool Name: Resume Campaign

Description

Resume a paused advertising campaign using the meta marketing api. this sets the campaign status to active so it can deliver ads again. note that child ad sets and ads that were previously active will also resume delivery, but those that were individually paused will remain paused.

Action Parameters

campaign_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Ad Creative

Description

Update ad creative

Action Parameters

creative_id
stringRequired
name
string
status
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Upload Ad Image

Description

Upload an image for use in meta ad creatives using the marketing api. the image can later be referenced by its hash when creating ad creatives.

Action Parameters

ad_account_id
stringRequired
image
objectRequired
name
string

Action Response

data
objectRequired
error
string
successful
booleanRequired