أدوات Meta Ads: الحملات والمجموعات الإعلانية والتغييرات

في هذه الصفحة 13 أداة. هذه الصفحة مولَّدة آليًا من قائمة الأدوات في الخادم نفسه، الإصدار 0.1.0، ولا تُحرَّر باليد. أوصاف الأدوات مكتوبة للمساعد الذكي، وهي بالإنجليزية ولم تُترجم، فكل ما تحت هذه الفقرة بالإنجليزية كما يقرؤه المساعد الذكي. لا تحتاج إلى معرفة اسم أي أداة لتطلب عملًا: هذه الصفحة مرجع لمن يريد أن يعرف ما تأخذه كل أداة بالضبط. صفحة كل الأدوات تسرد الصفحات كلها.

meta_ads_search_targeting

Kind: read. It is marked as changing nothing.

Find the ids and keys that meta_ads_create_adset's targeting takes: interests, behaviours, job titles, employers, schools, industries, places and languages.

Each result says where it goes: a detailed-targeting option carries kind and id (pass {kind, id, name}), a place carries key and use_in (countries, regions or cities), a language carries key for locales.

Argument	Type	Required	Default	Description
query	text	no	""	What to look for, e.g. "accounting software" or "Kuwait". For behavior, demographic, industry, life_event, family_status and income, Meta has a fixed list: the query filters it, and an empty query returns the start of it.
type	text	no	"interest"	interest, behavior, demographic, industry, life_event, family_status, income, work_position, work_employer, school, major, location or locale.
location_types	list of text	no	none	For location: any of country, region, city (all three by default).
country_code	text	no	none	For location: only places in this country.
limit	whole number	no	25	How many results (1-50).

meta_ads_list_budget_schedules

Kind: read. It is marked as changing nothing.

List the budget schedules of a Meta campaign or ad set: the periods in which its daily budget is raised, with when each starts and ends. One call to Meta.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign" or "adset" - what object_id is.
object_id	text	yes		From meta_ads_list.

meta_ads_set_status

Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.

Switch a Meta campaign, ad set or ad on or off, archive it or delete it. This is the only tool that can start spending: nothing else activates anything.

ACTIVE is checked against this installation's spending limits before it is sent, and this installation may require every ad that would run to have been previewed with meta_ads_preview in the last 24 hours. The dry run lists the budgets that would start spending, the most they could spend, the ads that would run, and what the ad account's active daily budgets would total. Show the user that and activate only after they confirm; never activate as a side effect of another request. PAUSED stops it and can be undone. ARCHIVED cannot be undone (an archived object can only be deleted) but keeps its results. DELETED cannot be undone and needs confirm_remove=true: prefer PAUSED or ARCHIVED unless the user asked for it to be deleted.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign", "adset" or "ad" - what object_id is.
object_id	text	yes		From meta_ads_list.
status	text	yes		"ACTIVE", "PAUSED", "ARCHIVED" or "DELETED".
confirm_remove	true or false	no	false	Must be true to delete, and only when the user asked for a delete.
dry_run	true or false	no	true	true = Meta checks the change without making it (default). false = make it, only after the user confirms.

meta_ads_update_budget

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Change the budget, bid or end time of a Meta campaign or ad set. Amounts are in the ad account's currency units (25.50, not 2550).

The budget is changed where it already is: a campaign that holds the budget, or an ad set that holds its own, and a daily budget stays daily and a lifetime one lifetime. Subject to this installation's limits for the account's currency: the highest daily and lifetime budget, the largest increase in one call, the total of the account's active daily budgets, and the longest an ad set may run. A call over a limit is refused, not trimmed. Meta itself allows an ad set's budget to change only four times in an hour.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign" or "adset" - what object_id is.
object_id	text	yes		From meta_ads_list.
daily_budget	number	no	none	New average daily budget. Meta may spend up to 75% more on one day.
lifetime_budget	number	no	none	New lifetime budget.
bid_amount	number	no	none	Ad set only: the bid cap or cost target.
bid_strategy	text	no	none	LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP or LOWEST_COST_WITH_MIN_ROAS.
end_time	text	no	none	Ad set only: when it stops, ISO 8601 with an offset, e.g. 2026-11-30T23:59:00+03:00. Without an offset it is read as UTC.
dry_run	true or false	no	true	true = Meta checks the change without making it (default). false = make it, only after the user confirms.

