أدوات Meta Ads: التصاميم والإعلانات والترويج
في هذه الصفحة 8 أداة. هذه الصفحة مولَّدة آليًا من قائمة الأدوات في الخادم نفسه، الإصدار 0.1.0، ولا تُحرَّر باليد. أوصاف الأدوات مكتوبة للمساعد الذكي، وهي بالإنجليزية ولم تُترجم، فكل ما تحت هذه الفقرة بالإنجليزية كما يقرؤه المساعد الذكي. لا تحتاج إلى معرفة اسم أي أداة لتطلب عملًا: هذه الصفحة مرجع لمن يريد أن يعرف ما تأخذه كل أداة بالضبط. صفحة كل الأدوات تسرد الصفحات كلها.
meta_ads_list_creatives
Kind: read. It is marked as changing nothing.
List the ad creatives of a Meta ad account: what each shows (title, text, button, thumbnail) and its id, which meta_ads_create_ad and meta_ads_preview take.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
limit | whole number | no | 25 | Rows per page (1-100). |
after | text | no | none | next_after from the previous page. |
meta_ads_list_videos
Kind: read. It is marked as changing nothing.
List the videos in a Meta ad account's library, newest first, and whether Meta has finished processing each. A video uploaded by meta_ads_create_creative appears here.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
limit | whole number | no | 25 | Rows per page (1-100). |
after | text | no | none | next_after from the previous page. |
meta_ads_preview
Kind: read. It is marked as changing nothing.
Get links that show a Meta ad, or a creative, as it would appear in each placement. Show them to the user before an ad is switched on: this installation may refuse to activate an ad that the person activating it has not had previewed in the last 24 hours, and a preview from this tool is what counts.
Each format is one call to Meta, so ask for the placements the ad set uses, up to four.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
ad_id | text | no | none | The ad to preview, from meta_ads_list or meta_ads_create_ad. Or: |
creative_id | text | no | none | The creative to preview, from meta_ads_create_creative. |
ad_formats | list of text | no | none | Placements to draw. Default MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD and INSTAGRAM_STORY. Also DESKTOP_FEED_STANDARD, FACEBOOK_STORY_MOBILE, FACEBOOK_REELS_MOBILE, MARKETPLACE_MOBILE, RIGHT_COLUMN_STANDARD, INSTREAM_VIDEO_MOBILE, INSTAGRAM_REELS, INSTAGRAM_PROFILE_FEED, INSTAGRAM_EXPLORE_GRID_HOME, INSTAGRAM_SEARCH_CHAIN, MESSENGER_MOBILE_INBOX_MEDIA. |
meta_ads_list_ad_comments
Kind: read. It is marked as changing nothing.
The comments people left on a Meta ad account's ads, newest first, by the post each ad shows. Several ads that show the same post share its comments, and are listed with it.
Each comment has the shape meta_list_comments gives. To answer or hide one, pass its comment_id to meta_reply_to_comment or meta_hide_comments with the page_id or ig_account_id shown beside the post. For a regular moderation pass that remembers what was seen, use meta_list_new_comments with ad_account_id instead.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
ad_id | text | no | none | Only this ad's post. Left out, the posts of every running ad. |
include_paused | true or false | no | false | Also the ads that are paused, which keep their comments. |
posts | whole number | no | 10 | How many posts to read (1-25). Each is one call to Meta. |
limit | whole number | no | 25 | Comments per post (1-100). |
meta_ads_create_creative
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 ad creative: what an ad shows. One image or one video (media_id), or a carousel (cards), with the text, the button and where it leads - or a post that already exists (post_id, instagram_media_id), shown as it is with its likes and comments. Files come from the media library (meta_list_media, meta_add_media) and are uploaded to the ad account only when dry_run=false.
The dry run is this server's own preflight: nothing is uploaded and Meta has not seen the creative, so do not call it validated. A creative spends nothing and shows nothing until an ad is made from it (meta_ads_create_ad), and it cannot be edited afterwards, only replaced. Meta's creative enhancements (rewriting text, cropping, retouching, translating) are sent switched off.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
name | text | yes | The creative's name, seen only in Ads Manager. | |
page_id | text | yes | The Facebook Page the ad speaks as; one of the ad account's pages. | |
primary_text | text | no | none | The words above the picture. About 125 characters show before "See more". Needed unless the creative is an existing post. |
instagram_user_id | text | no | none | The Instagram account the ad speaks as on Instagram; one of the ad account's instagram_accounts. Left out, the Page is used there too. |
media_id | text | no | none | One library image (JPEG or PNG) or video. 1:1 or 4:5 suits the feed. |
thumbnail_media_id | text | no | none | With a video: a library image to show before it plays. |
vertical_media_id | text | no | none | A 9:16 file of the same kind as media_id, shown in stories and reels while media_id is shown everywhere else. |
cards | list of Card | no | none | A carousel instead of media_id: 2 to 10 cards, each with a media_id and optionally its own headline, description and link_url. |
headline | text | no | none | The bold line beside the button. |
description | text | no | none | The smaller line under the headline; not shown on Instagram. |
call_to_action | text | no | "LEARN_MORE" | The button: LEARN_MORE (default), SIGN_UP, CONTACT_US, GET_QUOTE, APPLY_NOW, BOOK_NOW, DOWNLOAD, SHOP_NOW, SUBSCRIBE, GET_OFFER, ORDER_NOW, REQUEST_TIME, SEE_MENU, WATCH_MORE or NO_BUTTON. |
link_url | text | no | none | Where the ad leads. Not needed with lead_form_id. |
url_tags | text | no | none | Tracking parameters added to the link, e.g. utm_source=meta&utm_medium=paid. |
lead_form_id | text | no | none | A lead form of the Page to open instead of a website, for an ad set optimised for LEAD_GENERATION. |
enhancements | list of text | no | none | Creative enhancements to switch on by name. Refused unless this installation allows it; leave out unless the user asked for one. |
post_id | text | no | none | A post of the Page (from meta_list_posts, or the object_story_id of meta_ads_create_dark_post) to advertise as it is. Give no text, media or link. |
instagram_media_id | text | no | none | An Instagram post of instagram_user_id to advertise as it is. |
message_destination | text | no | none | WHATSAPP, MESSENGER or INSTAGRAM_DIRECT, for an ad whose button opens a chat instead of a website. The button and the link are then set for you: give one image or video and no link_url. The Page needs a WhatsApp number linked for WHATSAPP; INSTAGRAM_DIRECT needs instagram_user_id. |
welcome_message | WelcomeMessage | no | none | With message_destination: what the chat opens with - a greeting, up to 4 ice_breakers (questions to tap), or on WhatsApp a prefilled_message. |
dry_run | true or false | no | true | true = check here without sending anything (default). false = upload the files and create it, only after the user confirms. |
meta_ads_create_ad
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 ad: one creative shown in one ad set. Always created PAUSED, so nothing is shown or spent until it is switched on with meta_ads_set_status.
The dry run is checked by Meta, including its review of the creative's text and picture, and creates nothing. After creating it, show the user meta_ads_preview before activating.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
adset_id | text | yes | The ad set it runs in, from meta_ads_list or meta_ads_create_adset. | |
creative_id | text | yes | What it shows, from meta_ads_create_creative or meta_ads_list_creatives. | |
name | text | yes | The ad's name. | |
pixel_id | text | no | none | A Meta pixel whose website events are counted for this ad. |
conversion_domain | text | no | none | The website's bare domain (example.com), which Meta requires when the campaign measures conversions with a pixel. |
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_boost_post
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Advertise a post that already exists: a Facebook Page post or an Instagram post. Makes a campaign, an ad set and an ad in one step, all PAUSED - nothing is shown or spent until the campaign is switched on with meta_ads_set_status, which checks the spending limits.
The ad is the post itself, with its likes and comments. The dry run is this server's own preflight: Meta has not checked it, so do not call it validated. Its preview shows the post, the targeting, Meta's estimate of the audience and the most the budget could spend. Amounts are in the ad account's currency units and subject to this installation's limits. If Meta refuses a step when applying, what this call had made is deleted again.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
page_id | text | yes | The Page the post is on, or the Page linked to the Instagram account. | |
targeting | Targeting | yes | Who sees it: countries (or regions, cities), ages, gender, languages, detailed targeting. Left without placements, the ad runs on the post's own platform. | |
end_time | text | no | none | When it stops, ISO 8601 with an offset. This installation may require one. |
goal | text | no | "engagement" | "engagement" (likes, comments, shares; the default), "awareness" (as many people as possible) or "video_views". |
post_id | text | no | none | A Facebook Page post, from meta_list_posts or meta_ads_create_dark_post. Or: |
instagram_user_id | text | no | none | The Instagram account, with |
instagram_media_id | text | no | none | one of its posts, from meta_list_posts. |
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. Now if left out. |
name | text | no | none | What to call the campaign, ad set and ad. A name is made if left out. |
special_ad_categories | list of text | no | none | As for meta_ads_create_campaign: ask the user rather than assuming none applies. |
dry_run | true or false | no | true | true = check here without sending anything (default). false = create it all, paused, only after the user confirms. |
meta_ads_create_dark_post
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Make a Facebook Page post that appears on no timeline and exists only to be advertised (a "dark post"). Returns its object_story_id, which meta_ads_boost_post and meta_ads_create_creative take as post_id. Use it when several ads should share one post, and so one set of likes and comments; for a single ad, meta_ads_create_creative alone is enough.
The dry run is this server's own preflight: Meta has not seen the post. It does not count as one of the day's posts, since nobody sees it until an ad shows it.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
page_id | text | yes | Facebook Page id from meta_list_accounts. | |
message | text | yes | The post text. | |
link | text | no | none | A URL to attach. Only for a text post. |
image_url | text | no | none | Public https URL of a JPEG or PNG to post as a photo. |
media_id | text | no | none | An image from the caller's library (meta_list_media). |
dry_run | true or false | no | true | true = preflight only (default). false = make it, after the user confirms. |
Objects the arguments take
An argument whose type is a name takes an object with these fields.
Card
One card of a carousel.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
media_id | text | yes | A library image or video, from meta_list_media. | |
headline | text | no | none | |
description | text | no | none | |
link_url | text | no | none | Where this card leads; the creative's link_url if left out. |
WelcomeMessage
What the chat opens with.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
greeting | text | no | none | The first message the person sees from the business. |
ice_breakers | list of IceBreaker | no | Up to 4 questions to tap. | |
prefilled_message | text | no | none | WhatsApp only: a message already typed for the person, who presses send. |
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. |
IceBreaker
A question the person can tap instead of typing.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
title | text | yes | The question, up to 80 characters. | |
response | text | no | none | Messenger and Instagram only: the automatic answer, up to 300 characters. |
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 |