Settings Configuration

This document defines all configurable settings required to integrate the In-Chat Recommendations API across environments (Development, Staging, and Production).

It is based on the current technical integration guide:

Endpoint: POST https://mv.outbrain.com/Multivac/api/in-chat-recs
Authentication: API Key passed via query parameter key
Contextual signals: keywords + iabCategories passed in request body
Impression reporting: fire tracking.reportServed with &pos=X-Y

1) Overview

To call the In-Chat Recommendations API consistently across environments, your application should externalize configuration values such as:

API endpoint URL
API Key
Widget identifier (widgetJSId)
Default request flags (cors, optional testMode)
Request timeouts

✅ Store configuration in environment variables or secure secrets management.
❌ Never hardcode API keys in client-side repos or public codebases.

2) Environments

Environment	Purpose	Notes
Development	Local testing / QA	Use `testMode=true` to avoid polluting production
Staging	Pre-production validation	Uses the same endpoint with limited traffic
Production	Live traffic and monetization	Requires approved key + placement

3) Core Endpoint Settings

Production Endpoint

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

Method: POST
Authentication: API Key passed as query parameter key

4) Core Configuration Variables

Setting	Required	Description	Example
`TEADS_INCHAT_RECS_ENDPOINT`	✅	Full In-Chat Recommendations API endpoint	`https://mv.outbrain.com/Multivac/api/in-chat-recs`
`TEADS_API_KEY`	✅	API key used in `key` query param	`abcd1234`
`TEADS_WIDGET_JS_ID`	✅	Widget ID provided by Teads	`APP_12`
`TEADS_CORS`	✅	Must be `true` for browser/chat environments	`true`
`TEADS_TEST_MODE`	❌	Enable test mode during development	`true`

5) Runtime Parameters (Provided Per Request)

These are not static settings, but values your app must supply at runtime.

Parameter	Required	Type	Description	Example
`contentUrl`	✅	string	URL-encoded host page	`test.com`
`keywords`	✅	string[]	Chat intent/topic signals	`["investing","savings"]`
`iabCategories`	✅	string[]	IAB category signals	`["IAB13"]`

6) How Settings Map to the API Request

Query String Mapping

API Parameter	Comes From
`key`	`TEADS_API_KEY`
`contentUrl`	runtime input
`widgetJSId`	`TEADS_WIDGET_JS_ID`
`cors`	`TEADS_CORS`
`testMode`	`TEADS_TEST_MODE` (optional)

Full Example URL

https://mv.outbrain.com/Multivac/api/in-chat-recs?key=YOUR_KEY&contentUrl=test.com&widgetJSId=APP_12&cors=true&testMode=true

Body Example

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

Settings Configuration

1) Overview​

2) Environments​

3) Core Endpoint Settings​

Production Endpoint​

4) Core Configuration Variables​

5) Runtime Parameters (Provided Per Request)​

6) How Settings Map to the API Request​

Query String Mapping​

Full Example URL​

Body Example​