ChatGPT Ads Context Hints: How to Write Them, and Where OpenAI's Own Docs Disagree

On 2026-09-16 OpenAI published a dedicated help-centre article for context hints — the ad-group field that has existed in the ChatGPT Ads Advertiser API since the API's first public documentation, but that until now had no page of its own explaining how to write one.

The article matters more than a normal documentation addition, because context hints are the closest thing ChatGPT Ads has to the keyword. There is no keyword planner, no match type, no search-term report. What an advertiser gets instead is a free-text field attached to an ad group, and until yesterday the only official instruction on what to put in it was a two-sentence field note in an API reference.

That field note is now the problem. OpenAI has published three descriptions of context hints across two documentation surfaces, and they do not agree. One of them tells you to write natural phrases. Another calls them "audience or placement hints." Every runnable code example in the API reference does the exact thing the new guidance calls "less useful."

Everything below is quoted from OpenAI's official documentation and verified on 2026-09-17. Where we are reasoning past what OpenAI states, it is labelled as ours.

What a context hint is, in OpenAI's words

From the new help-centre article, Write Context Hints for ChatGPT Ads:

Context hints are additional details about your business, product, or service that help our systems understand when your ads may be relevant in ChatGPT. Add them at the ad group level to share useful information that may not be clear from your ad or landing page.

Two things are load-bearing in that sentence. Hints live at the ad group level, not the campaign or the ad. And their stated job is to supply what is not already visible in the creative or the landing page — which means a hint that restates your headline is, by OpenAI's own definition, doing nothing.

The developer-docs surface, Campaign Targeting, says the same thing in stricter language:

Context hints provide additional information about the ads in an ad group. Use them to describe relevant products, use cases, or needs that the creative and landing page may not fully cover. Hints are not exact-match keywords. They also do not replace explicit geographic, platform, or audience targeting.

How OpenAI says to write one

The help article gives a three-part prompt — what, who, when:

• What: "Relevant product features, services, pricing, availability, or service areas."
• Who: "Customer needs, preferences, or circumstances your offering is suited for."
• When: "Situations or decisions where your offering may be useful."

And one instruction that does most of the work:

Write a clear, natural phrase focused on one idea rather than a list of disconnected keywords. Each hint does not need to cover all three.

It then names four properties of a strong hint — additional, specific, relevant, accurate — with a clarification worth reading twice:

A detail can already appear on your landing page and still be useful if the hint connects it to a customer need. For example, "breathable running shoes for training in warm weather" explains why a feature matters.

The published examples, which OpenAI explicitly labels illustrative:

The developer docs carry a parallel table, framed as less useful versus more useful:

Hold on to the left-hand column. It is about to show up somewhere it should not.

Where OpenAI's own documentation contradicts itself

The Ad Groups API reference describes the same field like this:

context_hints | string[] | No | Free-form audience or placement hints.

That one line disagrees with both guidance surfaces on two counts. The help article says hints are details "about your business, product, or service." The developer guidance says they "do not replace explicit geographic, platform, or audience targeting." Calling them audience hints invites precisely the mistake the guidance page devotes a section to preventing — and placement is not a concept ChatGPT Ads exposes to advertisers at all.

It gets more concrete. Every runnable example in the API reference sets context_hints to a bare keyword list:

{
  "campaign_id": "cmpn_101",
  "name": "US English",
  "context_hints": ["productivity", "team collaboration"],
  "status": "active"
}

The Bulk API does the same, with ["shoes", "spring fashion"] — and shoes is the literal first entry in the developer docs' own "Less useful" column.

The API reference's longer field note splits the difference, and in doing so keeps the ambiguity alive:

Context hints provide extra information on when you think your ads might be useful, and help guide when they appear. Provide a list of descriptions or keywords for when the product or service might be useful to show.

"Descriptions or keywords" is not what "rather than a list of disconnected keywords" means.

