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
为推广帖子添加一个行动号召按钮,例如 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 会附加到该按钮链接上。允许发送不带 callToAction 的 goal: "traffic",此时会创建一条没有按钮的流量广告。您发送的 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"
}