--- title: "Launch a ChatGPT Ads chat card ad" method: POST path: "/api/v1/tools/chatgpt_launch_ad/execute" tags: ["ChatGPT Ads"] --- # Launch a ChatGPT Ads chat card ad `POST /api/v1/tools/chatgpt_launch_ad/execute` ## Request - Base URL: `https://adako.ai` - URL: `https://adako.ai/api/v1/tools/chatgpt_launch_ad/execute` - Auth: HTTP bearer Builds a complete, paused campaign on ChatGPT Ads: image upload, campaign, ad group and one chat card ad. The campaign is created paused and its ad group and ad active inside it, so nothing delivers and nothing spends until the campaign is turned on, and turning it on launches everything. Say this explicitly when you report the result, with the two links the result gives (ChatGPT Ads Manager and the campaign's page in Adako), and offer "enable all": one chatgpt_resume_campaign call, listed in the result as go_live.enable_all, one approval. Use when: the user has given a budget, a maximum bid, a destination, ad copy and a square image, and has decided to launch. Resolve every place they named with chatgpt_geo_lookup first — this tool takes location ids and refuses names. Do not call it twice for the same brief. If a step fails, the error lists what already exists; finish or remove that rather than starting again, or you will create a second campaign spending a second budget. Pass exactly one of lifetime_budget and daily_budget: a campaign on this platform can have a total ceiling or a daily limit, never both, and passing both is refused before anything is created. Do not invent copy, a budget, a bid, a destination or a location the user did not give. If any of those is missing, ask. max_bid is required because this tool creates a fixed-bid ad group, and its unit follows the objective: a CPM (per 1,000 impressions) for reach, per click for clicks, per conversion for conversions. Before the user approves, confirm with them that every market in the targeting is enabled for advertising on their account: a valid location id does not mean the account may advertise there. The preview lists each location id with its place and country when a recent chatgpt_geo_lookup returned it. The card limits are hard: the title must be 3–50 characters, the body at most 100, and the image must be square. These, the bid and the schedule are all checked before anything is created, so a rejection here costs nothing. Schedule dates are days in the ad account time zone, and a start date already past there is refused. Returns the ids of the four objects created and reads all of them back so their state is confirmed rather than assumed. Budgets and bids are decimals in the account currency. ## Headers - `Idempotency-Key` string ## Request body - object - `arguments` object, required - `ad_account_id` string: ChatGPT Ads advertiser account id. One advertiser key belongs to one account, so this is only needed when the user has connected more than one key. Omit it to use the primary account. - `campaign_name` string, required: Name shown in Ads Manager. Say what it sells and to whom. - `lifetime_budget` number: Hard ceiling on everything this campaign will ever spend, as a decimal in the account currency (100 means one hundred, not 10000). A campaign takes either this or daily_budget, never both — pass exactly one. - `daily_budget` number: Daily spending limit, decimal in the account currency, with no total ceiling. A campaign takes either this or lifetime_budget, never both — pass exactly one. - `objective` 'reach' | 'clicks' | 'conversions': What the platform optimises for: reach, clicks or conversions. Defaults to clicks. Conversions also needs conversion_event_setting_id. It also decides what max_bid means. - `conversion_event_setting_id` string: The conversion event to optimise for. Required when objective is conversions. - `geo_location_ids` string[]: Location ids from chatgpt_geo_lookup to run in. Ids only — a place name here is refused. Omit to run wherever the account is enabled to advertise. - `excluded_geo_location_ids` string[]: Location ids from chatgpt_geo_lookup the campaign must not run in, for example a region inside an included country. Ids only; an id cannot be both included and excluded. - `ad_group_name` string: Ad group name. Defaults to the campaign name with a suffix. - `context_hints` string[]: Short free-text hints about the audience or context the ad suits. This platform has no keywords; these are the nearest thing. - `max_bid` number: Maximum bid, a decimal in the account currency. This tool creates a fixed-bid ad group, which the platform will not accept without one, so a launch without it is refused before anything is created — ask the user for the number, never invent one. Its meaning follows the campaign objective: reach → the most to pay per 1,000 impressions (CPM, 60 means 60.00 per thousand); clicks → the most to pay per click (2.5 means 2.50 per click); conversions → the target cost per conversion (100 means 100.00 per conversion, although billing is still per click). - `title` string, required: Chat card headline, 3–50 characters. This is the line people read first. - `body` string, required: Chat card body copy, at most 100 characters. Put the offer in the first half. - `target_url` string, uri, required: Where a click goes. Must be https and reachable without a login. - `image_url` string, uri, required: The card image. It must be square; its bytes are checked here before anything is created. Adako hosts no files: the platform downloads this URL itself, from its own servers and often hours later, so it must be a public link straight to the file — not a file on the computer, not a Drive, Dropbox or design-tool share page, not a link that expires or asks for a login. Call check_media first: it repairs the usual share links, checks the file against this platform, and says where to put a file that has no link yet. - `start_date` string: First day delivery may start, YYYY-MM-DD, in the ad account time zone. Must be today or later there. Defaults to whenever the user activates it. - `end_date` string: Last day of delivery, YYYY-MM-DD, inclusive, in the ad account time zone. - `idempotency_key` string: Optional caller-supplied key; identical keys never execute twice. - `raw_data` boolean: Return compact JSON only (no markdown). Use when you will compute on the result. ## Response `200` The tool ran. A write returns proposal_id and approve_url while the change waits for approval. - SuccessEnvelope - `success` unknown, required - `tool` string, required - `data` object, required: Machine-readable result. - `markdown` string, required: The same result written for a person or a model. - `quota` Quota: Task usage for the current billing period. - `plan` string - `used` integer - `limit` integer - `period_end` string - `upgrade_url` string - `proposal_id` string: Present for writes. Nothing changes on the ad platform until it is approved. - `approve_url` string: Where a person approves the proposal. - `request_id` string, required ## Other responses - `400`: Invalid arguments, or the ad account could not be resolved. - `401`: Missing, invalid, revoked or expired API key. - `402`: Monthly task quota used up, or the plan does not include this tool. - `403`: The connected ad account lacks the access level this tool needs. - `404`: Unknown tool name. - `409`: Not connected, reconnect needed, confirmation required, a proposal already pending or no longer pending, an identical create that failed earlier today (proposal_failed_before), a create that duplicates an approved one (duplicate_create), the ad-account limit of the plan reached (account_limit), or an Idempotency-Key reused with different arguments. - `429`: Rate limited by Adako or by the ad platform. See Retry-After. - `500`: Unexpected error inside Adako. - `502`: The ad platform returned an error. --- [API](https://skmtc.dev/adako/apis/adako-rest-api.md) · [All operations](https://skmtc.dev/adako/apis/adako-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adako/apis/adako-rest-api/revisions/59ee60d48a56?raw)