Our read, and it is ours: the guidance pages are the intent and the API reference is stale scaffolding — placeholder examples written when the field was new, never revisited when the guidance was written. We say that because the two guidance surfaces, written by different teams for different audiences, independently agree with each other and independently disagree with the reference. But OpenAI has not said this, and if you are building an integration, the operational risk is real: an engineer implementing from the API reference will ship keyword arrays, and nothing in the API will reject them.

What to do about it: write phrases, not keywords, wherever the hint originates. If your ad groups are created programmatically, the copy-pasteable example in the reference is not a spec for good input, it is a spec for valid input.

The four mechanics the help article leaves out

The help article is a writing guide. The operational details live only in the developer docs, and three of the four below will eventually bite someone.

1. The ceiling is 2,000 hints per ad group.

An ad group can contain up to 2,000 hints. You do not need to fill the limit; include information that helps describe the ads accurately.

That ceiling reads like an invitation to generate hints at scale. Read against the guidance — additional, specific, accurate, one idea per hint — it is not. Two thousand accurate one-idea phrases about a single ad group's shared theme is not a bar most advertisers can clear honestly, and "accurate" is a maintenance obligation: the help article requires you to "update hints when features, pricing, promotions, availability, or service areas change." The plumber example bakes an $89 service-call fee into a hint. That is a price you now have to keep true in two places.

2. Updating the field replaces the list. It does not append.

Updating context_hints replaces the current list. To add one hint, retrieve the ad group, append the new hint to the existing list, and submit the complete intended list. Send an empty array to clear the list. Omit the field when you want to leave it unchanged.

This is the single most destructive thing in the API surface. A POST /ad_groups/{id} carrying one new hint silently deletes the other 400. There is no merge semantic and no warning. The safe pattern is read-modify-write, and OpenAI adds: "Retrieve the ad group after the update and confirm the saved list."

Note the difference between an empty array (clears everything) and an omitted field (leaves it alone). A serializer that helpfully emits "context_hints": [] for an unset property will wipe the field on every update.

3. Hints are not a delivery control, and the help article is unusually blunt about it.

Hints are not targeting rules or delivery instructions. They do not guarantee that your ad will appear for particular conversations, audiences, or situations, and they cannot enforce geographic limits, schedules, or exclusions.

With the worked example:

For example, "Residential plumbing services available in Chicago" describes your business. "Show this ad only to people in Chicago" is a delivery instruction. Use supported product controls for delivery restrictions, where available.

And the line that will save someone a quarter of wasted spend:

Wanting to reach a customer group does not, by itself, make your offering relevant.

The developer docs close the loop: "If you need to restrict delivery to a geographic area or audience, configure that restriction on the campaign separately."

4. There is an exclusion_hints field, and nothing explains it.

The Bulk API's supported-fields table lists exclusion_hints alongside context_hints for both ad_group.create and ad_group.update. That is the only place either documentation surface mentions it. It has no entry in the Ad Groups API reference field table, no section in Campaign Targeting, and no mention in the new help article — which, in the same breath, states that hints "cannot enforce ... exclusions."

We are not going to tell you what exclusion_hints does, because OpenAI has not. We are flagging that it exists, that it is accepted by the bulk endpoint, and that shipping values into an undocumented field whose stated sibling capability is explicitly disclaimed is not a good trade. Verified 2026-09-17: listed in the Bulk API supported-fields table only.

How hints interact with ad-group structure

The help article ties hint quality to how you split ad groups:

Group hints around a shared product, service, theme, or customer need. Related situations can belong in the same ad group. Consider separate ad groups when use cases require different messaging or landing pages.

This is the familiar paid-search discipline arriving by a different road. In Google Ads you split ad groups so the keyword, the copy and the landing page match. Here you split them so the hints and the creative describe one coherent offer. The failure mode is identical: an ad group whose hints span running shoes and hiking boots will be described accurately for neither, and the ad it serves cannot be right for both.

