Postman Collection Guide

This document explains how to use the Teads AI Chatbot SDK Postman Collection to test and validate Measurement, Publisher (Organic), and Marketer (Paid) API integrations.

---

1. Overview

The Postman collection includes four main folders:

Folder	Description
Measurement	Test SDK event tracking (load, view, click)
Publisher (Organic)	Fetch non-paid organic content recommendations
Marketer (Paid)	Fetch paid ad recommendations
Combined Flows	Simulate full chatbot lifecycle (load → organic → paid)

Each request is preconfigured with dynamic variables and testMode=true for safe QA testing.

---

2. Download and Import

Download JSON Collection:
teads-ai-chatbot-sdk-postman-collection.json

To import into Postman:

1. Open Postman.
2. Click Import → Upload Files.
3. Select the downloaded .json file.
4. Postman will automatically create the folder structure and environment variables.

---

3. Variables Overview

Variable	Example	Description
base_url	https://mv.outbrain.com	Root API endpoint
base_path	/Multivac/api/platforms	Base path for all requests
contentUrl	https://example.com	The canonical page/chatbot URL
contentUrlEncoded	(auto-generated)	URI-encoded version of contentUrl
measurement_key	abcd123-measure	API key for measurement events
content_key	abcd456-content	API key for organic/paid flows
measurement_widget_id	widget-measure-01	Widget ID for measurement flow
organic_widget_id	widget-organic-01	Widget ID for organic flow
paid_widget_id	widget-paid-01	Widget ID for paid flow
news	latest	Organic news filter
newsFrom	US	Origin country for content
extid	chatbot_load	Event type for measurement
testMode	true	Enables sandbox mode

---

4. Measurement Flow

Example: Measurement — chatbot_load

• Fires a single event for chatbot initialization.
• Uses measurement key and widget ID.
• Response body can be ignored.

GET https://mv.outbrain.com/Multivac/api/platforms?contentUrl={{contentUrlEncoded}}&key={{measurement_key}}&widgetJSId={{measurement_widget_id}}&idx=0&format=vjnc&cors=true&extid=chatbot_load&testMode=true

Other Measurement Events

Event	Purpose
unit_view	When ≥50% of unit visible for 1s
unit_click	When user clicks a recommendation

---

5. Publisher (Organic) Flow

Purpose: Fetch organic recommendations.

GET https://mv.outbrain.com/Multivac/api/platforms?contentUrl={{contentUrlEncoded}}&key={{content_key}}&widgetJSId={{organic_widget_id}}&idx=0&format=vjnc&cors=true&news={{news}}&newsFrom={{newsFrom}}&testMode=true

• newsFrom can be customized by user geolocation.
• Responses use the vjnc JSON schema.

---

6. Marketer (Paid) Flow

Purpose: Fetch paid ad recommendations.

GET https://mv.outbrain.com/Multivac/api/platforms?contentUrl={{contentUrlEncoded}}&key={{content_key}}&widgetJSId={{paid_widget_id}}&idx=0&format=vjnc&cors=true&testMode=true

• Uses paid widget ID.
• Paid recommendations usually start with http://paid.outbrain.com/... in their redirect URLs.

---

7. Combined Flow (Full Chatbot Lifecycle)

Simulate an entire chatbot session using three chained requests:

1. Fire chatbot_load event (Measurement API)
2. Fetch organic content (Publisher API)
3. Fetch paid content (Marketer API)

All three requests can be run sequentially in the Combined Flows → load + organic + paid folder.

---

8. Pre-request Script

Each request runs a pre-request script that automatically encodes your contentUrl into contentUrlEncoded:

const raw = pm.variables.get('contentUrl') || '';
const enc = encodeURIComponent(raw.replace(/[#?].*$/, '')); // remove query/fragments
pm.collectionVariables.set('contentUrlEncoded', enc);

You do not need to encode it manually.

---

9. Environment Setup (Optional)

You can create a Postman Environment for each stage:

Variable	Dev Example	Prod Example
contentUrl	https://dev.example.com	https://example.com
measurement_key	dev-measure-key	prod-measure-key
content_key	dev-content-key	prod-content-key
testMode	true	false

---

10. Response Validation

Field	Description
doc.url	Target redirect for clicks
doc.orig_url	Original article destination
doc.pixels	Tracking pixel URLs
doc.jsTrackers	Optional JS trackers
doc.clickTrackers	Fired when user clicks

---

11. Troubleshooting

Issue	Cause	Resolution
403 Forbidden	Invalid key or widget ID	Verify credentials with Teads
Empty JSON	Missing required param	Check news, format, or cors
CORS blocked	Missing cors=true	Add query param
Clicks not tracked	Modified redirect URL	Use doc.url exactly as returned

---

12. Best Practices

• Use testMode=true during QA and staging.
• Ensure all requests use HTTPS.
• Keep API keys private and server-injected.
• Run Measurement events within 3 minutes of content render.

---

13. Related Files

File	Description
Getting Started Guide	Introductory SDK setup instructions
Integration Guide	End-to-end integration details
Privacy Guide	Data handling and compliance requirements
Settings File	Environment configuration and variables
Examples File	Ready-to-use language examples

---

© 2025 Teads AI Platform. All rights reserved.