跳轉到主要內容
POST
推廣一條現有的 Instagram 貼文以建立廣告。 此端點允許您使用自定義定位、預算和排期參數,將自然發布的貼文轉換為付費廣告。
  • 預算和出價金額使用廣告帳戶的幣別。最多保留兩位小數;對於 Meta 僅接受整數單位的幣別(CLP、COP、CRC、HUF、IDR、ISK、JPY、KRW、PYG、TWD 和 VND),請使用整數。
  • 為滿足 Instagram 的要求,廣告必須至少投放 30 小時。
  • 您可以使用 興趣端點 來查找用於定位的興趣 ID。
  • Instagram 審核並批準推廣貼文最多可能需要 24 小時。
  • 如果直接使用 socialPostId(而非 Ayrshare 的 postId),請確保它是有效的 Instagram 貼文 ID。
  • 如果在 Facebook 建立活動之後(在創意、廣告組合或廣告步驟)推廣失敗, 我們會嘗試刪除該活動。如果刪除也失敗,空活動會保留在您的廣告帳號中。 您可以在廣告管理員(Ads Manager)中找到並刪除它。
在滿足以下兩個條件之前,Meta 會拒絕建立廣告:
  • 廣告帳戶已新增付款方式。 在 Meta 的帳單和付款中新增付款方式,並將其指派給您在 accountId 中傳送的廣告帳戶。僅儲存在商家資產組合中的付款方式並不足夠。
  • 已開啟個人化廣告(歐盟、歐洲經濟區和瑞士)。 如果與您的 Facebook Page 連結的 Facebook 或 Instagram 帳戶的擁有者選擇了查看個人化程度較低的廣告,或訂閱了無廣告的 Meta 服務,Meta 將不允許該帳戶及該 Page 投放廣告。擁有者可以在帳號管理中心 → 廣告偏好設定 → 廣告體驗中改回個人化廣告或取消訂閱。瞭解詳情。

廣告目標

每條廣告都必須設定一個目標(goal)。目標決定了廣告將如何針對展示進行最佳化。
  • engagement(互動):該目標旨在提升互動,同時確保廣告觸達盡可能多的獨立使用者。 它在曝光度與互動之間取得平衡,把廣告展示給盡可能多可能與之互動的不同使用者。
  • interactions(互動動作):旨在增加廣告的互動,例如按讚、評論和分享。 Instagram 會優先將廣告展示給最有可能與之互動的使用者。
  • awareness_views(品牌認知—展示):透過最大化廣告的展示次數來提升品牌認知。 它會在預算范圍內優先盡可能多次地展示廣告,而不考慮獨立觸達。
  • awareness_audience(品牌認知—受眾):透過最大化看到廣告的獨立使用者數量來增強品牌認知。 它確保廣告觸達盡可能多的不同使用者,並最大化獨立受眾規模,而不是對同一受眾多次展示。
Instagram 廣告需要一個透過 Facebook 連結的 Instagram Business 帳戶、一個關聯的 Facebook 主頁,以及 ads_management 權限。請透過 Facebook 重新綁定以授予此權限。使用 Instagram Login 連結的帳戶無法使用這些廣告端點。媒體 ID 和 Instagram 帳戶 ID 會從您已綁定的帳戶解析取得;請勿發送 instagram_user_id。
socialPostId 選擇器也接受 Instagram 專用的別名 igPostId。fbPostId 僅適用於 Facebook。成功的響應會包含 platform: "instagram"、socialPostId 和 igPostId。

請求頭參數

請求體參數

