curl -X POST https://api.ayrshare.com/api/ads/facebook/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": { "countries": ["US"] },
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}'
curl -X POST https://api.ayrshare.com/api/ads/facebook/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "Nurse Practitioner Hiring",
"status": "active",
"goal": "traffic",
"callToAction": {
"type": "APPLY_NOW",
"link": "https://example.com/careers/nurse-practitioner",
"linkTitle": "Apply today"
},
"specialAdCategories": ["employment"],
"minAge": 18,
"maxAge": 65,
"locations": { "countries": ["US"] },
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z"
}'
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/facebook/boost", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
})
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
API_KEY = "API_KEY"
url = "https://api.ayrshare.com/api/ads/facebook/boost"
payload = {
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}
response = requests.post(url, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json=payload)
print(response.json())
<?php
$API_KEY = "API_KEY";
$payload = [
"postId" => "1234567890",
"accountId" => "1234567890",
"adName" => "My Ad",
"status" => "active",
"goal" => "engagement",
"minAge" => 18,
"maxAge" => 65,
"locations" => ["countries" => ["US"]],
"budget" => 100,
"bidAmount" => 1,
"startDate" => "2025-03-01T00:00:00Z",
"endDate" => "2025-03-07T23:59:59Z",
"interests" => [1234567890, 1234567891]
];
$ch = curl_init("https://api.ayrshare.com/api/ads/facebook/boost");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer " . $API_KEY
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);
curl_close($ch);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string API_KEY = "API_KEY";
var payload = new
{
postId = "1234567890",
accountId = "1234567890",
adName = "My Ad",
status = "active",
goal = "engagement",
minAge = 18,
maxAge = 65,
locations = new { countries = new[] { "US" } },
budget = 100,
bidAmount = 1,
startDate = "2025-03-01T00:00:00Z",
endDate = "2025-03-07T23:59:59Z",
interests = new[] { 1234567890, 1234567891 }
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.ayrshare.com/api/ads/facebook/boost", content);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := "API_KEY"
payload := map[string]interface{}{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": map[string]interface{}{"countries": []string{"US"}},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": []int{1234567890, 1234567891},
}
jsonData, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
req, err := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/facebook/boost", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class BoostPost {
public static void main(String[] args) {
String API_KEY = "API_KEY";
String url = "https://api.ayrshare.com/api/ads/facebook/boost";
Map<String, Object> payload = new HashMap<>();
payload.put("postId", "1234567890");
payload.put("accountId", "1234567890");
payload.put("adName", "My Ad");
payload.put("status", "active");
payload.put("goal", "engagement");
payload.put("minAge", 18);
payload.put("maxAge", 65);
Map<String, Object> locations = new HashMap<>();
locations.put("countries", Arrays.asList("US"));
payload.put("locations", locations);
payload.put("budget", 100);
payload.put("bidAmount", 1);
payload.put("startDate", "2025-03-01T00:00:00Z");
payload.put("endDate", "2025-03-07T23:59:59Z");
payload.put("interests", Arrays.asList(1234567890, 1234567891));
try {
ObjectMapper objectMapper = new ObjectMapper();
String requestBody = objectMapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (IOException | InterruptedException e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
API_KEY = "API_KEY"
uri = URI.parse("https://api.ayrshare.com/api/ads/facebook/boost")
payload = {
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{API_KEY}"
request.body = payload.to_json
response = http.request(request)
puts response.body
{
"status": "success",
"adId": "120217670757750410",
"adName": "API Post - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 10,
"budget": 100,
"endDate": "2026-03-28T22:30:00Z",
"goal": {
"title": "Get More Engagement",
"description": "This goal seeks to increase engagement...",
"type": "engagement"
},
"interests": [
"6003195554098"
],
"locations": { "countries": ["US"] },
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"startDate": "2026-03-26T22:30:00Z"
}
{
"status": "success",
"adId": "120217670757750411",
"adName": "Nurse Practitioner Hiring - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 1,
"budget": 100,
"callToAction": {
"type": "APPLY_NOW",
"link": "https://example.com/careers/nurse-practitioner",
"linkTitle": "Apply today"
},
"endDate": "2025-03-07T23:59:59Z",
"goal": {
"title": "Drive Traffic",
"description": "Sends people from the boosted post to a destination off Facebook...",
"type": "traffic"
},
"locations": { "countries": ["US"] },
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"startDate": "2025-03-01T00:00:00Z"
}
{
"action": "boost post",
"status": "error",
"code": 369,
"message": "Unable to boost post. Please try again or contact us if the issue persists.",
"details": "The accountId likely does not exist. Please check the accountId and try again."
}
{
"action": "request",
"status": "error",
"code": 101,
"message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
"details": "Missing required fields: budget"
}
Facebook Ads
推廣貼文
透過將貼文提交到 Facebook 廣告平台來對其進行推廣
POST
/
ads
/
facebook
/
boost
curl -X POST https://api.ayrshare.com/api/ads/facebook/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": { "countries": ["US"] },
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}'
curl -X POST https://api.ayrshare.com/api/ads/facebook/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "Nurse Practitioner Hiring",
"status": "active",
"goal": "traffic",
"callToAction": {
"type": "APPLY_NOW",
"link": "https://example.com/careers/nurse-practitioner",
"linkTitle": "Apply today"
},
"specialAdCategories": ["employment"],
"minAge": 18,
"maxAge": 65,
"locations": { "countries": ["US"] },
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z"
}'
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/facebook/boost", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
})
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
API_KEY = "API_KEY"
url = "https://api.ayrshare.com/api/ads/facebook/boost"
payload = {
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}
response = requests.post(url, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json=payload)
print(response.json())
<?php
$API_KEY = "API_KEY";
$payload = [
"postId" => "1234567890",
"accountId" => "1234567890",
"adName" => "My Ad",
"status" => "active",
"goal" => "engagement",
"minAge" => 18,
"maxAge" => 65,
"locations" => ["countries" => ["US"]],
"budget" => 100,
"bidAmount" => 1,
"startDate" => "2025-03-01T00:00:00Z",
"endDate" => "2025-03-07T23:59:59Z",
"interests" => [1234567890, 1234567891]
];
$ch = curl_init("https://api.ayrshare.com/api/ads/facebook/boost");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer " . $API_KEY
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);
curl_close($ch);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string API_KEY = "API_KEY";
var payload = new
{
postId = "1234567890",
accountId = "1234567890",
adName = "My Ad",
status = "active",
goal = "engagement",
minAge = 18,
maxAge = 65,
locations = new { countries = new[] { "US" } },
budget = 100,
bidAmount = 1,
startDate = "2025-03-01T00:00:00Z",
endDate = "2025-03-07T23:59:59Z",
interests = new[] { 1234567890, 1234567891 }
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.ayrshare.com/api/ads/facebook/boost", content);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := "API_KEY"
payload := map[string]interface{}{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": map[string]interface{}{"countries": []string{"US"}},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": []int{1234567890, 1234567891},
}
jsonData, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
req, err := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/facebook/boost", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class BoostPost {
public static void main(String[] args) {
String API_KEY = "API_KEY";
String url = "https://api.ayrshare.com/api/ads/facebook/boost";
Map<String, Object> payload = new HashMap<>();
payload.put("postId", "1234567890");
payload.put("accountId", "1234567890");
payload.put("adName", "My Ad");
payload.put("status", "active");
payload.put("goal", "engagement");
payload.put("minAge", 18);
payload.put("maxAge", 65);
Map<String, Object> locations = new HashMap<>();
locations.put("countries", Arrays.asList("US"));
payload.put("locations", locations);
payload.put("budget", 100);
payload.put("bidAmount", 1);
payload.put("startDate", "2025-03-01T00:00:00Z");
payload.put("endDate", "2025-03-07T23:59:59Z");
payload.put("interests", Arrays.asList(1234567890, 1234567891));
try {
ObjectMapper objectMapper = new ObjectMapper();
String requestBody = objectMapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (IOException | InterruptedException e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
API_KEY = "API_KEY"
uri = URI.parse("https://api.ayrshare.com/api/ads/facebook/boost")
payload = {
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{API_KEY}"
request.body = payload.to_json
response = http.request(request)
puts response.body
{
"status": "success",
"adId": "120217670757750410",
"adName": "API Post - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 10,
"budget": 100,
"endDate": "2026-03-28T22:30:00Z",
"goal": {
"title": "Get More Engagement",
"description": "This goal seeks to increase engagement...",
"type": "engagement"
},
"interests": [
"6003195554098"
],
"locations": { "countries": ["US"] },
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"startDate": "2026-03-26T22:30:00Z"
}
{
"status": "success",
"adId": "120217670757750411",
"adName": "Nurse Practitioner Hiring - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 1,
"budget": 100,
"callToAction": {
"type": "APPLY_NOW",
"link": "https://example.com/careers/nurse-practitioner",
"linkTitle": "Apply today"
},
"endDate": "2025-03-07T23:59:59Z",
"goal": {
"title": "Drive Traffic",
"description": "Sends people from the boosted post to a destination off Facebook...",
"type": "traffic"
},
"locations": { "countries": ["US"] },
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"startDate": "2025-03-01T00:00:00Z"
}
{
"action": "boost post",
"status": "error",
"code": 369,
"message": "Unable to boost post. Please try again or contact us if the issue persists.",
"details": "The accountId likely does not exist. Please check the accountId and try again."
}
{
"action": "request",
"status": "error",
"code": 101,
"message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
"details": "Missing required fields: budget"
}
推廣一條現有的 Facebook 貼文以建立廣告。
此端點允許您使用自定義定位、預算和排期參數,將自然發布的貼文轉換為付費廣告。
- 預算和出價金額必須以美元(USD)指定,最多保留兩位小數。
- 為滿足 Facebook 的要求,廣告必須至少投放 30 小時。
- 您可以使用 興趣端點 來查找用於定位的興趣 ID。
- Facebook 審核並批準推廣貼文最多可能需要 24 小時。
- 如果直接使用
fbPostId(而非 Ayrshare 的postId),請確保它是有效的 Facebook 貼文 ID。 - 如果在 Facebook 建立活動之後(在創意、廣告組合或廣告步驟)推廣失敗, 我們會嘗試刪除該活動。如果刪除也失敗,空活動會保留在您的廣告帳號中。 您可以在廣告管理員(Ads Manager)中找到並刪除它。
廣告目標
每條廣告都必須設定一個目標(goal)。目標決定了廣告將如何針對展示進行最佳化。engagement(互動):該目標旨在提升互動,同時確保廣告觸達盡可能多的獨立使用者。 它在曝光度與互動之間取得平衡,把廣告展示給盡可能多可能與之互動的不同使用者。interactions(互動動作):旨在增加廣告的互動,例如按讚、評論和分享。 Facebook 會優先將廣告展示給最有可能與之互動的使用者。awareness_views(品牌認知—展示):透過最大化廣告的展示次數來提升品牌認知。 它會在預算范圍內優先盡可能多次地展示廣告,而不考慮獨立觸達。awareness_audience(品牌認知—受眾):透過最大化看到廣告的獨立使用者數量來增強品牌認知。 它確保廣告觸達盡可能多的不同使用者,並最大化獨立受眾規模,而不是對同一受眾多次展示。traffic(流量):將使用者從 Facebook 引導至您選擇的目的地,例如您的網站、到達頁面或職缺頁面。 Facebook 會針對連結點擊而非平台內互動進行最佳化。這是唯一支援callToAction按鈕的目標。
請求頭參數
請求體參數
string
必填
您的廣告名稱(顯示在 Facebook 廣告管理器中),格式為
{adName} - {postId or fbPostId} - {current date}。number
必填
最高出價金額,以美元計。最低出價金額為 $1.00。
number
必填
每日預算,以美元計。最低預算為 $1.00。
string
必填
要推廣的貼文的 Facebook 社群貼文 ID,可用於以直接在 Facebook 上建立的貼文來建立廣告。
這是 Facebook 上貼文 的 ID,而不是 Ayrshare 的 ID。如果未設定
postId,則該參數必填。string
預設值:"engagement"
必填
廣告的目標。可選值:
engagement、interactions、awareness_views、awareness_audience
和 traffic。詳見上文 廣告目標詳細說明。object
廣告的目標位置,採用包含陣列的物件:
countries、regions、cities。
未指定任何國家、地區或城市的物件(例如 {})會被拒絕並傳回代碼 101;如需定位美國,請省略 locations。顯示 子屬性
顯示 子屬性
array
國家代碼清單。
{
"countries": ["US", "CA"]
}
string
必填
要推廣的貼文的 Ayrshare 貼文 ID。如果未設定
fbPostId,則該參數必填。boolean
預設值:false
控制 Meta 在活動層級的廣告集預算共享。
Meta 現在要求在每個未設定活動級預算的活動上都傳遞此參數欄位,因此 Ayrshare 總會發送該欄位——為向後相容預設設為
false。設定為 true 可讓 Meta 在同一活動的其他廣告集之間共享某個廣告集最多約 20% 的預算,以最佳化整體表現。詳見 Meta 的 廣告活動組參考。object
為推廣貼文添加行動呼籲(call-to-action)按鈕,例如 Apply Now 或 Shop Now。按鈕會開啟您在
link 中提供的 URL;若使用 destination,則改為開啟 Messenger、WhatsApp 或 Instagram Direct 聊天(參見開啟對話而非連結)。{
"callToAction": {
"type": "APPLY_NOW",
"link": "https://www.mysite.com/careers/social-media-manager",
"linkTitle": "Social Media Manager"
}
}
顯示 子屬性
顯示 子屬性
string
必填
按鈕標簽。可選值:
LEARN_MORE、APPLY_NOW、SIGN_UP、SHOP_NOW、BOOK_TRAVEL、
GET_QUOTE、CONTACT_US、DOWNLOAD 和 SUBSCRIBE。輸入時不區分大小寫,因此 apply_now、Apply_Now 和 APPLY_NOW 均可接受。
若使用 destination,請改用訊息按鈕:MESSAGE_PAGE、WHATSAPP_MESSAGE 或
INSTAGRAM_MESSAGE。string
按鈕開啟的目的地。必須是絕對的
http 或 https URL。相對路徑、mailto: 連結
和格式錯誤的 URL 會被拒絕。除非設定了 destination,否則為必填。string
隨按鈕一起顯示的標題(可選)。
callToAction.link 提供目的地 URL。當 Meta 將行動呼籲以按鈕形式呈現在現有貼文上時,urlTags 會附加到該按鈕連結上。允許只使用 goal: "traffic" 而不帶 callToAction,這會建立一條沒有按鈕的流量廣告。您發送的 callToAction 會在推廣回應中原樣回傳,其中 type 會轉為大寫——參見 Post Boosted with a Call to Action 範例——之後也會由 已推廣廣告端點 在廣告上回傳。若要開啟 Messenger、WhatsApp 或 Instagram Direct 聊天而非連結,請參見開啟對話而非連結。array
向廣告 URL 添加 UTM 標簽。例如,如果連結 URL 為
{
"urlTags": ["utm_source=ayrshare", "utm_medium=social", "utm_campaign=ayrshare-social"]
}
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(金融產品與服務):推廣或直接連結到金融產品與服務優惠 (包括信貸)的廣告。financial_products_services被接受為等效拼寫,credit作為 Meta 對此類別的舊名稱同樣被接受——三者送達 Meta 時屬於同一類別,因此使用您手上已有的 任一寫法即可。employment(就業):推廣或直接連結到就業機會的廣告,包括但不限於兼職或全職工作、 實習或專業認證專案。此類別還包括對招聘網站或招聘會、招聘聚合服務,或詳述公司福利的廣告 (無論是否有具體的職位提供)。none(無):預設值。聲明該活動不屬於任何特殊廣告類別。顯式發送它等同於完全省略specialAdCategories;之所以接受此值,是為了讓總是發送該欄位的呼叫方無需特殊處理 即可表示「無類別」。issues_elections_politics(社會議題、選舉或政治):由候選人、政治人物、政黨,或代表他們, 或與其相關的廣告,或倡導選舉結果的廣告。這也包括與任何選舉、公投或投票倡議相關的廣告, 包括”號召投票”的選舉宣傳。以及在投放地被視為政治廣告或涉及社會議題的廣告。若選擇社會議題、 選舉或政治,則必須選擇投放這些廣告的國家/地區。您必須已獲得在該指定國家/地區投放社會議題、 選舉或政治相關廣告的授權。
400 及 code: 101,其中列出可接受的取值。先前無法識別的值會被悄悄捨棄,活動則以未分類的方式建立,因此一個拼寫錯誤就會讓受監管的廣告在未聲明任何類別的情況下持續投放。該錯誤訊息中的可接受取值清單以 Meta 的大寫形式書寫,並同時列出上述替代拼寫,因此其內容為 NONE, HOUSING, FINANCIAL_PRODUCTS_SERVICES, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCT_SERVICES, CREDIT。這些與此處列出的五個類別相同——FINANCIAL_PRODUCT_SERVICES 和 CREDIT 是 financial_product_services 的等效寫法,而不是額外的類別。興趣端點 會回傳完全相同的訊息。重複同一類別,或發送同一類別的兩種拼寫(例如 ["credit", "financial_product_services"]),都會被接受,並在送達 Meta 之前合併為單一類別。空值會被拒絕,並回傳 400 及 code: 101。若要查找 Meta 允許這些類別使用的興趣 ID,請將相同的值傳遞給 興趣端點。Meta 還需要知道特殊類別廣告投放的國家/地區。Ayrshare 從 locations 中取得這些國家/地區:您列出的國家/地區,以及每個地區和城市所屬的國家/地區。因此,鎖定英國城市的 housing 推廣會自動設定為英國,無需在請求中新增任何內容。如果未提供 locations,廣告將在美國投放,活動也會設定為美國。Meta 也為這些類別設定了每個城市周圍的最小半徑。一個半徑為 17 公里的英國城市遭到拒絕並傳回 #2909039,該錯誤要求至少 25 公里(15 英里),因此請使用 25 公里或以上。Meta 要求廣告主必須自行標識其活動類別。
Meta 會使用人工審核和機器学習來識別此類廣告。
如果您向我們發送了錯誤的
specialAdCategory,您的廣告可能會被暫停,直到活動被調整為止。string
ISO 8601 格式的結束日期和時間(必須至少在開始時間後 30 小時),例如
2025-03-01T00:00:00Z。如果未設定,廣告將無限期執行,結束日期為 ongoing(進行中)。object
使用一個包含
countries、regions 和 cities 陣列的物件來排除位置。顯示 子屬性
顯示 子屬性
array
要排除的國家代碼清單。
{
"countries": ["US", "CA"]
}
string
預設值:"all"
受眾性別。可選值:
all(全部)、male(男性)、female(女性)。number
預設值:65
廣告定位的最大年齡(預設:65)。
number
預設值:18
廣告定位的最小年齡(預設:18)。
string
ISO 8601 格式的開始日期和時間,例如
2025-03-01T00:00:00Z。如果未設定,廣告將立即開始投放。string
面向歐盟國家、用於合規《數字服務法》(DSA)的廣告受益人。若提供
dsaPayor 或 dsaBeneficiary 中任一個,
則必須同時設定兩者。有關更多資訊,請參閱我們的 DSA 指南。string
面向歐盟國家、用於合規《數字服務法》(DSA)的廣告付款方。若提供
dsaBeneficiary 或 dsaPayor 中任一個,
則必須同時設定兩者。活動預算
若要將預算設定在活動上而非廣告集上,請在巢狀格式中傳送budget.level: "campaign"。此時廣告集不會有自己的預算。此設定適用於每日預算與總額預算。
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "traffic",
"budget": { "amount": 50, "type": "lifetime", "level": "campaign" },
"schedule": { "start": "2026-11-01T00:00:00Z", "end": "2026-11-08T00:00:00Z" },
"platformOptions": { "facebook": { "adName": "November boost", "bidAmount": 2 } }
}
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.facebook.bidAmount:廣告集會保留自己的設定。傳送其中任何一項都會回傳400及code: 101。
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "engagement",
"attachTo": { "campaignId": "120210000000000001", "adSetId": "120210000000000002" },
"platformOptions": { "facebook": { "adName": "November boost" } }
}
- 活動或廣告集必須位於
accountId所指定的廣告帳戶中,且不得屬於其他使用者的推廣。否則請求會回傳400。Facebook 推廣也無法附加到由 Instagram 推廣建立的活動,反之亦然。 attachTo無法與budget.level: "campaign"、specialAdCategories或adSetBudgetSharingEnabled搭配使用,因為這些是在新活動上設定的。傳送這些參數會回傳code: 101。- 暫停或啟用推廣只會變更推廣所建立的項目:廣告,以及由推廣建立的廣告集。您在
attachTo中指定的活動或廣告集會保留自己的狀態。只有在其上層的活動與廣告集皆為啟用狀態時,廣告才會投放。當 Ayrshare 暫停您的廣告時(例如刪除設定檔時),此規則同樣適用。 - 如果推廣失敗,
attachTo中指定的活動或廣告集絕不會被刪除。 - 如果您附加的廣告集位於持有預算的活動中(活動預算),歷史記錄會像回報任何使用活動預算的廣告一樣回報該推廣:
budgetDaily顯示整個活動的預算,而非該推廣所佔的部分;一旦總額活動預算用完,在下一次夜間更新後,Ayrshare 在該活動中追蹤的每則廣告都會顯示deliveryStatus: "COMPLETED",包括已排程或審核中的廣告。遭拒絕的廣告會維持REJECTED。
開啟對話而非連結
推廣的按鈕可以開啟與您企業的聊天,而非網頁。請使用巢狀格式並傳送callToAction.destination,同時省略 callToAction.link。
destination | 開啟 | callToAction.type |
|---|---|---|
messenger | Messenger | MESSAGE_PAGE |
whatsapp | WHATSAPP_MESSAGE | |
instagramDm | Instagram Direct | INSTAGRAM_MESSAGE |
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "engagement",
"budget": { "amount": 20 },
"callToAction": { "type": "WHATSAPP_MESSAGE", "destination": "whatsapp" },
"platformOptions": { "facebook": { "adName": "Chat with us", "bidAmount": 2 } }
}
- 請使用
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。
curl -X POST https://api.ayrshare.com/api/ads/facebook/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": { "countries": ["US"] },
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}'
curl -X POST https://api.ayrshare.com/api/ads/facebook/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "Nurse Practitioner Hiring",
"status": "active",
"goal": "traffic",
"callToAction": {
"type": "APPLY_NOW",
"link": "https://example.com/careers/nurse-practitioner",
"linkTitle": "Apply today"
},
"specialAdCategories": ["employment"],
"minAge": 18,
"maxAge": 65,
"locations": { "countries": ["US"] },
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z"
}'
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/facebook/boost", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
})
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
API_KEY = "API_KEY"
url = "https://api.ayrshare.com/api/ads/facebook/boost"
payload = {
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}
response = requests.post(url, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json=payload)
print(response.json())
<?php
$API_KEY = "API_KEY";
$payload = [
"postId" => "1234567890",
"accountId" => "1234567890",
"adName" => "My Ad",
"status" => "active",
"goal" => "engagement",
"minAge" => 18,
"maxAge" => 65,
"locations" => ["countries" => ["US"]],
"budget" => 100,
"bidAmount" => 1,
"startDate" => "2025-03-01T00:00:00Z",
"endDate" => "2025-03-07T23:59:59Z",
"interests" => [1234567890, 1234567891]
];
$ch = curl_init("https://api.ayrshare.com/api/ads/facebook/boost");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer " . $API_KEY
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);
curl_close($ch);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string API_KEY = "API_KEY";
var payload = new
{
postId = "1234567890",
accountId = "1234567890",
adName = "My Ad",
status = "active",
goal = "engagement",
minAge = 18,
maxAge = 65,
locations = new { countries = new[] { "US" } },
budget = 100,
bidAmount = 1,
startDate = "2025-03-01T00:00:00Z",
endDate = "2025-03-07T23:59:59Z",
interests = new[] { 1234567890, 1234567891 }
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.ayrshare.com/api/ads/facebook/boost", content);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := "API_KEY"
payload := map[string]interface{}{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": map[string]interface{}{"countries": []string{"US"}},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": []int{1234567890, 1234567891},
}
jsonData, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
req, err := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/facebook/boost", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class BoostPost {
public static void main(String[] args) {
String API_KEY = "API_KEY";
String url = "https://api.ayrshare.com/api/ads/facebook/boost";
Map<String, Object> payload = new HashMap<>();
payload.put("postId", "1234567890");
payload.put("accountId", "1234567890");
payload.put("adName", "My Ad");
payload.put("status", "active");
payload.put("goal", "engagement");
payload.put("minAge", 18);
payload.put("maxAge", 65);
Map<String, Object> locations = new HashMap<>();
locations.put("countries", Arrays.asList("US"));
payload.put("locations", locations);
payload.put("budget", 100);
payload.put("bidAmount", 1);
payload.put("startDate", "2025-03-01T00:00:00Z");
payload.put("endDate", "2025-03-07T23:59:59Z");
payload.put("interests", Arrays.asList(1234567890, 1234567891));
try {
ObjectMapper objectMapper = new ObjectMapper();
String requestBody = objectMapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (IOException | InterruptedException e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
API_KEY = "API_KEY"
uri = URI.parse("https://api.ayrshare.com/api/ads/facebook/boost")
payload = {
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{API_KEY}"
request.body = payload.to_json
response = http.request(request)
puts response.body
{
"status": "success",
"adId": "120217670757750410",
"adName": "API Post - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 10,
"budget": 100,
"endDate": "2026-03-28T22:30:00Z",
"goal": {
"title": "Get More Engagement",
"description": "This goal seeks to increase engagement...",
"type": "engagement"
},
"interests": [
"6003195554098"
],
"locations": { "countries": ["US"] },
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"startDate": "2026-03-26T22:30:00Z"
}
{
"status": "success",
"adId": "120217670757750411",
"adName": "Nurse Practitioner Hiring - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 1,
"budget": 100,
"callToAction": {
"type": "APPLY_NOW",
"link": "https://example.com/careers/nurse-practitioner",
"linkTitle": "Apply today"
},
"endDate": "2025-03-07T23:59:59Z",
"goal": {
"title": "Drive Traffic",
"description": "Sends people from the boosted post to a destination off Facebook...",
"type": "traffic"
},
"locations": { "countries": ["US"] },
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"startDate": "2025-03-01T00:00:00Z"
}
{
"action": "boost post",
"status": "error",
"code": 369,
"message": "Unable to boost post. Please try again or contact us if the issue persists.",
"details": "The accountId likely does not exist. Please check the accountId and try again."
}
{
"action": "request",
"status": "error",
"code": 101,
"message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
"details": "Missing required fields: budget"
}