meta_ads_create_campaign

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a Meta campaign. It is always created PAUSED, and it has no dates: its ad sets carry the schedule. Amounts are in the ad account's currency units.

Give a budget here to have the campaign hold it and share it between its ad sets, or give none and let each ad set hold its own. Budgets are subject to this installation's limits for the account's currency; a call over one is refused, not trimmed.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
name	text	yes		The campaign's name.
objective	text	yes		OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_APP_PROMOTION or OUTCOME_SALES.
special_ad_categories	list of text	no	none	Required by Meta's policy when the ads are about EMPLOYMENT, HOUSING, CREDIT, FINANCIAL_PRODUCTS_SERVICES, ISSUES_ELECTIONS_POLITICS or ONLINE_GAMBLING_AND_GAMING. Ask the user rather than assuming none applies; declaring one limits the targeting Meta allows.
special_ad_category_country	list of text	no	none	With a category: the countries it is declared for.
daily_budget	number	no	none	Campaign-level average daily budget.
lifetime_budget	number	no	none	Campaign-level lifetime budget.
bid_strategy	text	no	none	With a campaign budget: LOWEST_COST_WITHOUT_CAP (default), LOWEST_COST_WITH_BID_CAP, COST_CAP or LOWEST_COST_WITH_MIN_ROAS.
spend_cap	number	no	none	The most the campaign may ever spend; it stops for good when reached.
dry_run	true or false	no	true	true = Meta checks it without creating anything (default). false = create it, only after the user confirms.

meta_ads_create_adset

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create an ad set in a Meta campaign: who sees the ads, where, when, what Meta optimises for and (unless the campaign holds it) the budget. Always created PAUSED.

The dry run is checked by Meta and its preview carries the targeting as it will be sent, Meta's estimate of the audience size (with a warning when it is very small) and the most the budget could spend. Show the user that before dry_run=false.

What goes with which campaign objective:

• OUTCOME_LEADS with a lead form: destination_type ON_AD, optimization_goal LEAD_GENERATION or QUALITY_LEAD, promoted_object.page_id.
• OUTCOME_LEADS or OUTCOME_SALES on a website: no destination_type, OFFSITE_CONVERSIONS, promoted_object.pixel_id and custom_event_type.
• OUTCOME_TRAFFIC: no destination_type, LINK_CLICKS or LANDING_PAGE_VIEWS.
• OUTCOME_AWARENESS: REACH, IMPRESSIONS, AD_RECALL_LIFT or THRUPLAY, promoted_object.page_id.
• OUTCOME_ENGAGEMENT: destination_type ON_POST with POST_ENGAGEMENT, ON_PAGE with PAGE_LIKES (page_id), ON_VIDEO with THRUPLAY.
• Ads that open a chat: destination_type WHATSAPP, MESSENGER or INSTAGRAM_DIRECT, optimization_goal CONVERSATIONS, promoted_object.page_id, under OUTCOME_ENGAGEMENT, OUTCOME_TRAFFIC or OUTCOME_SALES (WhatsApp also under OUTCOME_LEADS). The creative then needs the same message_destination.

