Skip to main content

Teads In-Chat API (V2.0): Example Use Cases

This documentation provides technical implementation examples for the Teads Recommendation Request (API Version 2.0). This API is a POST call used to fetch a structured JSON payload of sponsored and organic recommendations for conversational interfaces.

🏗 Global Request Configuration​

Every integration scenario uses the following baseline configuration:

  • Endpoint: https://mv.outbrain.com/Multivac/api/in-chat-recs
  • Method: POST
  • Mandatory Headers:
    • User-Agent: The client's browser or device string.
    • X-Forwarded-For: The end-user's public IP address.
    • Content-Type: application/json.

Parameter Mapping​

To ensure successful delivery, parameters must be placed correctly:

  • URL Query Parameters: key, widgetJSId, response_version, response_types, contentUrl, bundleUrl, portalUrl, lang, and Bf.
  • JSON Request Body: keywords, iabCategories, and chat.

🌐 Use Case 1: Web example (contentUrl)​

Scenario: A chatbot hosted on a standard website where the page content is publicly crawlable.

URL Parameters​

?key=YOUR_KEY&widgetJSId=APP_12&response_version=2.0&response_types=catOrKeywords&contentUrl=example-research.com

JSON Request Body​

{
    "keywords": ["finance news", "investing"],
    "iabCategories": ["IAB13"],
    "chat": "I am looking for the latest updates on market trends."
}

🌐 Use Case 2: App example (bundleUrl)​

Scenario: A native iOS or Android application. For mobile environments, the lang parameter is mandatory.

URL Parameters​

?key=YOUR_KEY&widgetJSId=APP_12&response_version=2.0&response_types=BrandDisplay,embeddings&bundleUrl=https%3A%2F%2Fapps.apple.com%2Fapp%2Fid123&lang=en

JSON Request Body​

{
    "keywords": ["finance news", "investing"],
    "iabCategories": ["IAB13"],
    "chat": "I am looking for the latest updates on market trends."
}

🌐 Use Case 3: App example (portalUrl)​

Scenario: An AI assistant in a messaging app or internal tool where a crawlable public URL does not exist. The lang parameter is mandatory.

URL Parameters​

?key=YOUR_KEY&widgetJSId=APP_12&response_version=2.0&response_types=catOrKeywords,BrandDisplay&portalUrl=https://examplemessenger.local&lang=en

JSON Request Body​

{
    "keywords": ["finance news", "investing"],
    "iabCategories": ["IAB13"],
    "chat": "I am looking for the latest updates on market trends."
}