Skip to main content

​
Requesting an Ad Format

Use the ad_formats field in your bid request to specify which formats your integration can render. The server picks the best match and the response includes an ad_format field confirming what was returned. When ad_formats is omitted, it defaults to ["sponsored_message"] for contextual requests and ["sponsored_prompt"] for opener requests.

​
Available Formats

Formatad_formats valueStatus
Sponsored Messagesponsored_messageLive
Sponsored Promptsponsored_promptLive
CarouselcarouselComing soon
Sponsored Pollsponsored_pollComing soon
Use the ad_format field in the response to determine which format was returned and render accordingly. A native ad card displayed inline in the conversation. Includes a headline, description, optional image, and a call-to-action.
Sponsored message example
Response fields: ad_format, advertiser, domain, headline, description, cta_text, url, image_url 
{
  "ad_format": "sponsored_message",
  "price": 5.50,
  "advertiser": "Nike",
  "domain": "nike.com",
  "headline": "Premium Running Shoes",
  "description": "Perfect for marathon training. Lightweight and comfortable.",
  "cta_text": "Shop Now",
  "url": "https://ssp.thrads.ai/api/v1/tracking/redirect?token=abc123",
  "image_url": "https://cdn.example.com/nike-shoes.jpg",
  "dsp": "thrad_dsp",
  "bidId": "bid_abc123"
}
FieldDescription
ad_formatAlways "sponsored_message" for this format.
priceClearing price (CPM) in dollars — what the publisher earns.
advertiserBrand name of the advertiser (e.g. "Nike"). In rare cases this may return a domain (e.g. "nike.com") as a fallback when the brand name is not available. Your UI should handle both gracefully.
domainAdvertiser website domain (e.g. "nike.com").
headlineAd headline. Respects config.max_headline_chars when set.
descriptionAd body text. May be null.
cta_textCall-to-action text. May be absent — default to “Learn More” in your UI.
urlClick tracking URL. Always use this for clicks — it tracks the click and redirects to the landing page.
image_urlAd image URL. Only present when config.image_enabled is true (default) and a product image is available. Render without an image if absent.
dspWinning DSP identifier.
bidIdBid identifier for tracking and debugging.
A set of sponsored follow-up questions displayed as clickable prompts before or during a conversation.
Sponsored prompt example
Response fields: ad_format, advertiser, sponsored_prompt, url, logo_url The response returns an array of bids, each containing a sponsored prompt: 
{
  "bids": [
    {
      "ad_format": "sponsored_prompt",
      "bidId": "bid_sp_001",
      "advertiser": "Nike",
      "sponsored_prompt": "What are the best running shoes for marathon training?",
      "url": "https://ssp.thrads.ai/api/v1/tracking/redirect?token=sp1",
      "logo_url": "https://cdn.example.com/nike-logo.png",
      "view_url": "https://ssp.thrads.ai/api/v1/tracking/view?token=v1"
    }
  ]
}
Coming soon — contact us at contact@thrad.ai for early access.
A scrollable set of ad cards, each with its own headline, image, and link. Useful for showcasing multiple products in a single slot.
Coming soon — contact us at contact@thrad.ai for early access.
An interactive poll sponsored by an advertiser. Engages users with a question and multiple-choice answers, with optional click-through on results.
Sponsored poll example

​
Response Handling

​
No Bid Response

{
  "requestId": "api_req_124",
  "timestamp": "2025-11-24T21:51:52.240297Z",
  "totalTime": 0.095,
  "status": "success",
  "message": "No bids",
  "data": {
    "bid": null
  },
  "error": null
}
A 200 OK response with "bid": null is not an error. It means the auction ran successfully but no DSP submitted a winning bid. This is normal behavior and should be handled gracefully in your UI.
Optimize Your Frontend for User ExperienceThe quality of your ad rendering directly impacts user engagement and revenue. Make sure to:
  • Use smooth animations when displaying ads
  • Ensure ads are visually distinct but not intrusive
  • Make the entire ad card clickable for better UX
  • Optimize images for fast loading
  • Use appropriate spacing and typography
  • Test on mobile and desktop devices
  • Ensure accessibility standards are met
Acceptable Ads Compliance: Your ad display should be compatible with the Acceptable Ads Standard. This ensures ads are non-intrusive, clearly labeled, and appropriately sized — helping maintain user trust and ad-blocker compatibility.