A combination Meta does not allow is refused with the ones it does.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
campaign_id	text	yes		The campaign it goes in, from meta_ads_list or meta_ads_create_campaign.
name	text	yes		The ad set's name.
targeting	Targeting	yes		Countries (or regions, cities), ages, gender, languages, detailed targeting, custom audiences, placements. Ids and keys come from meta_ads_search_targeting. Countries may be limited by this installation.
optimization_goal	text	yes		What Meta optimises delivery for; see above.
billing_event	text	no	"IMPRESSIONS"	What is paid for: IMPRESSIONS (default, and the only choice for most goals), LINK_CLICKS, THRUPLAY.
destination_type	text	no	none	Where the result happens; see above.
promoted_object	PromotedObject	no	none	The Page, pixel and event, or app the goal is about.
daily_budget	number	no	none	Average daily budget. Meta may spend up to 75% more on one day.
lifetime_budget	number	no	none	Budget for the whole run; needs end_time.
start_time	text	no	none	ISO 8601 with an offset, e.g. 2026-11-01T09:00:00+03:00. Now if left out.
end_time	text	no	none	When it stops. This installation may require one.
bid_amount	number	no	none	The bid cap or cost target, with a bid_strategy that takes one.
bid_strategy	text	no	none	LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP or LOWEST_COST_WITH_MIN_ROAS.
attribution_spec	list of AttributionWindow	no	none	e.g. [{"event_type": "CLICK_THROUGH", "window_days": 7}].
frequency_caps	list of FrequencyCap	no	none	e.g. [{"interval_days": 7, "max_frequency": 3}] - at most 3 impressions per person in 7 days. For REACH and awareness goals.
schedule	list of ScheduleSlot	no	none	Hours of the day and days of the week to run; lifetime budgets only.
dsa_payor	text	no	none	Needed when an EU country is targeted: who pays for the ads.
dsa_beneficiary	text	no	none	Needed when an EU country is targeted: who the ads are for.
dry_run	true or false	no	true	true = Meta checks it without creating anything (default). false = create it, only after the user confirms.

meta_ads_update_campaign

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Rename a Meta campaign, or change the special ad categories it declares.

Its budget and bid strategy are changed with meta_ads_update_budget and its status with meta_ads_set_status. Its objective cannot be changed: make a new campaign with meta_ads_create_campaign and copy the ad sets into it with meta_ads_duplicate.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
campaign_id	text	yes		From meta_ads_list.
name	text	no	none	The new name.
special_ad_categories	list of text	no	none	The whole new list: EMPLOYMENT, HOUSING, CREDIT, FINANCIAL_PRODUCTS_SERVICES, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING. [] declares none. Ask the user; do not assume.
special_ad_category_country	list of text	no	none	With a category: the countries it is declared for.
dry_run	true or false	no	true	true = Meta checks the change without making it (default). false = make it, only after the user confirms.

meta_ads_update_adset

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Change a Meta ad set: its name, who sees the ads, when it starts, its attribution windows, its frequency cap or the hours it runs. Give only what changes.

targeting replaces the whole targeting, so give all of it, not only the part that changes; it is checked as at creation, and the dry run carries Meta's estimate of the new audience. On an ad set that is running, a change of targeting restarts Meta's learning. The budget, bid and end time are changed with meta_ads_update_budget. What it optimises for, where the result happens and what it promotes are fixed when it is made: copy it with meta_ads_duplicate or make a new one.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
adset_id	text	yes		From meta_ads_list.
name	text	no	none	The new name.
targeting	Targeting	no	none	The whole new targeting, as for meta_ads_create_adset.
start_time	text	no	none	ISO 8601 with an offset. Only for an ad set that has not started.
attribution_spec	list of AttributionWindow	no	none	e.g. [{"event_type": "CLICK_THROUGH", "window_days": 7}].
frequency_caps	list of FrequencyCap	no	none	e.g. [{"interval_days": 7, "max_frequency": 3}].
schedule	list of ScheduleSlot	no	none	Hours of the day and days of the week to run; lifetime budgets only.
dsa_payor	text	no	none	Needed when an EU country is targeted: who pays for the ads.
dsa_beneficiary	text	no	none	Needed when an EU country is targeted: who the ads are for.
dry_run	true or false	no	true	true = Meta checks the change without making it (default). false = make it, only after the user confirms.

meta_ads_update_ad

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Change a Meta ad: its name, the creative it shows, or the pixel that tracks it.

