> For the complete documentation index, see [llms.txt](https://docs.adpage.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adpage.io/integrations-marketingtools/openai-ads.md).
# OpenAI Ads
Configure the OpenAI Pixel and Conversions API with event ID deduplication.
Set up the OpenAI Pixel in the web container first. Then send matching events through the OpenAI Conversions API.
Both tags send the same conversion. Give both tags the same event name and event ID. OpenAI can then deduplicate the events and count one conversion.
This hybrid setup captures browser and server events. It also reduces losses from ad blockers and browser cookie restrictions.
### What you'll configure
You will create:
* An OpenAI Pixel tag in the GTM web container.
* An OpenAI Conversions API tag in the GTM server container.
* One shared `event_id` for each matching browser and server event.
Use this page for the complete implementation. See [OpenAI credentials](/integrations-marketingtools/openai-ads/where-to-find-the-openai-pixel-id-and-api-key.md), [event ID deduplication](/integrations-marketingtools/openai-ads/chatgpt-ads-event-id-deduplication.md), and [campaign URL tracking](/integrations-marketingtools/openai-ads/utm-parameters-and-dynamic-tracking-for-chatgpt-ads.md).
### Before you start
Make sure you have:
* [ ] A GTM web container with GA4 event tags.
* [ ] A GTM server container that receives the GA4 events.
* [ ] The **OpenAI Pixel ID** and **API Key** from OpenAI Ads Manager. See [Where to find the OpenAI Pixel ID and API Key](/integrations-marketingtools/openai-ads/where-to-find-the-openai-pixel-id-and-api-key.md).
* [ ] A **Unique Event ID** variable in the web container.
{% hint style="info" %}
Confirm that the client's OpenAI Ads Manager account is active. It provides the Pixel ID, conversion configuration, and API key.
{% endhint %}
### Part 1: Set up client-side tracking
#### Step 1: Add the OpenAI Pixel template
1. Open your GTM web container and go to **Templates**.
2. Under **Tag Templates**, click **Search Gallery**.
3. Search for the **OpenAI Pixel** tag template and add it.
#### Step 2: Create a Pixel ID variable
1. Go to **Variables** and create a **Constant** variable.
2. Set its value to the OpenAI Pixel ID.
3. Save it as your Pixel ID variable.
#### Step 3: Create client-side event tags
1. Create a new **OpenAI Pixel** tag.
2. Select your Pixel ID variable.
3. Choose **Inherit from DataLayer** to reuse the GA4 event name.
4. Choose **Override** only when OpenAI requires a different event name.
5. Keep **Automatic Event Parameters** mapping enabled.
6. Under **Server-Side Tracking Settings**, set **Event ID** to your Unique Event ID variable.
7. Use the same trigger as the matching GA4 event tag.
Repeat this for every event you want to track. Include `page_view` with the same trigger as the GA4 page view tag.
#### Step 4: Pass the event ID to GA4
Add the same Unique Event ID variable to every matching GA4 event tag:
1. Open the GA4 event tag.
2. Add an event parameter named `event_id`.
3. Set its value to the Unique Event ID variable.
4. Save the tag.
The server container can now read the event ID from the GA4 event.
### Part 2: Set up server-side tracking
#### Step 5: Add the Conversions API template
1. Open your GTM server container and go to **Templates**.
2. Under **Tag Templates**, click **Search Gallery**.
3. Add the **OpenAI Conversions API** tag template.
#### Step 6: Create the server-side tag
1. Create a new **OpenAI Conversions API** tag.
2. Under **Event Name Setup Method**, choose **Inherit from client**.
3. Choose **Override** only when the Pixel tag uses the same override.
4. Choose the correct **Action Source**, such as **Website**.
5. Enter the OpenAI Pixel ID and API key.
6. Keep **Automatic Event Parameters** mapping enabled.
#### Step 7: Pass the event ID to OpenAI
1. Create a server-container variable that reads the incoming `event_id` event parameter.
2. Open the OpenAI Conversions API tag.
3. Under **Server Event Data Parameters**, add **Event ID**.
4. Set its value to the server-side event ID variable.
#### Step 8: Configure consent and the trigger
Enable **Consent Granted / GTM Consent Mode support**. Map it to marketing consent.
Create a trigger for the events you want to send. Use both conditions:
* `{{Event Name}}` matches RegEx `purchase|order_completed`.
* `{{Client Name}}` equals `GA4`.
Leave **Set Click ID cookie** enabled unless the client requires otherwise. It stores OpenAI's click ID in the first-party `__oppref` cookie.
{% hint style="warning" %}
The Pixel and Conversions API tags must use the same event name and event ID. Different values prevent deduplication.
{% endhint %}
### Test and validate the complete setup in preview mode
Before you publish, confirm that the OpenAI cookies reach the server container and that the Conversions API tag forwards the click ID (`oppref`) and the browser reference (`obref`) to OpenAI.
The Pixel stores both values in first-party cookies (`__oppref` and `__obref`). The Conversions API does not capture them for you. The tag must find the click ID in the URL, the cookie, or the event data, and send it as `oppref`. The browser reference goes in `user.obref`, unchanged.
**Prepare the test**
1. Open a clean incognito window. Connect GTM preview mode for both the web container and the server container.
2. Work in a separate workspace. If the tag offers **Validate Only**, enable it for the test, so test events are excluded from measurement. Switch it off again before you publish.
3. Open a landing page with a test click ID, for example `https://yourdomain.com/?oppref=test123`. You can also click a test campaign
**Where to look in server preview**
| Location | What to check |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Incoming request (client) | The `cookie` header contains `__oppref` and `__obref`. If they are missing, the tag cannot read them. The server container is probably not running on a first-party domain of the website. |
| Event Data | `page_location` contains the `oppref` parameter. The consent state shows `ad_storage` granted. |
| OpenAI tag → Request | The URL is `https://bzr.openai.com/v1/events?pid=`. The body contains `oppref`, `user.obref`, `id` and `source_url`. |
| Browser → Application → Cookies | `__oppref` exists with the expected domain and expiry. The server container sets it in the `Set-Cookie` header of its response. |
**Run the test scenarios**
| # | Scenario | Expected result |
| - | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | Landing page with `oppref` in the URL, marketing consent granted | The first event contains `oppref`, equal to the URL value. The `__oppref` cookie is set. |
| 2 | Second page view without `oppref` in the URL | `oppref` comes from the cookie and has the same value. |
| 3 | Second ad click with a different `oppref` | The new value is sent and the cookie is overwritten. |
| 4 | Direct visit without `oppref` | `oppref` is omitted from the body. It is not an empty string. |
| 5 | Marketing consent denied | No request goes to OpenAI and no cookies are set. Revoking consent removes the cookies. |
| 6 | Consent given after the landing page loaded | The OpenAI tag fires after the consent update and still contains `oppref` from the URL. |
| 7 | `user.obref` | Equals the value of the `__obref` cookie and is not hashed. |
| 8 | Pixel and Conversions API together | Both send the same event ID, so only one conversion counts. |
| 9 | Purchase sent from a shop webhook | No browser cookies are available. Store the click ID with the order and set it manually in the tag. |
**Apply the findings to the template**
1. Update the **OpenAI Conversions API** template to the latest version from the gallery. Check that the user fields in the request body match the OpenAI specification, for example `emails_sha256`, `cities`, `postal_codes` and `countries` as lists.
2. If `oppref` is missing on the first event although `page_location` contains it, set the **Click ID** manually under **Server Event Data Parameters**. Use a variable that reads `oppref` from `page_location` first, then from the `__oppref` cookie, then from the event data. Manual values take precedence over automapped ones, so make sure the variable falls back correctly. Test in preview what happens when the variable is empty.
3. Keep **Set Click ID cookie** enabled. Leave **HTTP Only** on its default (off), so browser scripts can still read the cookie. Choose an expiry that matches OpenAI's cookie lifetime of 30 to 90 days.
4. Fire the OpenAI Pixel `page_view` tag after the consent update. The landing URL contains `oppref` on the first page only. If the tag fires before consent is known, the click ID is lost.
5. Use the same Unique Event ID in both tags. Disable **Autogenerate an Event ID** in the server tag when the Pixel also sends events.
**Check the result after publishing**
In the outgoing request logs, confirm that:
* Landing pages with `oppref` in the URL carry `oppref` in the request body.
* Follow-up page views carry the same value.
* No requests contain `"validate_only": true`.
* The number of non-2xx responses does not increase.
{% hint style="warning" %}
Only send the click ID, hashed emails and cookie values for visitors who granted marketing consent. Test values such as `test123` reach OpenAI as real events unless **Validate Only** is enabled.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.adpage.io/integrations-marketingtools/openai-ads.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
