> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # Create messaging ad > Messaging Ads. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Creates a messaging ad that spends the given budget. validateOnly=true checks the request without acting and needs no confirmation. Creates a Meta ad that opens a chat with you on WhatsApp, Messenger or Instagram Direct when someone taps it. ### Destinations `destination` selects where the tapped ad opens a conversation: WhatsApp the Page's Messenger inbox the linked Instagram account's Direct inbox `destinations` puts two or three of them on one ad set and lets Meta pick the app per viewer. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** POST /apis/v1/ads/messaging * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/messaging` * **connectionId:** query; 必填 * **X-Aisa-Confirm:** header; 可选 * **Idempotency-Key:** header; 可选 * **Runtime 事实版本:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-ads.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "post_aisa_ads_apis_v1_ads_messaging", "method": "POST", "path": "/apis/v1/ads/messaging", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.", "in": "query", "name": "connectionId", "required": true, "schema": { "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" } }, { "description": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.", "in": "header", "name": "X-Aisa-Confirm", "required": false, "schema": { "enum": [ "spend" ], "type": "string" } }, { "description": "Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "adAccountId": "act_757082720485182", "budgetAmount": 2.61, "budgetType": "daily", "connectionId": "adc_7f3k2m9q", "creatives": [ { "objectStoryId": "811889972008357_123456789" } ], "destination": "whatsapp", "name": "WhatsApp existing post", "status": "PAUSED" }, "schema": { "additionalProperties": true, "description": "Besides the `required` list, the request must use EXACTLY ONE of these shapes: Single-creative: `headline`, `body`, and one of `imageUrl` / `video`, OR `platformPostId` / `objectStoryId` to reuse an organic post.", "properties": { "adAccountId": { "description": "Meta ad account ID, e.g. `act_123456789`.", "minLength": 1, "type": "string" }, "adSetId": { "description": "Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "type": "string" }, "adSetName": { "description": "Exact name for the ad set this request provisions. Omitted keeps ` - Ad Set`. Ignored with `adSetId`.", "maxLength": 255, "type": "string" }, "adSetStatus": { "description": "Ad-set-level status, same semantics as `POST /apis/v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it.", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "adStatus": { "description": "Request-side publish switch for `adStatus` on ad creation endpoints only (`status`, `campaignStatus` and `adSetStatus` carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase `active`/`paused`…", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "advantageAudience": { "description": "Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).", "enum": [ 0, 1 ], "type": "integer" }, "ageMax": { "maximum": 65, "minimum": 13, "type": "integer" }, "ageMin": { "maximum": 65, "minimum": 13, "type": "integer" }, "audienceExclude": { "description": "Custom or lookalike audience ids to exclude. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "audienceId": { "description": "Custom audience ID to target. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "type": "string" }, "audienceInclude": { "description": "Custom or lookalike audience ids to include. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "behaviors": { "description": "Behavior ids from /apis/v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across). TikTok: video/creator interaction categories, sent as the ad group's actions.", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "bidAmount": { "description": "Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.", "exclusiveMinimum": 0, "type": "number" }, "bidStrategy": { "description": "Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`.", "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP", "COST_CAP", "LOWEST_COST_WITH_MIN_ROAS" ], "type": "string" }, "body": { "description": "Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.", "minLength": 1, "type": "string" }, "budgetAmount": { "description": "Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.", "exclusiveMinimum": 0, "type": "number" }, "budgetLevel": { "description": "Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /apis/v1/ads/create.", "enum": [ "adset", "campaign" ], "type": "string" }, "budgetType": { "description": "Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.", "enum": [ "daily", "lifetime" ], "type": "string" }, "campaignName": { "description": "Exact name for the campaign this request provisions. Omitted keeps ` - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).", "maxLength": 255, "type": "string" }, "campaignStatus": { "description": "Campaign-level status, same semantics as `POST /apis/v1/ads/create`. Defaults to `status`. `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live).", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "carouselCards": { "description": "Messaging and CTWA only (a 400 on POST /apis/v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`.", "items": { "description": "One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own.", "properties": { "callToAction": { "description": "Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed).", "type": "string" }, "description": { "description": "Card description, under the title.", "maxLength": 255, "type": "string" }, "headline": { "description": "Card title (Meta name).", "maxLength": 255, "type": "string" }, "imageUrl": { "description": "Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly).", "format": "uri", "type": "string" }, "linkUrl": { "description": "Not accepted: a 400. The card tap opens the conversation, not a website.", "type": "string" } }, "required": [ "imageUrl" ], "type": "object" }, "maxItems": 10, "minItems": 2, "type": "array" }, "cities": { "description": "City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither.", "items": { "properties": { "distance_unit": { "enum": [ "mile", "kilometer" ], "type": "string" }, "key": { "minLength": 1, "type": "string" }, "radius": { "exclusiveMinimum": 0, "type": "number" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "connectionId": { "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.", "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" }, "countries": { "description": "ISO 3166-1 alpha-2 country codes. Defaults to `[\"US\"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.", "items": { "maxLength": 2, "minLength": 2, "type": "string" }, "type": "array" }, "countryGroups": { "description": "Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`.", "items": { "enum": [ "africa", "asia", "europe", "north_america", "south_america", "oceania", "central_america", "caribbean", "eea", "euro_area", "nafta", "mercosur", "afta", "apec", "gcc", "cisfta", "emerging_markets", "itunes_app_store", "android_free_store", "android_paid_store" ], "type": "string" }, "type": "array" }, "creativeFeatures": { "additionalProperties": { "enum": [ "OPT_IN", "OPT_OUT" ], "type": "string" }, "description": "Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT.", "type": "object" }, "creatives": { "description": "Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId reference.", "items": { "description": "Supply headline, body, and image/video; or body and carouselCards (no headline); or exactly one existing post reference. References cannot be combined with headline, body, imageUrl, video or carouselCards; welcomeMessage works on all three.", "properties": { "body": { "description": "Primary text shown above the image / video.", "minLength": 1, "type": "string" }, "carouselCards": { "description": "A 2-10 card carousel for this entry instead of `imageUrl` / `video`; `body` is required. Same rules as the top-level `carouselCards`. Carousel and single-media entries can be mixed on one ad set.", "items": { "description": "One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own.", "properties": { "callToAction": { "description": "Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed).", "type": "string" }, "description": { "description": "Card description, under the title.", "maxLength": 255, "type": "string" }, "headline": { "description": "Card title (Meta name).", "maxLength": 255, "type": "string" }, "imageUrl": { "description": "Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly).", "format": "uri", "type": "string" }, "linkUrl": { "description": "Not accepted: a 400. The card tap opens the conversation, not a website.", "type": "string" } }, "required": [ "imageUrl" ], "type": "object" }, "maxItems": 10, "minItems": 2, "type": "array" }, "creativeFeatures": { "additionalProperties": { "enum": [ "OPT_IN", "OPT_OUT" ], "type": "string" }, "description": "Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT.", "type": "object" }, "existingPostId": { "description": "Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.", "minLength": 1, "type": "string" }, "headline": { "maxLength": 255, "minLength": 1, "type": "string" }, "imageUrl": { "description": "Image asset. Mutually exclusive with this entry's `video`. Required if neither `video` nor an existing post reference is supplied.", "format": "uri", "type": "string" }, "objectStoryId": { "description": "Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields.", "pattern": "^\\d+_\\d+$", "type": "string" }, "platformPostId": { "description": "Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id.", "minLength": 1, "type": "string" }, "video": { "description": "Video creative. Mutually exclusive with this entry's `imageUrl`. Required if neither `imageUrl` nor an existing post reference is supplied.", "properties": { "id": { "description": "Reuse a video already uploaded to this ad account (list them with GET /apis/v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`.", "type": "string" }, "thumbnailUrl": { "description": "OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable).", "format": "uri", "type": "string" }, "url": { "description": "Public URL of the video to upload. Provide either `url` or `id`.", "format": "uri", "type": "string" } }, "type": "object" }, "welcomeMessage": { "description": "Custom chat welcome message for this entry: `text` plus exactly one of `prefillText` or `quickReplies` (400 otherwise). Same shape as the top-level `welcomeMessage` of the single-creative shape.", "properties": { "prefillText": { "description": "Message put into the user's text input, ready to send. Replaces Meta's default. Exactly one of prefillText or quickReplies.", "minLength": 1, "type": "string" }, "quickReplies": { "description": "Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies.", "items": { "properties": { "payload": { "maxLength": 1000, "minLength": 1, "type": "string" }, "title": { "description": "Chip label the person taps.", "maxLength": 20, "minLength": 1, "type": "string" } }, "required": [ "payload", "title" ], "type": "object" }, "maxItems": 13, "minItems": 1, "type": "array" }, "text": { "description": "Greeting shown when the chat opens. Replaces Meta's default.", "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" } }, "type": "object" }, "minItems": 1, "type": "array" }, "currency": { "description": "ISO 4217 currency code matching the ad account's currency (e.g. `USD`).", "maxLength": 3, "minLength": 3, "type": "string" }, "customLocations": { "description": "Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.", "items": { "properties": { "address": { "type": "string" }, "distanceUnit": { "enum": [ "mile", "kilometer" ], "type": "string" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" }, "name": { "type": "string" }, "radius": { "exclusiveMinimum": 0, "type": "number" } }, "required": [ "distanceUnit", "latitude", "longitude", "radius" ], "type": "object" }, "type": "array" }, "description": { "description": "Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed.", "maxLength": 255, "minLength": 1, "type": "string" }, "destination": { "description": "Where the conversation opens when the ad is tapped. Set this OR `destinations`, not both.", "enum": [ "whatsapp", "messenger", "instagram_direct" ], "type": "string" }, "destinations": { "description": "Two or three messaging apps on ONE ad set, like Ads Manager's \"all messaging apps\". Set this OR `destination`, not both. The ad set gets Meta's combined destination_type (e.g.", "items": { "enum": [ "whatsapp", "messenger", "instagram_direct" ], "type": "string" }, "maxItems": 3, "minItems": 2, "type": "array", "uniqueItems": true }, "dsaBeneficiary": { "description": "Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26).", "maxLength": 100, "type": "string" }, "dsaPayor": { "description": "Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.", "maxLength": 100, "type": "string" }, "endDate": { "description": "ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.", "type": "string" }, "excludedLocations": { "additionalProperties": true, "description": "Geo to exclude, same shape as POST /apis/v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).", "type": "object" }, "existingCampaignId": { "description": "Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "pattern": "^\\d+$", "type": "string" }, "existingPostId": { "description": "Alias of platformPostId, kept for existing callers. Sending both with different values is a 400.", "minLength": 1, "type": "string" }, "gender": { "description": "Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.", "enum": [ "all", "male", "female" ], "type": "string" }, "headline": { "description": "Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.", "maxLength": 255, "minLength": 1, "type": "string" }, "imageUrl": { "description": "Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.", "format": "uri", "type": "string" }, "incomeTier": { "description": "Normalized household-income tier, same as POST /apis/v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.", "enum": [ "top_5", "top_10", "top_10_25", "top_25_50" ], "type": "string" }, "interests": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "languages": { "description": "Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants (\"en\" = all English), a region-qualified code a specific one (\"en_GB\", \"pt_BR\"); unknown codes are rejected.", "items": { "type": "string" }, "type": "array" }, "metros": { "description": "DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).", "items": { "properties": { "key": { "minLength": 1, "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "name": { "description": "Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a \" #N\" suffix (1-indexed) so Ads Manager shows them as a numbered batch.", "minLength": 1, "type": "string" }, "neighborhoods": { "description": "Meta neighborhood keys (from GET /apis/v1/ads/targeting/search).", "items": { "properties": { "key": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "objectStoryId": { "description": "Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields.", "pattern": "^\\d+_\\d+$", "type": "string" }, "objective": { "description": "Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.", "enum": [ "OUTCOME_ENGAGEMENT", "OUTCOME_SALES", "OUTCOME_LEADS" ], "type": "string" }, "optimizeCardOrder": { "description": "Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. `false`: keeps the cards in the order given.", "type": "boolean" }, "pageId": { "description": "Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages.", "type": "string" }, "placementAssets": { "description": "A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (`adSetId`).", "properties": { "defaultImageUrl": { "description": "Image mode. Catch-all image for any placement no rule matches. Required in image mode (Meta mandates a default rule).", "format": "uri", "type": "string" }, "defaultThumbnailUrl": { "description": "Video mode (optional). Poster image for the default video; Meta auto-generates one when omitted.", "format": "uri", "type": "string" }, "defaultVideoUrl": { "description": "Video mode. Catch-all video for any placement no rule matches. Required in video mode.", "format": "uri", "type": "string" }, "rules": { "description": "One entry per placement group you want to pin a specific asset to.", "items": { "properties": { "body": { "description": "One primary text pinned to this rule. Omit to inherit the top-level body.", "minLength": 1, "type": "string" }, "description": { "description": "One link description pinned to this rule. Omit to inherit the top-level description.", "maxLength": 255, "minLength": 1, "type": "string" }, "headline": { "description": "One headline pinned to this rule. Omit to inherit the top-level headline.", "maxLength": 255, "minLength": 1, "type": "string" }, "imageUrl": { "description": "Image mode. The image to deliver for this rule's placements.", "format": "uri", "type": "string" }, "placements": { "description": "Placements this asset is pinned to. At least one field must be set (an empty rule is invalid; that role is served by the default asset). Same enums as the top-level `placements` object.", "properties": { "audienceNetworkPositions": { "items": { "enum": [ "classic", "rewarded_video" ], "type": "string" }, "type": "array" }, "devicePlatforms": { "items": { "enum": [ "mobile", "desktop" ], "type": "string" }, "type": "array" }, "facebookPositions": { "items": { "enum": [ "feed", "right_hand_column", "marketplace", "story", "search", "instream_video", "facebook_reels", "facebook_reels_overlay", "profile_feed", "notification" ], "type": "string" }, "type": "array" }, "instagramPositions": { "items": { "enum": [ "stream", "story", "explore", "explore_home", "reels", "profile_feed", "ig_search", "profile_reels" ], "type": "string" }, "type": "array" }, "messengerPositions": { "items": { "enum": [ "messenger_home", "sponsored_messages", "story" ], "type": "string" }, "type": "array" }, "publisherPlatforms": { "items": { "enum": [ "facebook", "instagram", "threads", "messenger", "audience_network", "whatsapp", "meta" ], "type": "string" }, "type": "array" }, "threadsPositions": { "items": { "enum": [ "threads_stream" ], "type": "string" }, "type": "array" }, "whatsappPositions": { "items": { "enum": [ "status" ], "type": "string" }, "type": "array" } }, "type": "object" }, "thumbnailUrl": { "description": "Video mode (optional). Poster image for this rule's video; auto-generated when omitted.", "format": "uri", "type": "string" }, "videoUrl": { "description": "Video mode. The video to deliver for this rule's placements.", "format": "uri", "type": "string" } }, "required": [ "placements" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "placements": { "description": "Manual ad placements on the shared ad set. Omit for automatic placements.", "properties": { "audienceNetworkPositions": { "items": { "enum": [ "classic", "rewarded_video" ], "type": "string" }, "type": "array" }, "devicePlatforms": { "description": "Restrict by device. Omit to deliver on both mobile and desktop.", "items": { "enum": [ "mobile", "desktop" ], "type": "string" }, "type": "array" }, "facebookPositions": { "items": { "enum": [ "feed", "right_hand_column", "marketplace", "story", "search", "instream_video", "facebook_reels", "facebook_reels_overlay", "profile_feed", "notification" ], "type": "string" }, "type": "array" }, "instagramPositions": { "items": { "enum": [ "stream", "story", "explore", "explore_home", "reels", "profile_feed", "ig_search", "profile_reels" ], "type": "string" }, "type": "array" }, "messengerPositions": { "items": { "enum": [ "messenger_home", "sponsored_messages", "story" ], "type": "string" }, "type": "array" }, "publisherPlatforms": { "description": "Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here.", "items": { "enum": [ "facebook", "instagram", "threads", "messenger", "audience_network", "whatsapp", "meta" ], "type": "string" }, "type": "array" }, "threadsPositions": { "items": { "enum": [ "threads_stream" ], "type": "string" }, "type": "array" }, "whatsappPositions": { "items": { "enum": [ "status" ], "type": "string" }, "type": "array" } }, "type": "object" }, "places": { "description": "Meta place keys (from GET /apis/v1/ads/targeting/search).", "items": { "properties": { "key": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "platformPostId": { "description": "Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id.", "minLength": 1, "type": "string" }, "rawTargeting": { "additionalProperties": true, "description": "Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /apis/v1/ads/create does.", "type": "object" }, "regionalRegulatedCategories": { "description": "Meta only. Regional regulation categories required when the ad set targets certain countries (e.g.", "items": { "type": "string" }, "type": "array" }, "regionalRegulationIdentities": { "additionalProperties": { "type": [ "string", "integer" ] }, "description": "Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.", "type": "object" }, "regions": { "description": "Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /apis/v1/ads/targeting/search?type=region).", "items": { "properties": { "key": { "minLength": 1, "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "roasAverageFloor": { "description": "Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.", "exclusiveMinimum": 0, "type": "number" }, "savedTargetingId": { "description": "ID of a saved_targeting audience (POST /apis/v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "type": "string" }, "specialAdCategories": { "description": "Meta special ad categories on the new campaign.", "items": { "enum": [ "HOUSING", "EMPLOYMENT", "CREDIT", "ISSUES_ELECTIONS_POLITICS", "FINANCIAL_PRODUCTS_SERVICES", "ONLINE_GAMBLING_AND_GAMING" ], "type": "string" }, "type": "array" }, "specialAdCategoryCountry": { "description": "Countries the special ad category applies to. Requires specialAdCategories.", "items": { "type": "string" }, "type": "array" }, "startDate": { "description": "When the ad set starts delivering. ISO 8601 date or date-time.", "type": "string" }, "status": { "description": "Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "targeting": { "description": "Normalized, platform-agnostic ad-targeting spec. Every field is optional; an empty object targets the platform's default broadest audience.", "properties": { "ageMax": { "description": "Maximum age. Same per-platform application and clamping as ageMin.", "maximum": 100, "minimum": 13, "type": "integer" }, "ageMin": { "description": "Minimum age. Applied on Meta, TikTok, Pinterest, LinkedIn, X and Google Search/Display (Google excludes the age ranges outside the request). Rejected with 400 on OpenAI, Reddit and Google Performance Max / Demand Gen.", "maximum": 100, "minimum": 13, "type": "integer" }, "audienceExclude": { "description": "Platform audience IDs to exclude; same ID formats as audienceInclude. Not supported on OpenAI (400). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "items": { "type": "string" }, "type": "array" }, "audienceInclude": { "description": "Platform audience IDs to include, as returned by GET /apis/v1/ads/audiences: Meta: custom audience ids. TikTok: audience ids. Pinterest: customer list ids. LinkedIn: segment ids (the platformAudienceId from GET /apis/v1/ads/audiences). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "items": { "type": "string" }, "type": "array" }, "behaviors": { "description": "Behaviour entities from /apis/v1/ads/targeting/search?dimension=behavior (Meta, TikTok and LinkedIn). On TikTok they target people who, in the picked categories:", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "cities": { "description": "City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits; both must be set together or both omitted. `radius` is only honoured on platforms whose capability map allows city radius (Meta).", "items": { "oneOf": [ { "type": "string" }, { "properties": { "distanceUnit": { "description": "Required if radius is set.", "enum": [ "mile", "kilometer" ], "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "radius": { "description": "Radius around the city. Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch.", "type": "number" } }, "required": [ "key" ], "type": "object" } ] }, "type": "array" }, "communities": { "description": "Reddit only (400 elsewhere). Subreddits to target, by name, with or without the `r/` prefix (e.g. `['marketing', 'r/startups']`), as returned by /apis/v1/ads/targeting/search?dimension=community.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "companySizes": { "description": "LinkedIn B2B only. Single-letter size codes (A to I), or the full urn:li:staffCountRange:* URN from /apis/v1/ads/targeting/search?dimension=companySize.", "items": { "type": "string" }, "type": "array" }, "conversationKeywords": { "description": "Reddit only (400 elsewhere). Keywords that place the ad in Reddit conversations about them, as returned by /apis/v1/ads/targeting/search?dimension=conversationKeyword.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "countries": { "description": "ISO 3166-1 alpha-2 country codes (e.g. ['US']).", "items": { "type": "string" }, "type": "array" }, "countryGroups": { "description": "Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`.", "items": { "enum": [ "africa", "asia", "europe", "north_america", "south_america", "oceania", "central_america", "caribbean", "eea", "euro_area", "nafta", "mercosur", "afta", "apec", "gcc", "cisfta", "emerging_markets", "itunes_app_store", "android_free_store", "android_paid_store" ], "type": "string" }, "type": "array" }, "customLocations": { "description": "Point-radius (lat/lng) targeting (Meta custom_locations / Google proximity). Honoured on Meta and Google; ignored on platforms without radius support.", "items": { "properties": { "address": { "description": "Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location.", "type": "string" }, "distanceUnit": { "enum": [ "mile", "kilometer" ], "type": "string" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" }, "name": { "type": "string" }, "radius": { "description": "Positive radius around the point.", "type": "number" } }, "required": [ "distanceUnit", "latitude", "longitude", "radius" ], "type": "object" }, "type": "array" }, "excludedCommunities": { "description": "Reddit only (400 elsewhere). Subreddits to exclude, named like `communities`.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "excludedConversationKeywords": { "description": "Reddit only (400 elsewhere). Conversation keywords to keep the ad away from.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "excludedLocations": { "description": "Geo to exclude from the audience. Mirrors the inclusion geo shape. Meta (excluded_geo_locations): excluded cities can carry a radius catchment, and excluded custom (lat/lng) pins are supported.", "properties": { "cities": { "description": "Cities to exclude. Optional `radius` + `distanceUnit` exclude a catchment around the city (both must be set together or both omitted); Meta honours the radius on excluded cities.", "items": { "properties": { "distanceUnit": { "description": "Required if radius is set.", "enum": [ "mile", "kilometer" ], "type": "string" }, "key": { "type": "string" }, "radius": { "description": "Radius around the excluded city. Requires distanceUnit.", "type": "number" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "countries": { "items": { "type": "string" }, "type": "array" }, "countryGroups": { "description": "Meta only. Continents and trade blocs to exclude (`excluded_geo_locations.country_groups`).", "items": { "enum": [ "africa", "asia", "europe", "north_america", "south_america", "oceania", "central_america", "caribbean", "eea", "euro_area", "nafta", "mercosur", "afta", "apec", "gcc", "cisfta", "emerging_markets", "itunes_app_store", "android_free_store", "android_paid_store" ], "type": "string" }, "type": "array" }, "customLocations": { "description": "Point-radius (lat/lng) pins to exclude (Meta excluded_geo_locations.custom_locations). Mirrors the inclusion customLocations shape.", "items": { "properties": { "address": { "description": "Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location.", "type": "string" }, "distanceUnit": { "enum": [ "mile", "kilometer" ], "type": "string" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" }, "name": { "type": "string" }, "radius": { "description": "Positive radius around the point.", "type": "number" } }, "required": [ "distanceUnit", "latitude", "longitude", "radius" ], "type": "object" }, "type": "array" }, "neighborhoods": { "description": "Named neighbourhood areas to exclude. `key` from /apis/v1/ads/targeting/search.", "items": { "properties": { "key": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "places": { "description": "Named points of interest to exclude. `key` from /apis/v1/ads/targeting/search.", "items": { "properties": { "key": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "regions": { "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "zips": { "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" } }, "type": "object" }, "gender": { "description": "Restrict by gender. 'all' (default) targets everyone.", "enum": [ "all", "male", "female" ], "type": "string" }, "incomeTier": { "description": "Normalized household-income tier (ZIP/percentile based). Meta and TikTok express all four. Google maps only `top_10` (its INCOME_RANGE_90_UP); other tiers on Google, and any income tier on LinkedIn / X / Pinterest, are rejected.", "enum": [ "top_5", "top_10", "top_10_25", "top_25_50" ], "type": "string" }, "industries": { "description": "LinkedIn B2B only. Industry URN id fragments, or the full urn:li:industry:* URN from /apis/v1/ads/targeting/search?dimension=industry.", "items": { "type": "string" }, "type": "array" }, "interests": { "description": "Interest entities from /apis/v1/ads/targeting/search?dimension=interest. Each carries the platform's opaque id.", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "jobFunctions": { "description": "LinkedIn B2B only. Function URN id fragments, or the full urn:li:function:* URN from /apis/v1/ads/targeting/search?dimension=jobFunction.", "items": { "type": "string" }, "type": "array" }, "languages": { "description": "Language codes restricting the audience by language. Applied on Meta, Google, TikTok, LinkedIn, X, Pinterest and Reddit; rejected with 400 on OpenAI. A code the platform cannot target returns 400 listing the ones it can.", "items": { "type": "string" }, "type": "array" }, "metros": { "description": "DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`).", "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "regions": { "description": "Region/state targeting. `key` is the platform location ID from /apis/v1/ads/targeting/search?dimension=geo&geoType=region. An entry may also be that id as a plain string (`\"20321\"` is `{ key: \"20321\" }`).", "items": { "oneOf": [ { "type": "string" }, { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" } ] }, "type": "array" }, "seniorities": { "description": "LinkedIn B2B only. Seniority URN id fragments, or the full urn:li:seniority:* URN from /apis/v1/ads/targeting/search?dimension=seniority.", "items": { "type": "string" }, "type": "array" }, "skills": { "description": "LinkedIn B2B only. Member skills (e.g. Python, Recruiting): skill URN id fragments, or the full urn:li:skill:* URN from /apis/v1/ads/targeting/search?dimension=skill. Values are ORed; the facet is ANDed with the other facets.", "items": { "type": "string" }, "type": "array" }, "userDevice": { "description": "Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting.", "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" }, "userOs": { "description": "Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting.", "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" }, "workEmployers": { "description": "Meta only. Employer entities from /apis/v1/ads/targeting/search?dimension=workEmployer.", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "workIndustries": { "description": "Meta only. Work-industry entities from /apis/v1/ads/targeting/search?dimension=workIndustry. Not interchangeable with the LinkedIn `industries` URN fragments.", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "workPositions": { "description": "Meta only. Job title entities from /apis/v1/ads/targeting/search?dimension=workPosition. Not interchangeable with the LinkedIn `jobTitles` URN fragments.", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "zips": { "description": "Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`). Supported on Meta, Google, TikTok, Pinterest, X.", "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" } }, "type": "object" }, "tracking": { "description": "Ad tracking. Meta, plus `urlTags` on ChatGPT (OpenAI) and `pixelId` on Reddit. Meta: attaches pixel measurement to the ad regardless of the optimization goal (the \"Website events\" tracking row in Ads Manager).", "properties": { "pixelId": { "description": "Meta Pixel ID to attach for offsite-conversion measurement, or the Reddit pixel of the new ad group.", "type": "string" }, "urlTags": { "description": "Click-URL params. Meta: stored on the creative as `url_tags` and returned by GET /apis/v1/ads/{adId}/tracking-tags.", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" }, "type": "array" } }, "type": "object" }, "userDevice": { "description": "Meta `user_device`.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "userOs": { "description": "Meta `user_os`, e.g. [\"iOS_ver_14.0_and_above\"].", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "validateOnly": { "description": "Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with `adSetId`). Nothing is uploaded, created or stored; media is checked by URL.", "type": "boolean" }, "video": { "description": "Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.", "properties": { "id": { "description": "Reuse a video already uploaded to this ad account (list them with GET /apis/v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`.", "type": "string" }, "thumbnailUrl": { "description": "OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable).", "format": "uri", "type": "string" }, "url": { "description": "Public URL of the video to upload. Provide either `url` or `id`.", "format": "uri", "type": "string" } }, "type": "object" }, "welcomeMessage": { "description": "Custom chat welcome message (Meta's `page_welcome_message`, \"Mensaje de bienvenida\" / \"Mensaje predefinido\" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.", "properties": { "prefillText": { "description": "Message put into the user's text input, ready to send. Replaces Meta's default (\"Hi! I want more info.\"). Lets one ad steer the opening message toward what it promotes (e.g. a specific product). Exactly one of prefillText or quickReplies.", "minLength": 1, "type": "string" }, "quickReplies": { "description": "Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies. Put your own campaign or ad key in each payload.", "items": { "properties": { "payload": { "maxLength": 1000, "minLength": 1, "type": "string" }, "title": { "description": "Chip label the person taps.", "maxLength": 20, "minLength": 1, "type": "string" } }, "required": [ "payload", "title" ], "type": "object" }, "maxItems": 13, "minItems": 1, "type": "array" }, "text": { "description": "Greeting shown when the chat opens. Replaces Meta's default (\"Hi! Can we help you?\").", "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" }, "whatsappPhoneNumber": { "description": "WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. Sent to the creative CTA and, when creating a new ad set, its promoted_object.", "pattern": "^\\+[1-9]\\d{6,14}$", "type": "string" }, "workEmployers": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "workIndustries": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "workPositions": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "workflowId": { "description": "A workflow in the ad account's profile, stored on the ad. 404 when no such workflow exists in the profile.", "pattern": "^[a-fA-F0-9]{24}$", "type": "string" }, "zips": { "description": "ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /apis/v1/ads/targeting/search.", "items": { "properties": { "key": { "minLength": 1, "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" } }, "required": [ "adAccountId", "name" ], "type": "object" } } }, "required": true }, "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-ads.json POST /apis/v1/ads/messaging openapi: 3.1.0 info: description: '' title: AIsa Ads version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:ba353f59e89e1ebabe0e301d8ef57d3cbfa6bb406a8c591ee9c3833d64b60520 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-ads x-aisa-catalogs: aisa-ads: title: AIsa Ads description: '' x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/ads/messaging: post: summary: Create messaging ad description: >- Messaging Ads. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Creates a messaging ad that spends the given budget. validateOnly=true checks the request without acting and needs no confirmation. Creates a Meta ad that opens a chat with you on WhatsApp, Messenger or Instagram Direct when someone taps it. ### Destinations `destination` selects where the tapped ad opens a conversation: WhatsApp the Page's Messenger inbox the linked Instagram account's Direct inbox `destinations` puts two or three of them on one ad set and lets Meta pick the app per viewer. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: post_aisa_ads_apis_v1_ads_messaging parameters: - description: >- The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead. in: query name: connectionId required: true schema: pattern: ^adc_[0-9A-Za-z]+$ type: string - description: >- Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform. in: header name: X-Aisa-Confirm required: false schema: enum: - spend type: string - description: >- Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you. in: header name: Idempotency-Key required: false schema: maxLength: 191 minLength: 1 type: string requestBody: content: application/json: example: adAccountId: act_757082720485182 budgetAmount: 2.61 budgetType: daily connectionId: adc_7f3k2m9q creatives: - objectStoryId: 811889972008357_123456789 destination: whatsapp name: WhatsApp existing post status: PAUSED schema: additionalProperties: true description: >- Besides the `required` list, the request must use EXACTLY ONE of these shapes: Single-creative: `headline`, `body`, and one of `imageUrl` / `video`, OR `platformPostId` / `objectStoryId` to reuse an organic post. properties: adAccountId: description: Meta ad account ID, e.g. `act_123456789`. minLength: 1 type: string adSetId: description: >- Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. type: string adSetName: description: >- Exact name for the ad set this request provisions. Omitted keeps ` - Ad Set`. Ignored with `adSetId`. maxLength: 255 type: string adSetStatus: description: >- Ad-set-level status, same semantics as `POST /apis/v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. enum: - ACTIVE - PAUSED type: string adStatus: description: >- Request-side publish switch for `adStatus` on ad creation endpoints only (`status`, `campaignStatus` and `adSetStatus` carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase `active`/`paused`… enum: - ACTIVE - PAUSED type: string advantageAudience: description: >- Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it). enum: - 0 - 1 type: integer ageMax: maximum: 65 minimum: 13 type: integer ageMin: maximum: 65 minimum: 13 type: integer audienceExclude: description: >- Custom or lookalike audience ids to exclude. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. items: type: string minItems: 1 type: array audienceId: description: >- Custom audience ID to target. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. type: string audienceInclude: description: >- Custom or lookalike audience ids to include. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. items: type: string minItems: 1 type: array behaviors: description: >- Behavior ids from /apis/v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across). TikTok: video/creator interaction categories, sent as the ad group's actions. items: properties: id: type: string name: type: string required: - id type: object type: array bidAmount: description: >- Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise. exclusiveMinimum: 0 type: number bidStrategy: description: >- Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`. enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string body: description: >- Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`. minLength: 1 type: string budgetAmount: description: >- Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget. exclusiveMinimum: 0 type: number budgetLevel: description: >- Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /apis/v1/ads/create. enum: - adset - campaign type: string budgetType: description: >- Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`. enum: - daily - lifetime type: string campaignName: description: >- Exact name for the campaign this request provisions. Omitted keeps ` - Campaign`. Ignored with `adSetId` (the ad set already has a campaign). maxLength: 255 type: string campaignStatus: description: >- Campaign-level status, same semantics as `POST /apis/v1/ads/create`. Defaults to `status`. `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). enum: - ACTIVE - PAUSED type: string carouselCards: description: >- Messaging and CTWA only (a 400 on POST /apis/v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. items: description: >- One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own. properties: callToAction: description: >- Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed). type: string description: description: Card description, under the title. maxLength: 255 type: string headline: description: Card title (Meta name). maxLength: 255 type: string imageUrl: description: >- Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly). format: uri type: string linkUrl: description: >- Not accepted: a 400. The card tap opens the conversation, not a website. type: string required: - imageUrl type: object maxItems: 10 minItems: 2 type: array cities: description: >- City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. items: properties: distance_unit: enum: - mile - kilometer type: string key: minLength: 1 type: string radius: exclusiveMinimum: 0 type: number required: - key type: object type: array connectionId: description: >- The ads connection (adc_...), when not sent as the connectionId query parameter. pattern: ^adc_[0-9A-Za-z]+$ type: string countries: description: >- ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied. items: maxLength: 2 minLength: 2 type: string type: array countryGroups: description: >- Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`. items: enum: - africa - asia - europe - north_america - south_america - oceania - central_america - caribbean - eea - euro_area - nafta - mercosur - afta - apec - gcc - cisfta - emerging_markets - itunes_app_store - android_free_store - android_paid_store type: string type: array creativeFeatures: additionalProperties: enum: - OPT_IN - OPT_OUT type: string description: >- Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. type: object creatives: description: >- Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId reference. items: description: >- Supply headline, body, and image/video; or body and carouselCards (no headline); or exactly one existing post reference. References cannot be combined with headline, body, imageUrl, video or carouselCards; welcomeMessage works on all three. properties: body: description: Primary text shown above the image / video. minLength: 1 type: string carouselCards: description: >- A 2-10 card carousel for this entry instead of `imageUrl` / `video`; `body` is required. Same rules as the top-level `carouselCards`. Carousel and single-media entries can be mixed on one ad set. items: description: >- One card of a messaging ad carousel (Meta link_data.child_attachments). Every card opens the same conversation, so a card has no link of its own. properties: callToAction: description: >- Optional. Must equal the destination's messaging call to action (WHATSAPP_MESSAGE for whatsapp, MESSAGE_PAGE for messenger, INSTAGRAM_MESSAGE for instagram_direct; with `destinations` the first one listed). type: string description: description: Card description, under the title. maxLength: 255 type: string headline: description: Card title (Meta name). maxLength: 255 type: string imageUrl: description: >- Card image. Uploaded to the ad account and sent as the card image_hash (by URL on validateOnly). format: uri type: string linkUrl: description: >- Not accepted: a 400. The card tap opens the conversation, not a website. type: string required: - imageUrl type: object maxItems: 10 minItems: 2 type: array creativeFeatures: additionalProperties: enum: - OPT_IN - OPT_OUT type: string description: >- Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. type: object existingPostId: description: >- Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. minLength: 1 type: string headline: maxLength: 255 minLength: 1 type: string imageUrl: description: >- Image asset. Mutually exclusive with this entry's `video`. Required if neither `video` nor an existing post reference is supplied. format: uri type: string objectStoryId: description: >- Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. pattern: ^\d+_\d+$ type: string platformPostId: description: >- Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id. minLength: 1 type: string video: description: >- Video creative. Mutually exclusive with this entry's `imageUrl`. Required if neither `imageUrl` nor an existing post reference is supplied. properties: id: description: >- Reuse a video already uploaded to this ad account (list them with GET /apis/v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`. type: string thumbnailUrl: description: >- OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable). format: uri type: string url: description: >- Public URL of the video to upload. Provide either `url` or `id`. format: uri type: string type: object welcomeMessage: description: >- Custom chat welcome message for this entry: `text` plus exactly one of `prefillText` or `quickReplies` (400 otherwise). Same shape as the top-level `welcomeMessage` of the single-creative shape. properties: prefillText: description: >- Message put into the user's text input, ready to send. Replaces Meta's default. Exactly one of prefillText or quickReplies. minLength: 1 type: string quickReplies: description: >- Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies. items: properties: payload: maxLength: 1000 minLength: 1 type: string title: description: Chip label the person taps. maxLength: 20 minLength: 1 type: string required: - payload - title type: object maxItems: 13 minItems: 1 type: array text: description: >- Greeting shown when the chat opens. Replaces Meta's default. minLength: 1 type: string required: - text type: object type: object minItems: 1 type: array currency: description: >- ISO 4217 currency code matching the ad account's currency (e.g. `USD`). maxLength: 3 minLength: 3 type: string customLocations: description: >- Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required. items: properties: address: type: string distanceUnit: enum: - mile - kilometer type: string latitude: maximum: 90 minimum: -90 type: number longitude: maximum: 180 minimum: -180 type: number name: type: string radius: exclusiveMinimum: 0 type: number required: - distanceUnit - latitude - longitude - radius type: object type: array description: description: >- Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. maxLength: 255 minLength: 1 type: string destination: description: >- Where the conversation opens when the ad is tapped. Set this OR `destinations`, not both. enum: - whatsapp - messenger - instagram_direct type: string destinations: description: >- Two or three messaging apps on ONE ad set, like Ads Manager's "all messaging apps". Set this OR `destination`, not both. The ad set gets Meta's combined destination_type (e.g. items: enum: - whatsapp - messenger - instagram_direct type: string maxItems: 3 minItems: 2 type: array uniqueItems: true dsaBeneficiary: description: >- Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). maxLength: 100 type: string dsaPayor: description: >- Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor. maxLength: 100 type: string endDate: description: >- ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`. type: string excludedLocations: additionalProperties: true description: >- Geo to exclude, same shape as POST /apis/v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations). type: object existingCampaignId: description: >- Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. pattern: ^\d+$ type: string existingPostId: description: >- Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. minLength: 1 type: string gender: description: >- Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`. enum: - all - male - female type: string headline: description: >- Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference. maxLength: 255 minLength: 1 type: string imageUrl: description: >- Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied. format: uri type: string incomeTier: description: >- Normalized household-income tier, same as POST /apis/v1/ads/create. Incompatible with housing, employment and credit specialAdCategories. enum: - top_5 - top_10 - top_10_25 - top_25_50 type: string interests: items: properties: id: type: string name: type: string required: - id type: object type: array languages: description: >- Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"); unknown codes are rejected. items: type: string type: array metros: description: >- DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`). items: properties: key: minLength: 1 type: string name: type: string required: - key type: object type: array name: description: >- Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch. minLength: 1 type: string neighborhoods: description: >- Meta neighborhood keys (from GET /apis/v1/ads/targeting/search). items: properties: key: type: string required: - key type: object type: array objectStoryId: description: >- Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. pattern: ^\d+_\d+$ type: string objective: description: >- Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing. enum: - OUTCOME_ENGAGEMENT - OUTCOME_SALES - OUTCOME_LEADS type: string optimizeCardOrder: description: >- Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. `false`: keeps the cards in the order given. type: boolean pageId: description: >- Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. type: string placementAssets: description: >- A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (`adSetId`). properties: defaultImageUrl: description: >- Image mode. Catch-all image for any placement no rule matches. Required in image mode (Meta mandates a default rule). format: uri type: string defaultThumbnailUrl: description: >- Video mode (optional). Poster image for the default video; Meta auto-generates one when omitted. format: uri type: string defaultVideoUrl: description: >- Video mode. Catch-all video for any placement no rule matches. Required in video mode. format: uri type: string rules: description: >- One entry per placement group you want to pin a specific asset to. items: properties: body: description: >- One primary text pinned to this rule. Omit to inherit the top-level body. minLength: 1 type: string description: description: >- One link description pinned to this rule. Omit to inherit the top-level description. maxLength: 255 minLength: 1 type: string headline: description: >- One headline pinned to this rule. Omit to inherit the top-level headline. maxLength: 255 minLength: 1 type: string imageUrl: description: >- Image mode. The image to deliver for this rule's placements. format: uri type: string placements: description: >- Placements this asset is pinned to. At least one field must be set (an empty rule is invalid; that role is served by the default asset). Same enums as the top-level `placements` object. properties: audienceNetworkPositions: items: enum: - classic - rewarded_video type: string type: array devicePlatforms: items: enum: - mobile - desktop type: string type: array facebookPositions: items: enum: - feed - right_hand_column - marketplace - story - search - instream_video - facebook_reels - facebook_reels_overlay - profile_feed - notification type: string type: array instagramPositions: items: enum: - stream - story - explore - explore_home - reels - profile_feed - ig_search - profile_reels type: string type: array messengerPositions: items: enum: - messenger_home - sponsored_messages - story type: string type: array publisherPlatforms: items: enum: - facebook - instagram - threads - messenger - audience_network - whatsapp - meta type: string type: array threadsPositions: items: enum: - threads_stream type: string type: array whatsappPositions: items: enum: - status type: string type: array type: object thumbnailUrl: description: >- Video mode (optional). Poster image for this rule's video; auto-generated when omitted. format: uri type: string videoUrl: description: >- Video mode. The video to deliver for this rule's placements. format: uri type: string required: - placements type: object maxItems: 10 minItems: 1 type: array required: - rules type: object placements: description: >- Manual ad placements on the shared ad set. Omit for automatic placements. properties: audienceNetworkPositions: items: enum: - classic - rewarded_video type: string type: array devicePlatforms: description: >- Restrict by device. Omit to deliver on both mobile and desktop. items: enum: - mobile - desktop type: string type: array facebookPositions: items: enum: - feed - right_hand_column - marketplace - story - search - instream_video - facebook_reels - facebook_reels_overlay - profile_feed - notification type: string type: array instagramPositions: items: enum: - stream - story - explore - explore_home - reels - profile_feed - ig_search - profile_reels type: string type: array messengerPositions: items: enum: - messenger_home - sponsored_messages - story type: string type: array publisherPlatforms: description: >- Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here. items: enum: - facebook - instagram - threads - messenger - audience_network - whatsapp - meta type: string type: array threadsPositions: items: enum: - threads_stream type: string type: array whatsappPositions: items: enum: - status type: string type: array type: object places: description: Meta place keys (from GET /apis/v1/ads/targeting/search). items: properties: key: type: string required: - key type: object type: array platformPostId: description: >- Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. Facebook IDs become object_story_id. minLength: 1 type: string rawTargeting: additionalProperties: true description: >- Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /apis/v1/ads/create does. type: object regionalRegulatedCategories: description: >- Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. items: type: string type: array regionalRegulationIdentities: additionalProperties: type: - string - integer description: >- Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. type: object regions: description: >- Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /apis/v1/ads/targeting/search?type=region). items: properties: key: minLength: 1 type: string required: - key type: object type: array roasAverageFloor: description: >- Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side. exclusiveMinimum: 0 type: number savedTargetingId: description: >- ID of a saved_targeting audience (POST /apis/v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. type: string specialAdCategories: description: Meta special ad categories on the new campaign. items: enum: - HOUSING - EMPLOYMENT - CREDIT - ISSUES_ELECTIONS_POLITICS - FINANCIAL_PRODUCTS_SERVICES - ONLINE_GAMBLING_AND_GAMING type: string type: array specialAdCategoryCountry: description: >- Countries the special ad category applies to. Requires specialAdCategories. items: type: string type: array startDate: description: >- When the ad set starts delivering. ISO 8601 date or date-time. type: string status: description: >- Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves. enum: - ACTIVE - PAUSED type: string targeting: description: >- Normalized, platform-agnostic ad-targeting spec. Every field is optional; an empty object targets the platform's default broadest audience. properties: ageMax: description: >- Maximum age. Same per-platform application and clamping as ageMin. maximum: 100 minimum: 13 type: integer ageMin: description: >- Minimum age. Applied on Meta, TikTok, Pinterest, LinkedIn, X and Google Search/Display (Google excludes the age ranges outside the request). Rejected with 400 on OpenAI, Reddit and Google Performance Max / Demand Gen. maximum: 100 minimum: 13 type: integer audienceExclude: description: >- Platform audience IDs to exclude; same ID formats as audienceInclude. Not supported on OpenAI (400). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. items: type: string type: array audienceInclude: description: >- Platform audience IDs to include, as returned by GET /apis/v1/ads/audiences: Meta: custom audience ids. TikTok: audience ids. Pinterest: customer list ids. LinkedIn: segment ids (the platformAudienceId from GET /apis/v1/ads/audiences). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. items: type: string type: array behaviors: description: >- Behaviour entities from /apis/v1/ads/targeting/search?dimension=behavior (Meta, TikTok and LinkedIn). On TikTok they target people who, in the picked categories: items: properties: id: type: string name: type: string required: - id type: object type: array cities: description: >- City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits; both must be set together or both omitted. `radius` is only honoured on platforms whose capability map allows city radius (Meta). items: oneOf: - type: string - properties: distanceUnit: description: Required if radius is set. enum: - mile - kilometer type: string key: type: string name: type: string radius: description: >- Radius around the city. Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. type: number required: - key type: object type: array communities: description: >- Reddit only (400 elsewhere). Subreddits to target, by name, with or without the `r/` prefix (e.g. `['marketing', 'r/startups']`), as returned by /apis/v1/ads/targeting/search?dimension=community. items: minLength: 1 type: string type: array companySizes: description: >- LinkedIn B2B only. Single-letter size codes (A to I), or the full urn:li:staffCountRange:* URN from /apis/v1/ads/targeting/search?dimension=companySize. items: type: string type: array conversationKeywords: description: >- Reddit only (400 elsewhere). Keywords that place the ad in Reddit conversations about them, as returned by /apis/v1/ads/targeting/search?dimension=conversationKeyword. items: minLength: 1 type: string type: array countries: description: ISO 3166-1 alpha-2 country codes (e.g. ['US']). items: type: string type: array countryGroups: description: >- Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`. items: enum: - africa - asia - europe - north_america - south_america - oceania - central_america - caribbean - eea - euro_area - nafta - mercosur - afta - apec - gcc - cisfta - emerging_markets - itunes_app_store - android_free_store - android_paid_store type: string type: array customLocations: description: >- Point-radius (lat/lng) targeting (Meta custom_locations / Google proximity). Honoured on Meta and Google; ignored on platforms without radius support. items: properties: address: description: >- Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location. type: string distanceUnit: enum: - mile - kilometer type: string latitude: maximum: 90 minimum: -90 type: number longitude: maximum: 180 minimum: -180 type: number name: type: string radius: description: Positive radius around the point. type: number required: - distanceUnit - latitude - longitude - radius type: object type: array excludedCommunities: description: >- Reddit only (400 elsewhere). Subreddits to exclude, named like `communities`. items: minLength: 1 type: string type: array excludedConversationKeywords: description: >- Reddit only (400 elsewhere). Conversation keywords to keep the ad away from. items: minLength: 1 type: string type: array excludedLocations: description: >- Geo to exclude from the audience. Mirrors the inclusion geo shape. Meta (excluded_geo_locations): excluded cities can carry a radius catchment, and excluded custom (lat/lng) pins are supported. properties: cities: description: >- Cities to exclude. Optional `radius` + `distanceUnit` exclude a catchment around the city (both must be set together or both omitted); Meta honours the radius on excluded cities. items: properties: distanceUnit: description: Required if radius is set. enum: - mile - kilometer type: string key: type: string radius: description: >- Radius around the excluded city. Requires distanceUnit. type: number required: - key type: object type: array countries: items: type: string type: array countryGroups: description: >- Meta only. Continents and trade blocs to exclude (`excluded_geo_locations.country_groups`). items: enum: - africa - asia - europe - north_america - south_america - oceania - central_america - caribbean - eea - euro_area - nafta - mercosur - afta - apec - gcc - cisfta - emerging_markets - itunes_app_store - android_free_store - android_paid_store type: string type: array customLocations: description: >- Point-radius (lat/lng) pins to exclude (Meta excluded_geo_locations.custom_locations). Mirrors the inclusion customLocations shape. items: properties: address: description: >- Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location. type: string distanceUnit: enum: - mile - kilometer type: string latitude: maximum: 90 minimum: -90 type: number longitude: maximum: 180 minimum: -180 type: number name: type: string radius: description: Positive radius around the point. type: number required: - distanceUnit - latitude - longitude - radius type: object type: array neighborhoods: description: >- Named neighbourhood areas to exclude. `key` from /apis/v1/ads/targeting/search. items: properties: key: type: string required: - key type: object type: array places: description: >- Named points of interest to exclude. `key` from /apis/v1/ads/targeting/search. items: properties: key: type: string required: - key type: object type: array regions: items: properties: key: type: string name: type: string required: - key type: object type: array zips: items: properties: key: type: string name: type: string required: - key type: object type: array type: object gender: description: Restrict by gender. 'all' (default) targets everyone. enum: - all - male - female type: string incomeTier: description: >- Normalized household-income tier (ZIP/percentile based). Meta and TikTok express all four. Google maps only `top_10` (its INCOME_RANGE_90_UP); other tiers on Google, and any income tier on LinkedIn / X / Pinterest, are rejected. enum: - top_5 - top_10 - top_10_25 - top_25_50 type: string industries: description: >- LinkedIn B2B only. Industry URN id fragments, or the full urn:li:industry:* URN from /apis/v1/ads/targeting/search?dimension=industry. items: type: string type: array interests: description: >- Interest entities from /apis/v1/ads/targeting/search?dimension=interest. Each carries the platform's opaque id. items: properties: id: type: string name: type: string required: - id type: object type: array jobFunctions: description: >- LinkedIn B2B only. Function URN id fragments, or the full urn:li:function:* URN from /apis/v1/ads/targeting/search?dimension=jobFunction. items: type: string type: array languages: description: >- Language codes restricting the audience by language. Applied on Meta, Google, TikTok, LinkedIn, X, Pinterest and Reddit; rejected with 400 on OpenAI. A code the platform cannot target returns 400 listing the ones it can. items: type: string type: array metros: description: >- DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`). items: properties: key: type: string name: type: string required: - key type: object type: array regions: description: >- Region/state targeting. `key` is the platform location ID from /apis/v1/ads/targeting/search?dimension=geo&geoType=region. An entry may also be that id as a plain string (`"20321"` is `{ key: "20321" }`). items: oneOf: - type: string - properties: key: type: string name: type: string required: - key type: object type: array seniorities: description: >- LinkedIn B2B only. Seniority URN id fragments, or the full urn:li:seniority:* URN from /apis/v1/ads/targeting/search?dimension=seniority. items: type: string type: array skills: description: >- LinkedIn B2B only. Member skills (e.g. Python, Recruiting): skill URN id fragments, or the full urn:li:skill:* URN from /apis/v1/ads/targeting/search?dimension=skill. Values are ORed; the facet is ANDed with the other facets. items: type: string type: array userDevice: description: >- Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting. items: minLength: 1 type: string minItems: 1 type: array userOs: description: >- Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting. items: minLength: 1 type: string minItems: 1 type: array workEmployers: description: >- Meta only. Employer entities from /apis/v1/ads/targeting/search?dimension=workEmployer. items: properties: id: type: string name: type: string required: - id type: object type: array workIndustries: description: >- Meta only. Work-industry entities from /apis/v1/ads/targeting/search?dimension=workIndustry. Not interchangeable with the LinkedIn `industries` URN fragments. items: properties: id: type: string name: type: string required: - id type: object type: array workPositions: description: >- Meta only. Job title entities from /apis/v1/ads/targeting/search?dimension=workPosition. Not interchangeable with the LinkedIn `jobTitles` URN fragments. items: properties: id: type: string name: type: string required: - id type: object type: array zips: description: >- Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`). Supported on Meta, Google, TikTok, Pinterest, X. items: properties: key: type: string name: type: string required: - key type: object type: array type: object tracking: description: >- Ad tracking. Meta, plus `urlTags` on ChatGPT (OpenAI) and `pixelId` on Reddit. Meta: attaches pixel measurement to the ad regardless of the optimization goal (the "Website events" tracking row in Ads Manager). properties: pixelId: description: >- Meta Pixel ID to attach for offsite-conversion measurement, or the Reddit pixel of the new ad group. type: string urlTags: description: >- Click-URL params. Meta: stored on the creative as `url_tags` and returned by GET /apis/v1/ads/{adId}/tracking-tags. items: properties: key: type: string value: type: string required: - key - value type: object type: array type: object userDevice: description: Meta `user_device`. items: type: string minItems: 1 type: array userOs: description: Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"]. items: type: string minItems: 1 type: array validateOnly: description: >- Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with `adSetId`). Nothing is uploaded, created or stored; media is checked by URL. type: boolean video: description: >- Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied. properties: id: description: >- Reuse a video already uploaded to this ad account (list them with GET /apis/v1/ads/videos) instead of re-uploading. Wins over `url`. Provide either `url` or `id`. type: string thumbnailUrl: description: >- OPTIONAL: when omitted, the poster is auto-generated from Meta's own preferred video thumbnail. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable). format: uri type: string url: description: >- Public URL of the video to upload. Provide either `url` or `id`. format: uri type: string type: object welcomeMessage: description: >- Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry. properties: prefillText: description: >- Message put into the user's text input, ready to send. Replaces Meta's default ("Hi! I want more info."). Lets one ad steer the opening message toward what it promotes (e.g. a specific product). Exactly one of prefillText or quickReplies. minLength: 1 type: string quickReplies: description: >- Tappable chips under the greeting instead of a prefilled message. Exactly one of prefillText or quickReplies. Put your own campaign or ad key in each payload. items: properties: payload: maxLength: 1000 minLength: 1 type: string title: description: Chip label the person taps. maxLength: 20 minLength: 1 type: string required: - payload - title type: object maxItems: 13 minItems: 1 type: array text: description: >- Greeting shown when the chat opens. Replaces Meta's default ("Hi! Can we help you?"). minLength: 1 type: string required: - text type: object whatsappPhoneNumber: description: >- WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. Sent to the creative CTA and, when creating a new ad set, its promoted_object. pattern: ^\+[1-9]\d{6,14}$ type: string workEmployers: items: properties: id: type: string name: type: string required: - id type: object type: array workIndustries: items: properties: id: type: string name: type: string required: - id type: object type: array workPositions: items: properties: id: type: string name: type: string required: - id type: object type: array workflowId: description: >- A workflow in the ad account's profile, stored on the ad. 404 when no such workflow exists in the profile. pattern: ^[a-fA-F0-9]{24}$ type: string zips: description: >- ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /apis/v1/ads/targeting/search. items: properties: key: minLength: 1 type: string name: type: string required: - key type: object type: array required: - adAccountId - name type: object required: true responses: '200': content: application/json: schema: properties: message: type: string results: items: properties: node: enum: - campaign - adSet - creative - ad type: string reason: description: >- On unverified: why Meta could not dry-run this node although the other nodes passed. type: string status: enum: - validated - skipped - unverified type: string required: - node - status type: object type: array validateOnly: description: Always true. type: boolean required: - message - results - validateOnly type: object description: >- `validateOnly: true` only. Meta accepted every node; nothing was created. '201': content: application/json: schema: oneOf: - description: >- Response returned by `POST /apis/v1/ads/ctwa` when the request used the single-creative shape (top-level headline / body / imageUrl|video). `adType` is the union discriminator. properties: ad: description: The persisted Ad document. type: object adType: enum: - single type: string message: type: string warnings: description: >- Present when Meta created the ad set differently from the request: items: type: string type: array required: - ad - adType - message type: object - description: >- Response returned by `POST /apis/v1/ads/ctwa` when the request used the multi-creative shape (`creatives[]`). N persisted Ad documents share the returned `platformCampaignId` and `platformAdSetId`. `adType` is the union discriminator. properties: adType: enum: - multi type: string ads: description: >- The persisted Ad documents (one per creative), all sharing the same `platformCampaignId` and `platformAdSetId`. items: type: object type: array message: type: string platformAdSetId: type: string platformCampaignId: type: string warnings: description: >- Present when Meta created the ad set differently from the request: items: type: string type: array required: - adType - ads - message - platformAdSetId - platformCampaignId type: object description: Ad(s) created and submitted for review. default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.