A creative cannot be edited, so changing what an ad shows means making a new creative with meta_ads_create_creative and putting it on the ad here. That sends the ad back through Meta's review. On an ad that is switched on, this installation may require the new creative to have been previewed with meta_ads_preview in the last 24 hours. An ad cannot be moved to another ad set: copy it with meta_ads_duplicate.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
ad_id	text	yes		From meta_ads_list.
name	text	no	none	The new name.
creative_id	text	no	none	The creative to show instead, from meta_ads_list_creatives.
pixel_id	text	no	none	The pixel that records what people do after the ad.
conversion_domain	text	no	none	The bare domain conversions happen on, like example.com.
dry_run	true or false	no	true	true = Meta checks the change without making it (default). false = make it, only after the user confirms.

meta_ads_duplicate

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Copy a Meta campaign, ad set or ad. The copy is always PAUSED and carries its source's settings, budget included; switch it on with meta_ads_set_status, which checks the spending limits.

The dry run is this server's preflight, not Meta's check. Meta copies at most 3 ads under a campaign or ad set in one call: for more, copy without deep_copy and then copy what is under it one at a time, giving the copy as to_parent_id.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign", "adset" or "ad" - what object_id is.
object_id	text	yes		From meta_ads_list.
deep_copy	true or false	no	false	Also copy the ad sets and ads under a campaign, or the ads under an ad set.
rename_suffix	text	no	"- Copy"	Added to the copy's name (and, with deep_copy, to everything under it).
to_parent_id	text	no	none	Put the copy of an ad set in this campaign, or the copy of an ad in this ad set, instead of beside its source.
dry_run	true or false	no	true	true = check only (default). false = make the copy, after the user confirms.

meta_ads_bulk_update

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Pause or archive several Meta campaigns, ad sets or ads, or change the budget, bid or end time of several campaigns or ad sets, in one call - up to 25, all of one level.

Each item is checked and changed by itself, exactly as meta_ads_set_status or meta_ads_update_budget would: the same limits, Meta's own check on a dry run, and its own row in the activity log. The answer lists every item with its result or the reason it was refused; one refusal does not stop the others. Switching on and deleting are not offered here: each of those is its own confirmed call to meta_ads_set_status. Each item costs two calls to Meta, so do not use this for a single object.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign", "adset" or "ad" - what every object_id is.
items	list of BulkItem	yes		One per object: {"object_id": ..., "status": "PAUSED"} or {"object_id": ..., "daily_budget": 30} (or lifetime_budget, bid_amount, end_time). Amounts are in the ad account's currency units.
dry_run	true or false	no	true	true = check every item and change nothing (default). false = make the changes, only after the user confirms.

meta_ads_add_labels

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Put labels on a Meta campaign, ad set or ad, or take some off. Labels are the ad account's own tags for grouping things; meta_ads_list shows them. A label that does not exist yet is made. The dry run is this server's preflight.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign", "adset" or "ad" - what object_id is.
object_id	text	yes		From meta_ads_list.
labels	list of text	no	none	Names to add to the labels it already has.
remove	list of text	no	none	Names to take off it. The label itself stays in the ad account.
dry_run	true or false	no	true	true = check only (default). false = change the labels.

meta_ads_create_budget_schedule

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Raise the daily budget of a Meta campaign or ad set for a period - a sale, a launch, a weekend - after which it goes back by itself. Only where a daily budget is held.

The raised budget is subject to this installation's limits exactly as a raise made with meta_ads_update_budget: the highest daily budget, the largest increase in one call and the total of the account's daily budgets. The dry run is this server's preflight; show the user the budget during the period and the most it could spend. A schedule cannot be changed or removed from here once made.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
level	text	yes		"campaign" or "adset" - whichever holds the daily budget.
object_id	text	yes		From meta_ads_list.
start_time	text	yes		When the raise starts, ISO 8601 with an offset, e.g. 2026-11-27T00:00:00+03:00. Without an offset it is read as UTC.
end_time	text	yes		When it ends.
increase_by	number	yes		How much to add to the daily budget during the period, in whole currency units of the ad account (20, not 20.50).
dry_run	true or false	no	true	true = check only (default). false = make the schedule, only after the user confirms.

