跳转到主要内容
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 主页关联的 Facebook 或 Instagram 账户的所有者选择了查看个性化程度较低的广告,或订阅了无广告的 Meta 服务,Meta 将不允许该账户及该主页投放广告。所有者可以在账户中心 → 广告偏好 → 广告体验中改回个性化广告或取消订阅。了解详情。

广告目标

每条广告都必须设置一个目标(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 Ad Manager 中),格式为 {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 为这两种目标存储相同的设置,因此使用 interactions 推广的聊天按钮在从 Meta 读回广告时,可能会以 engagement 目标列出。