Technical Integration Guide: Teads In-Chat API (V2.0)

This documentation defines the technical specification for the Teads Recommendation API (API Version 2.0). This API can be used to fetch a structured JSON payload of sponsored content and organic recommendations tailored to conversational interfaces.

---

1. API Endpoint & Headers

The API is a POST call to the Teads recommendation engine. It combines environment metadata with real-time contextual signals to return a tailored multi-part response.

• API URL: https://mv.outbrain.com/Multivac/api/in-chat-recs
• Required Headers:
  • User-Agent: The client's user agent string (e.g., Mozilla/5.0...).
  • X-Forwarded-For: The end-user's IP address.

---

2. Parameter Specification

A. Authentication & Environment

Parameter	Type	Required	Description
key	String	Yes	The unique Partner API Key used to authenticate the request.
contentUrl	String	Yes (For Web -if bundleUrl and portalUrl do not apply)	The canonical URL of the host page for contextual crawling.
bundleUrl	String	Yes (For apps - if contentUrl and portalUrl do not apply)	The URI-encoded store URL of the App.
portalUrl	String	Yes (For native applications- If contentUrl & bundleUrl do not apply)	URL representing the context where the ad placement is presented to users. Does not need to be a reachable/crawlable URL.
lang	String	Yes (Can only be used in conjuction with portalUrl, otherwise it has to be omitted)	The 2-letter language code (ISO-639-1-alpha-2). Must be added if bundleUrl or portalUrl is sent.
widgetJSId	String	Yes	The UI placement identifier (e.g., APP_16) that defines layout constraints and configurations, Each Widget_ID has a fixed number of recommendations and image size.
bf	FLOAT	No	Bid floor parameter, based on CPM.

B. Contextual Targeting (Request Body)

These parameters drive the relevance of the recommendations:

• keywords (Array): A comma-delimited list of high-intent search terms (e.g., ["shopping","birthday","manga"]).
• iabCategories (Array): A comma-delimited IAB V1 list of standardized industry categories used to filter content types (e.g., ["IAB1","IAB2-1"]).
• chat (String): Additional contextual free text data. (e.g., ["Free text chat"])

C. Response Control

• response_version (String): Must be set to 2.0.
• response_types (Array): Specifies the requested engine types to populate the response.
  • Supported values: catOrKeywords, embeddings,BrandDisplay

---

3. Response Schema

The response provides multiple content sets typically grouped by the recommendation engine’s type. Each set contains a list of documents and a high-level tracking URL.

Root Level

• version (String): The API version (e.g., "2.0").
• results (Object): Contains the content payloads grouped by recommendation type.

Result Groups (when response type is catOrKeywords, embeddings)

Each object within results follows this structure:

• documents (Array): A list of content items.
• tracking (Object):
  • reportServed, URL To be triggered when any of the recommendations have been served.

Document Object

Field	Type	Description
pos	String	The index position of the item in the response.
adType	String	Type of ad (e.g., "Brand", "Search").
url	String	The click-through destination.
thumbnail_url	String	Image asset URL for the recommendation.
source_display_name	String	The brand or publisher name.
content	String	The headline or title of the ad/article.
target_domain	String	The domain where the user will land.
cta	String	(Optional) Call-to-action text.
cpm/net_cpc	FLOAT	The financial value (CPM or CPC) associated with the item.
doc_tracking	Object	Contains tracking pixels (pixels) and viewability logs (on-viewed).

The display Object

This object contains the core technical assets required to render the advertisement when the response_types parameter in the API request includes BrandDisplay, located within the results root.

Field	Type	Description
html	String	The actual code snippet (usually a <script> tag) used to load the ad creative.
div_id	String	The unique identifier intended for the ad's container element.
placement_id	Integer	The specific Teads internal ID for the ad placement.
width	Integer	The intended width of the ad unit (e.g., 1 for fluid/responsive or specific pixel values).
height	Integer	The intended height of the ad unit.
outiframe_allowed	Boolean	Indicates if the ad script is permitted to run within a cross-domain iframe.
om	Boolean	Open Measurement signal; indicates if the ad supports OM SDK for third-party viewability.

---

---

4. Data Flow & Tracking (Monetization)

To ensure accurate revenue attribution and campaign performance reporting, the following tracking lifecycle must be strictly followed. Every recommendation returned in the results object contains specific URLs that must be triggered at different stages of the user experience.

---

A. Serve Confirmation (reportServed)

The Serve Confirmation is the first signal in the monetization chain. It confirms that the Teads engine successfully delivered content to your application and that the widget is ready to be displayed.

• Action: Fire a GET request to the tracking.reportServed URL.
• Location: Found at the root of each engine type in the results object (e.g., results.embeddings.tracking.reportServed).
• Timing: Trigger this as soon as the API response is received and the container/widget is initialized.
• Context: This signal is mandatory for Teads to validate that the request resulted in a successful "fill".

---

B. Impression & Third-Party Tracking (pixels)

The Impression Pixels notify third-party bidders and internal systems that an ad has been successfully rendered within the chat interface.

• Action: Iterate through the doc_tracking.pixels array for each document and fire every URL contained within.
• Location: Found within the doc_tracking object of an individual document.
• Timing: Trigger these as soon as the ad asset (thumbnail or BrandDisplay HTML) is injected into the chat UI.
• Macro Handling: Some URLs may contain an ${AUCTION_MIN_TO_WIN} macro. If you are not running a client-side auction, this can typically be defaulted to 0 or the clearing price to ensure the pixel records correctly.

---

C. Viewability Tracking (on-viewed)

The Viewability signal is the most critical component for premium monetization. Many high-value "Brand" campaigns are billed only when an ad is confirmed to be "Viewable" by the user.

• Action: Fire a GET request to the URLs listed in the on-viewed array.
• Location: Found within doc_tracking.on-viewed.
• Timing: Strict Requirement: These URLs must only be triggered when the specific ad enters the user's visible viewport.
• Implementation Note: In conversational interfaces, this usually occurs when a user scrolls through the chat history and the ad bubble becomes visible on the screen.
• Revenue Impact: Failure to trigger viewability pixels will result in zero revenue for any campaign sold on a "Viewable CPM" (vCPM) basis, even if the ad was technically "served".

---

Tracking Summary Table

Signal Type	JSON Path	Trigger Event	Priority
Serve	results.{type}.tracking.reportServed	Widget/Container Load	High
Impression	results.{type}.documents[n].doc_tracking.pixels	Ad Rendering/Initialization	High
Viewability	results.{type}.documents[n].doc_tracking.on-viewed	Ad enters visible viewport	Critical

---