string
此推廣請求的唯一非空鍵。使用相同的鍵重試相同的負載,可避免建立重複的廣告。以不同的負載重用該鍵,或用於 Facebook 推廣,會返回 HTTP 409。在其他任何平台上,相同的鍵會建立一個獨立的推廣。仍在處理中的請求同樣會返回 409;預留不可用時會返回 503,且不會建立廣告。
boolean
預設值:false
允許 Meta 在該活動的各廣告集之間共享預算。
string
必填
用於推廣該貼文的 Instagram 廣告帳戶 ID。可以從 廣告帳戶端點 獲取帳戶 ID。
string
必填
您的廣告名稱(顯示在 Instagram 廣告管理器中),格式為 {adName} - {postId or socialPostId} - {current date}。如果您傳送 idempotencyKey,名稱結尾還會附加 - {request reference},這是一個簡短的請求識別碼,同一金鑰的識別碼保持不變。
number
必填
最高出價金額,以廣告帳戶的幣別計,須為正數。
number
必填
每日預算,以廣告帳戶的幣別計,須為正數。Meta 可能會針對您的帳戶和目標強制執行最低限額。
string
要推廣的貼文的 Instagram 社群貼文 ID,可用於以直接在 Instagram 上建立的貼文來建立廣告。 這是 Instagram 上貼文 的 ID,而不是 Ayrshare 的 ID。如果未設定 postId,則該參數必填。
string
預設值:"engagement"
廣告的目標。可選值:engagement、interactions、awareness_views 和 awareness_audience。詳見上文 廣告目標詳細說明。
object
使用 國家代碼,以 {"countries": ["US", "CA"]} 定位目標國家。您也可以提供 regions 和 cities 陣列;參見 地區 和 城市。未指定任何國家、地區或城市的物件(例如 {})會被拒絕並傳回代碼 101;如需定位美國,請省略 locations。
string
要推廣的貼文的 Ayrshare 貼文 ID。如果未設定 socialPostId,則該參數必填。
string
預設值:"active"
廣告的狀態。可選值:active 和 paused。之後可以使用 更新廣告端點 修改廣告狀態。
object
使用 Meta Pixel 追蹤廣告。
array
向廣告 URL 添加 UTM 標簽。
例如,如果連結 URL 為 https://www.mysite.com/my-post,添加的 URL 標簽為:utm_source=ayrshare、utm_medium=social 和 utm_campaign=ayrshare-social。那麼廣告 URL 將為: https://www.mysite.com/my-post?utm_source=ayrshare&utm_medium=social&utm_campaign=ayrshare-social。
array
Meta 要求屬於 特殊廣告類別 的廣告主必須自行標識其活動類別。如果您的業務屬於其中之一,在推廣貼文時必須選擇相應的類別。支援以下取值:
  • housing(住房):推廣或直接連結到住房機會或相關服務的廣告,包括但不限於房屋或公寓的 出售/出租資訊、房主保險、按揭保險、按揭貸款、房屋維修以及房屋淨值或估價服務。
  • financial_product_services(金融產品與服務):推廣或直接連結到金融產品與服務優惠 (包括信貸)的廣告。
  • employment(就業):推廣或直接連結到就業機會的廣告,包括但不限於兼職或全職工作、 實習或專業認證專案。此類別還包括對招聘網站或招聘會、招聘聚合服務,或詳述公司福利的廣告 (無論是否有具體的職位提供)。
  • issues_elections_politics(社會議題、選舉或政治):由候選人、政治人物、政黨,或代表他們, 或與其相關的廣告,或倡導選舉結果的廣告。這也包括與任何選舉、公投或投票倡議相關的廣告, 包括「號召投票」的選舉宣傳。以及在投放地被視為政治廣告或涉及社會議題的廣告。若選擇社會議題、 選舉或政治,則必須選擇投放這些廣告的國家/地區。您必須已獲得在該指定國家/地區投放社會議題、 選舉或政治相關廣告的授權。
Meta 還需要知道特殊類別廣告投放的國家/地區。Ayrshare 從 locations 中取得這些國家/地區:您列出的國家/地區,以及每個地區和城市所屬的國家/地區。因此,鎖定英國城市的 housing 推廣會自動設定為英國,無需在請求中新增任何內容。如果未提供 locations,廣告將在美國投放,活動也會設定為美國。Meta 也為這些類別設定了每個城市周圍的最小半徑。一個半徑為 17 公里的英國城市遭到拒絕並傳回 #2909039,該錯誤要求至少 25 公里(15 英里),因此請使用 25 公里或以上。
Meta 要求廣告主必須自行標識其活動類別。 Meta 會使用人工審核和機器學習來識別此類廣告。 如果您向我們發送了錯誤的 specialAdCategories,您的廣告可能會被暫停,直到活動被調整為止。
string
從廣告中受益的個人或組織。需與 dsaPayor 一同設定。可使用 DSA 推薦端點 獲取建議。
string
為廣告付款的個人或組織。需與 dsaBeneficiary 一同設定。
string
ISO 8601 格式的結束日期和時間(必須至少在開始時間後 30 小時),例如 2025-03-01T00:00:00Z。如果未設定,廣告將無限期執行,結束日期為 ongoing(進行中)。
object
使用與 locations 相同的 countries、regions 和 cities 結構來排除位置。
string
預設值:"all"
受眾性別。可選值:all(全部)、male(男性)、female(女性)。
array
廣告的目標興趣,作為 Instagram 興趣 ID 的陣列。
number
預設值:65
廣告定位的最大年齡(預設:65)。
number
預設值:18
廣告定位的最小年齡(預設:18)。
string
ISO 8601 格式的開始日期和時間,例如 2025-03-01T00:00:00Z。如果未設定,廣告將立即開始投放。
請將範例中的 ID 替換為您自己的 ID。將 startDate 和 endDate 設定為您預期的排期;範例日期僅供參考。

總額預算

上方的請求主體會在廣告集上設定每日預算。若要使用總額預算,請改為傳送推廣請求主體的巢狀格式。 在巢狀格式中,accountId、postId(或以 socialPostId 取代 igPostId)、goal、status 和 callToAction 保留在最上層。三個物件會取代扁平格式的預算、日期和定位欄位:budget、schedule(start、end)和 targeting(locations、excludedLocations、ageMin、ageMax、genders、interests)。其餘欄位 adName、bidAmount、specialAdCategories、adSetBudgetSharingEnabled、link、tracking、urlTags、dsaBeneficiary 和 dsaPayor 則移至 platformOptions.instagram 之下。
  • budget.type:daily(預設值)或 lifetime。總額預算會在開始與結束日期之間花用,因此需要 schedule.end。若未提供,請求會遭拒絕,並回傳 400 及 code: 101。Meta 的廣告集預算共用僅適用於每日預算,因此搭配 adSetBudgetSharingEnabled: true 的總額預算同樣會遭拒絕,並回傳 code: 101。
