Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thrads.ai/llms.txt

Use this file to discover all available pages before exploring further.

The config object lets you control how ads are served per request — pacing, creative constraints, and analytics tags. All fields are optional and fall back to defaults set on your chatbot in the platform dashboard. 
{
  "config": {
    "ad_offset": 3,
    "max_frequency": 5,
    "max_headline_chars": 60,
    "image_enabled": true,
    "restricted_click_area": false,
    "experiment_tag": "variant_a"
  }
}

​
Ad Pacing

Controls when and how often ads appear in a conversation. Two checks run before any auction logic:
  • Ad Offset (ad_offset) — minimum turns before the first ad in a conversation
  • Max Frequency (max_frequency) — minimum number of requests between consecutive ads
When pacing blocks a request, the API returns a 200 OK with "bid": null and a message indicating the reason — same as a no-bid. Continue without an ad.
FieldTypeDescription
ad_offsetintMin turn number before first ad. null uses dashboard default. 0 disables the offset check.
max_frequencyintMin requests between consecutive ads. For example, 5 means an ad can appear at most once every 5 requests. null uses dashboard default. 0 disables the frequency check.

​
Example

{
  "config": {
    "ad_offset": 3,
    "max_frequency": 5
  }
}
This says: “Don’t show ads before turn 3, and require at least 5 requests between consecutive ads.” The system tracks request counts automatically — no need to send turns_from_last_ad.

​
Creative Constraints

Control what the ad creative looks like to fit your UI.

​
Headline Limit

When max_headline_chars is set, the system guarantees no headline exceeds the limit. If no creative fits, no ad is returned. 
{
  "config": {
    "max_headline_chars": 50
  }
}

​
Image Control

When image_enabled is false, the response is forced into text mode: placement is "text", the image_url field is omitted entirely, and an advertiser logo is returned in logo_url instead. Render the logo on your card. Use this when your UI doesn’t support product imagery, or when you want a more compact card. See Ad Formats & Rendering — Sponsored Message for the full text-mode vs image-mode response shapes. 
{
  "config": {
    "image_enabled": false
  }
}

​
Click Area

Set restricted_click_area to true if your UI only makes specific elements clickable — logo, advertiser name, CTA button — rather than the entire ad surface. This is an analytics-only signal: the response payload is identical and you wire up the click handlers however you already do. We use the flag to segment performance metrics (CTR, dwell time) by click-zone style so you can compare your restricted layout against fully-clickable peers. 
{
  "config": {
    "restricted_click_area": true
  }
}
Defaults to false (full ad surface assumed clickable).

​
Experiments

Beta — available to all publishers.
Use experiment_tag to run A/B tests on your integration. Tag each request with a label (max 30 characters) and the tag is recorded on every impression. Compare performance metrics across variants in your dashboard.
FieldTypeDescription
experiment_tagstring (max 30 chars)A/B test label. Recorded on every impression for analytics segmentation.

​
Example

Test whether showing ads after turn 3 vs turn 5 performs better: 
// Variant A
{ "config": { "ad_offset": 3, "experiment_tag": "offset_3" } }

// Variant B
{ "config": { "ad_offset": 5, "experiment_tag": "offset_5" } }
Split your traffic between the two variants and compare offset_3 vs offset_5 in your dashboard analytics.