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,
"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 turns 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.
| Field | Type | Description |
|---|
ad_offset | int | Min turn number before first ad. null uses dashboard default. 0 disables the offset check. |
max_frequency | int | Min turns between consecutive ads. null uses dashboard default. 0 disables the frequency check. |
Example
{
"config": {
"ad_offset": 3,
"max_frequency": 5
}
}
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, product images are never included in the response. The ad is returned with a logo derived from the advertiser’s domain, or no image at all. Use this when your UI doesn’t support displaying images.
{
"config": {
"image_enabled": false
}
}
Experiments
Beta — available to all publishers.
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.
| Field | Type | Description |
|---|
experiment_tag | string (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" } }
offset_3 vs offset_5 in your dashboard analytics.
Split your traffic between the two variants and compare metrics in your dashboard analytics. 