若為總額預算,回應會新增 budgetType: "lifetime"。每日預算不會回傳 budgetType,因此若缺少此欄位,請將其視為 daily。

活動預算

若要將預算設定在活動上而非廣告集上,請在上方所示的巢狀格式中傳送 budget.level: "campaign"。此時廣告集不會有自己的預算。此設定適用於每日預算與總額預算。
  • budget.level:adSet(預設值)或 campaign。活動預算無法與 adSetBudgetSharingEnabled 搭配使用。同時傳送兩者會遭拒絕,並回傳 400 及 code: 101。
  • 若為活動預算,回應會新增 budgetLevel: "campaign"。廣告集預算不會回傳 budgetLevel,因此若缺少此欄位,請將其視為 adSet。
  • 在歷史記錄中,對於使用每日活動預算的廣告,budgetDaily 會顯示該活動的每日預算。若多則廣告共用同一個活動預算,每則廣告都會顯示整個活動預算,而非其所佔的部分。歷史記錄不會顯示總額預算,無論是設定在活動或廣告集上。一旦總額活動預算用完,在下一次夜間更新後,該活動中的每則廣告都會顯示 deliveryStatus: "COMPLETED",包括已排程或審核中的廣告。遭拒絕的廣告會維持 REJECTED。

推廣至現有的活動或廣告集

預設情況下,每次推廣都會建立自己的活動、廣告集與廣告。若要將推廣新增至您已在 Meta 中執行的活動或廣告集,請使用巢狀格式並傳送 attachTo。
  • attachTo.campaignId:推廣會在該活動內建立新的廣告集與廣告。請照常傳送 budget、targeting 與 bidAmount:這些設定會套用到新的廣告集。
  • attachTo.adSetId:推廣只會在該廣告集內建立廣告。請同時傳送 attachTo.campaignId,也就是該廣告集所屬的活動。請省略 budget、targeting 與 platformOptions.instagram.bidAmount:廣告集會保留自己的設定。傳送其中任何一項都會回傳 400 及 code: 101。
  • 活動或廣告集必須位於 accountId 所指定的廣告帳戶中,且不得屬於其他使用者的推廣。否則請求會回傳 400。Instagram 推廣也無法附加到由 Facebook 推廣建立的活動,反之亦然。
  • attachTo 無法與 budget.level: "campaign"、specialAdCategories 或 adSetBudgetSharingEnabled 搭配使用,因為這些是在新活動上設定的。傳送這些參數會回傳 code: 101。
  • 暫停或啟用推廣只會變更推廣所建立的項目:廣告,以及由推廣建立的廣告集。您在 attachTo 中指定的活動或廣告集會保留自己的狀態。只有在其上層的活動與廣告集皆為啟用狀態時,廣告才會投放。當 Ayrshare 暫停您的廣告時(例如刪除設定檔時),此規則同樣適用。
  • 如果推廣失敗,attachTo 中指定的活動或廣告集絕不會被刪除。
  • 如果您附加的廣告集位於持有預算的活動中(活動預算),歷史記錄會像回報任何使用活動預算的廣告一樣回報該推廣:budgetDaily 顯示整個活動的預算,而非該推廣所佔的部分;一旦總額活動預算用完,在下一次夜間更新後,Ayrshare 在該活動中追蹤的每則廣告都會顯示 deliveryStatus: "COMPLETED",包括已排程或審核中的廣告。遭拒絕的廣告會維持 REJECTED。

開啟對話而非連結

推廣的按鈕可以開啟與您企業的聊天,而非網頁。請使用巢狀格式並傳送 callToAction.destination,同時省略 callToAction.link。
  • 請使用 engagement 或 interactions 廣告目標。廣告會因此針對對話進行最佳化:Meta 會將其顯示給可能發起聊天的使用者。其他目標會回傳 400 及 code: 101。
  • callToAction.type 必須與目的地相符,如上表所示。接受任何大小寫。
  • callToAction.link 與 callToAction.linkTitle 無法與 destination 一起傳送,因為按鈕開啟的是聊天,而非頁面。若未使用 destination,link 仍為必填。
  • 使用者會傳訊息給與您設定檔連結的帳戶。若為 whatsapp,其 Facebook Page 必須在 Meta 中連結 WhatsApp Business 號碼。
  • destination 無法與 attachTo.adSetId 搭配使用:現有的廣告集會保留其原有的目的地。若使用 attachTo.campaignId,該活動必須具有 Meta 的 OUTCOME_ENGAGEMENT 目標;否則請求會回傳 400 及 code: 101。
  • 回應以及已推廣廣告端點會回傳包含 destination 的 callToAction。由於 Meta 對兩種目標儲存相同的設定,因此從 Meta 讀回廣告時,以 interactions 推廣的聊天按鈕可能會以 engagement 目標列出。