Objects the arguments take

An argument whose type is a name takes an object with these fields.

Targeting

Who an ad set is shown to. Ids and keys come from meta_ads_search_targeting.

Field	Type	Required	Default	Description
countries	list of text	no		Two-letter country codes, e.g. ['KW', 'SA'].
regions	list of text	no		Region keys.
cities	list of City	no
location_types	list of one of home, recent	no	none	People who live there (home), were recently there (recent), or both (default).
excluded_countries	list of text	no
excluded_regions	list of text	no
excluded_cities	list of City	no
age_min	whole number	no	18
age_max	whole number	no	65
genders	one of all, male, female	no	"all"
locales	list of whole number	no		Language keys, e.g. Arabic and English.
detailed	list of list of Option	no		Detailed targeting. A person must match at least one option of EVERY inner list: [[a, b], [c]] is (a or b) and c.
exclude	list of Option	no		Options to leave out.
custom_audiences	list of text	no		Custom or lookalike audience ids to include, from meta_ads_list_audiences.
excluded_custom_audiences	list of text	no
placements	object	no	none	Where the ads appear, by platform: {'facebook': ['feed', 'story'], 'instagram': []}. An empty list is every position of that platform. Left out: Meta chooses (Advantage+ placements).
devices	list of one of mobile, desktop	no	none
advantage_audience	true or false	no	false	Let Meta show the ads beyond this targeting when it expects better results. Age, gender and detailed targeting then become suggestions only.

PromotedObject

Field	Type	Required	Default	Description
page_id	text	no	none
pixel_id	text	no	none
custom_event_type	text	no	none	With a pixel: e.g. LEAD, PURCHASE, COMPLETE_REGISTRATION.
application_id	text	no	none
object_store_url	text	no	none
product_set_id	text	no	none
whatsapp_phone_number	text	no	none	With destination_type WHATSAPP: which of the Page's WhatsApp numbers, digits with the country code. Left out, the number linked to the Page.

AttributionWindow

Field	Type	Required	Default	Description
event_type	one of CLICK_THROUGH, VIEW_THROUGH, ENGAGED_VIDEO_VIEW	yes
window_days	one of 1, 7	yes

FrequencyCap

Field	Type	Required	Default	Description
event	always IMPRESSIONS	no	"IMPRESSIONS"
interval_days	whole number (1 to 90)	yes
max_frequency	whole number (1 to 90)	yes

ScheduleSlot

When, within a day, the ads run.

Field	Type	Required	Default	Description
start_minute	whole number (0 to 1439)	yes		Minutes after midnight, e.g. 540 for 09:00.
end_minute	whole number (1 to 1440)	yes
days	list of whole number	yes		0 (Sunday) to 6 (Saturday).
timezone_type	one of USER, ADVERTISER	no	"USER"

BulkItem

One change to one object: a status, or a budget, bid or end time.

Field	Type	Required	Default	Description
object_id	text	yes
status	text	no	none	PAUSED or ARCHIVED.
daily_budget	number	no	none
lifetime_budget	number	no	none
bid_amount	number	no	none	Ad sets only.
end_time	text	no	none	Ad sets only, ISO 8601 with an offset.

City

Field	Type	Required	Default	Description
key	text	yes		The city's key from meta_ads_search_targeting(type='location').
radius	number	no	none	Around the city: 17-80 km or 10-50 miles.
distance_unit	one of kilometer, mile	no	"kilometer"

Option

Field	Type	Required	Default	Description
kind	text	yes		The targeting field, as the search result's kind: interests, behaviors, work_positions, work_employers, education_schools, education_majors, industries, life_events, family_statuses or income.
id	text	yes
name	text	no	none