ChatGPT-Anzeigen (OpenAI Ads)
OpenAI Ads API deklarativ via api-Adapter: Konto, Kampagnen, Anzeigengruppen, Anzeigen, Kennzahlen je Tag; Pausieren, Budget, Anlegen mit derselben Freigabe und demselben Deckel wie Google und Meta.
ChatGPT-Anzeigen (Ads Manager ads.openai.com) laufen über die OpenAI Ads API (Advertiser API, https://api.ads.openai.com/v1/, Doku: developers.openai.com/ads). TaskMonkey bindet sie über den deklarativen api-Adapter ein. Die Tools liegen in config/tenants/_shared/tools/openai_ads/ und stehen damit jedem Workspace zur Verfügung, sobald er einen apis.openai_ads-Block und einen eigenen Key hat (seit 16.11.2026, zuerst meco).
Was die API kann
- Auth:
Authorization: Bearer <Ads-API-Key>. Den Key legt man im Ads Manager unter Settings an. Ein Key gehört zu genau einem Werbekonto (GET /ad_account, deshalb ohne Konto-ID). - Lesen: Konto, Kampagnen, Anzeigengruppen, Anzeigen, Insights (Konto, Kampagne, Anzeigengruppe, Anzeige; stündlich, täglich, monatlich oder Summe; Impressionen, Klicks, Kosten, CTR, CPC, CPM; Aufschlüsselung nach Land, Gerät und Plattform), Audit-Logs.
- Schreiben: Kampagnen, Anzeigengruppen und Anzeigen anlegen und ändern (
POST, nicht PATCH), Status über…/activate,…/pause,…/archive(Archivieren ist nicht umkehrbar), Tages- oder Laufzeitbudget je Kampagne, Bilder hochladen (POST /upload), Konto-Ausgabelimits (nur bei Rechnungskauf), Pixel und Conversions-API, Bulk-API. - Beträge in Micros der Konto-Währung (1 EUR = 1.000.000). Kosten (
spend) in Insights kommen schon in Währungseinheiten. - Rate-Limits: 600 Anfragen pro Minute je Endpunkt, 1.200 pro Minute gesamt (je Konto und je IP), Bulk-Jobs 10 pro 10 Sekunden.
- Ausrichtung im EWR: keine personalisierten Anzeigen, nur Land und Gesprächsthema (
context_hintsder Anzeigengruppe). Mindestbudget DE: etwa 15 € je Tag und Kampagne im Wochenschnitt (siehedocs/marketing/chatgpt-ads-recherche-2026-10-29.md).
Tools
| Tool | Art | Geld? | Freigabe |
|---|---|---|---|
openaiAdsGetAccount |
lesen: Konto (Status, Zeitzone, Währung, Prüfung) | – | – |
openaiAdsListCampaigns |
lesen: Kampagnen mit daily_budget_eur / lifetime_budget_eur |
– | – |
openaiAdsListAdGroups |
lesen: Anzeigengruppen einer Kampagne (context_hints, Gebot) |
– | – |
openaiAdsListAds |
lesen: Anzeigen einer Anzeigengruppe (Text, Ziel-URL, review_status) |
– | – |
openaiAdsGetInsights |
lesen: Kennzahlen je Tag oder als Summe, plus totals |
– | – |
openaiAdsGetObject |
intern: ein Objekt lesen (für die Prüfungen) | – | – |
openaiAdsAccountDailyBudget |
intern: Summe aktiver Tagesbudgets gegen den Konto-Deckel | – | – |
openaiAdsSetStatus |
Kampagne, Anzeigengruppe oder Anzeige paused (sofort) oder active |
ja | active: Ja im Chat, ohne Chat Freigabe-Anfrage, autonome Workspaces bis zum Deckel ohne |
openaiAdsSetCampaignBudget |
Tagesbudget einer Kampagne | ja | Erhöhen wie active, Senken sofort |
openaiAdsUploadImage |
Bild per https-URL hochladen, liefert file_id |
nein | – |
openaiAdsCreateCampaign |
Kampagne anlegen, immer pausiert, mit Tagesbudget | nein (pausiert) | wie active |
openaiAdsCreateAdGroup |
Anzeigengruppe anlegen, immer pausiert, Festgebot | nein (pausiert) | wie active |
openaiAdsCreateAd |
Anzeige (chat_card) anlegen, immer pausiert, geht zur Prüfung |
nein (pausiert) | wie active |
openaiAdsObjectAction, openaiAdsUpdateCampaignBudget, openaiAdsCreateObject |
Roh-Schreiber | ja | nur über die Hüllen (only_via) |
Beispiel Kosten je Tag: openaiAdsGetInsights ohne Argumente liefert die letzten 7 Tage je Kampagne und Tag (Tage in Europe/Berlin, heute bis zur letzten vollen Stunde). Ganzes Konto als eine Summe: {"aggregation_level": "ad_account", "granularity": "none"}.
Regeln für Geld
Gleiches Muster wie Meta Ads und Google Ads:
- Alles wird pausiert angelegt. Live geht etwas nur über
openaiAdsSetStatus(status=active), und zwar erst, wenn Kampagne, Anzeigengruppe und Anzeige aktiv sind. - Obergrenze je Kampagne
apis.openai_ads.max_daily_budget_eur(Default 30), Höchstgebotapis.openai_ads.max_bid_eur(Default 5 €, je Klick bzw. je 1.000 Impressionen). Darüber schreibt TaskMonkey nie. - Konto-Deckel der Plattform
Platform.ads.max_account_daily_budget_eur(Default 50): Summe aller aktiven ChatGPT-Kampagnen inklusive der neuen bzw. geänderten. Nicht bestimmbar (aktive Kampagne mit Laufzeitbudget, mehr als 500 Kampagnen, Lesefehler) heißt abgelehnt. - Nur EUR-Konten. Rechnet das Werbekonto in einer anderen Währung, ändert TaskMonkey keine Budgets und aktiviert nichts.
- Laufzeitbudgets werden nicht angefasst (die API stellt nur von Laufzeit auf Tag um, nicht zurück), und solche Kampagnen werden nicht aktiviert. Kampagnen aus TaskMonkey haben immer ein Tagesbudget.
- Freigabe und Autonomie:
checkAdsAutonomy(App\Tooling\AdsAutonomy, Plattformopenai_ads), sonstrequestAdsApproval(Ja im Chat bzw. Freigabe-Anfrage unter/manage/approvals). meco ist perPlatform.ads.workspaces.mecoautonom. Der Gesamtdeckelautonomous_max_total_daily_eur(meco 50 €/Tag) zählt jetzt Google, Meta und ChatGPT zusammen: Bei jeder autonomen Erhöhung liestcheckAdsAutonomydie Tagesbudgets aller anderen eingerichteten Plattformen. Ist eine davon nicht lesbar, gibt es eine Freigabe-Anfrage statt einer autonomen Aktion. Anlegen (pausiert) ändert die Konto-Summe nicht, läuft aber durch dieselbe Prüfung. - Ziel-URLs der Anzeigen nur https auf
apis.openai_ads.allowed_target_hosts(meco:taskmonkey.deund Subdomains). Ohne Liste wird keine Anzeige angelegt. - Archivieren gibt es nicht als Tool (nicht umkehrbar), das geht nur im Ads Manager.
Deckel-Audit (auch für Google und Meta)
Die Regeln oben greifen nur, wenn TaskMonkey selbst schreibt. Anlass 17.11.: Im ChatGPT-Werbekonto lief eine vom OpenAI-Einrichtungsassistenten angelegte Kampagne mit 65 €/Tag an unseren Tools vorbei. Deshalb prüft der Scheduled Task ads_cap_audit (meco, config/tenants/meco/scheduled.php, stündlich, failure_backoff 15 min) mit dem Tool auditAdsBudgetCaps (config/tenants/_shared/tools/ads_audit/), was in den Konten tatsächlich aktiv ist:
- liest je eingerichteter Plattform alle aktiven Kampagnen mit Tagesbudget (
listAdsCampaigns,metaListActiveBudgets,openaiAdsListCampaigns); - Verstoß 1: Tagesbudget einer Kampagne über
apis.<plattform>.max_daily_budget_eur(nur wenn gesetzt); - Verstoß 2: Summe einer Plattform über dem Konto-Deckel
Platform.ads.max_account_daily_budget_eur; - Verstoß 3: Summe aller Plattformen über dem Gesamtdeckel (
Platform.ads.workspaces.<code>.max_total_daily_eur, sonstautonomous_max_total_daily_eur, sonst Konto-Deckel; im Tool als$ctx['platform']['ads']['max_total_daily_eur']). Bei 2 und 3 wird pausiert, bis die Summe wieder passt: zuerst Kampagnen, die beim letzten sauberen Lauf noch nicht aktiv waren, dann die teuerste. Geteilte Google-Budgets zählen einmal. - Verstoß = Kampagne über das normale Pause-Tool pausieren (
setAdsCampaignStatusPAUSED,metaUpdateStatusPAUSED,openaiAdsSetStatuspaused). Budget wird nie geändert, nichts gelöscht. Danach Mail an den Workspace (sendAdminEmail, EmpfängerPlatform.ads.workspaces.<code>.notify_emails, sonstadmin_emails) mit Plattform, Kampagne, Tagesbudget, Grund, Ergebnis. - Meta-AdSets zählen mit, außer
effective_statusPAUSED, ARCHIVED, DELETED, CAMPAIGN_PAUSED (also auch IN_PROCESS, WITH_ISSUES; ohne Feld gilt ACTIVE). - Nicht raten: Plattform nicht lesbar (Fehler, zu viele Kampagnen, Konto nicht in EUR — Währung je Konto: Google
customer.currency_codeperqueryAds, Metacurrencydes Ad-Accounts permetaGetAdAccount, ChatGPTcurrency_code) oder aktive Kampagne mit Laufzeitbudget = Meldung, nichts pausiert. Die Gesamtsumme gilt dann als Untergrenze; liegt schon sie über dem Deckel, wird trotzdem pausiert. Lesefehler machen den Lauf zum Fehler (Backoff, Monitor). - Je Kampagne bzw. Hinweis höchstens eine Mail pro Tag (
$ctx['cache']); scheitert die Mail, kommt sie im nächsten Lauf. - Probelauf ohne Pausieren:
bin/cake test_tool -t meco --tool auditAdsBudgetCaps --args '{"dry_run":true}'.
Wieder einschalten geht nur über die normalen Tools (Obergrenze, Deckel, Freigabe greifen dort). Wer eine Kampagne im Ads Manager selbst anlegt, sollte das Budget dort im Deckel halten, sonst pausiert der Audit sie innerhalb einer Stunde.
Einrichten (pro Workspace)
- Im Ads Manager unter Settings einen API-Key anlegen.
- In
tenants_untracked/<code>/.envalsOPENAI_ADS_API_KEY=…ablegen (prod:shared/tenants_untracked/<code>/.env). - In
apis.phpdes Workspaces:
'openai_ads' => [
'base_url' => 'https://api.ads.openai.com/v1/',
'headers' => [
'Authorization' => 'Bearer {{secret:OPENAI_ADS_API_KEY}}',
'Accept' => 'application/json',
],
'read_timeout' => 25,
'max_daily_budget_eur' => 30,
'max_bid_eur' => 5,
'allowed_target_hosts' => ['example.de'],
],
- Prüfen:
bin/cake test_tool -t <code> --tool openaiAdsListCampaigns.
Tests: tests/TestCase/Tooling/OpenaiAdsToolsTest.php (Fake-API).