One more line, easy to skim past:

You can also describe which products an ad group promotes. This clarifies product scope; it does not exclude particular people or conversations.

Scope, not exclusion. It keeps coming back to the same boundary.

What we would actually do

This is Soku's editorial opinion, not OpenAI documentation.

1. Write hints last, not first. A hint is defined as what the creative and landing page do not already cover. You cannot know that before the creative exists.
2. One idea per hint, and keep the count low. The useful number is closer to 10 than to 2,000. Every hint is a claim you have to keep accurate.
3. Never put a geographic, scheduling or audience restriction in a hint. It will not be enforced, and it displaces a hint that could have described the offer.
4. If you write hints via the API, use read-modify-write and verify after. Assume no merge. Assume no warning.
5. Put prices in hints only if you have a process for changing them. The plumber example is good writing and a maintenance liability at the same time.
6. Re-read hints whenever the offer changes. "Accurate" is listed as a property of a strong hint, which makes a stale hint a weak one by definition.

Also documented this week

The context-hints article was not the only ChatGPT Ads documentation change captured on 2026-09-17. Briefly, with sources:

• Branch is now a supported mobile measurement partner. Set up Mobile Measurement Partner Integrations changed from "AppsFlyer and Adjust are the mobile measurement partners currently supported" to "AppsFlyer, Adjust, and Branch," and gained a five-step Branch setup section.
• Event quality lost its beta label. Understand and improve event quality previously opened with "Note: Event quality is currently in beta, and access is rapidly expanding." That line is gone.
• Sponsored Agents are documented, and unavailable. A new article describes an ad format that lets people "chat with an AI representative of a business in ChatGPT," and is explicit that it is "currently available only to selected advertisers in a limited alpha test" and that OpenAI is "not accepting early access requests at this time." Do not plan around it.
• The ad-account creation limit is now written down. Creating additional ad accounts in Ads Manager states that once you belong to 10 or more ad accounts you cannot create another yourself — a limit on creating, not on membership, since you can still be invited to more.

Separately, OpenAI's advertiser product-update email dated 2026-09-16 announced text customization — an opt-in setting that adapts existing headlines and descriptions to conversation context and can translate ad copy into a user's preferred language. We could not find this in either documentation surface as of 2026-09-17, so treat it as announced-but-not-yet-documented, attributed to the email and not to a help-centre page. The same email described AI-assisted ad creation as "currently in testing."

What the documentation still does not say

Three things an advertiser would want and cannot get from the official text:

• There is no reporting on hints. Nothing in the reference or the help centre exposes which hint contributed to a delivery. There is no search-term-report equivalent, so hint performance is not measurable at the hint level — only inferable from ad-group-level splits you design yourself.
• There is no stated quality signal. Unlike Event Quality Score, which now publishes a 1-10 rating for conversion data sources, hints have no published diagnostic. A bad hint and a good hint look identical in the interface.
• The 2,000 ceiling has no stated behaviour near the top. OpenAI does not say whether many weak hints dilute strong ones. Our assumption is that they do, and it is an assumption.

Sources, all verified 2026-09-17:

• Write Context Hints for ChatGPT Ads — help centre, published 2026-09-16
• Campaign Targeting — developer docs
• Ad Groups API reference — developer docs
• Bulk API — developer docs
• Create Ad Groups for ChatGPT Ads — help centre
• OpenAI advertiser product-update email, 2026-09-16 — used only for the text-customization and AI-assisted-ad-creation items, both labelled above as not documented

If you are running ChatGPT Ads alongside Google and Meta, the structural differences matter more than the surface ones — we covered them in ChatGPT Ads vs Google Ads vs Meta Ads. For the layer beneath hints, see ChatGPT Ads platform targeting, which is a real delivery control in the way hints are not. And for the measurement side referenced above, ChatGPT Ads event quality covers the score that just left beta.