Technical Integration Guide

API Endpoint

Environment	URL
Production	https://mv.outbrain.com/Multivac/api/in-chat-recs

Method: POST
Authentication: API Key passed as a query parameter.

Request Parameters

URL Query Parameters

Parameter	Required	Type	Description
key	Yes	String	Your unique API Key.
contentUrl	Yes	String	URL-encoded host page (e.g., test.com).
widgetJSId	Yes	String	Fixed value provided by Teads (e.g., APP_12).
cors	Yes	Boolean	Set to true.
testMode	No	Boolean	Set to true for development testing.

JSON Body (Contextual Signals)

Use the body to provide real-time signals from the chat conversation:

{
  "keywords": ["investing", "savings", "personal finance"],
  "iabCategories": ["IAB13"]
}

3. Understanding the Response

When a request is successful, you will receive a JSON object containing a list of documents. Each document represents an individual ad recommendation.

Response Field Definitions

Field	Description	Use Case
url	The destination link for the ad.	Wrap the ad title or image in this link.
thumbnail_url	The URL for the ad's creative image.	Display this as the "Ad Card" image.
content	The headline/title of the advertisement.	The main text the user reads.
source_display_name	The name of the advertiser/brand.	Displayed as "Sponsored by [Name]".
target_domain	The domain of the advertiser website.	Displayed for transparency (e.g., "clubmed.fr").
pos	The unique index of the ad in the list.	Critical: Used for impression reporting.
cta	(Optional) Call to action text.	The text for the button (e.g., "Learn More").

Tracking Object

The tracking object contains the reportServed URL. This is the endpoint used to notify Teads that an ad was actually seen by the user.

---

4. Reporting Impressions (Pixels)

To ensure monetization, you must fire the reportServed pixel as soon as the ads are rendered in the chat window.

Logic

1. Locate the reportServed URL.
2. Append the pos value of all displayed ads to the URL using the format &pos=X-Y.
3. Fire the URL as a GET request or via navigator.sendBeacon.

Example

If the response contains 5 ads and you display the first (pos: 0) and third (pos: 2), the pixel should look like this:

https://mcdp-nldc1.outbrain.com/writePartialStats?token=...&pos=0-2

---

5. Implementation Example (JavaScript)

async function getAds() {
  const url = "https://mv.outbrain.com/Multivac/api/platforms?contentUrl=example.com&widgetJSId=APP_12&key=YOUR_KEY&idx=0&format=vjnc&cors=true";
  
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ keywords: ["finance"], iabCategories: ["IAB13"] })
  });

  const data = await response.json();
  
  // Render the first ad headline to the user
  const ad = data.documents[0];
  console.log(`Displaying Ad: ${ad.content} by ${ad.source_display_name}`);

  // Report that the first ad (pos 0) was served
  if (data.tracking && data.tracking.reportServed) {
    const pixel = `${data.tracking.reportServed}&pos=0`;
    navigator.sendBeacon(pixel); 
  }
}