Ads

Request contextual ads

Analyzes conversation context and returns relevant ads. One ad is returned per placement in the request.

How It Works

Send the user's current message (and optionally the previous assistant response for context)
Gravity extracts intent, matches against active ad campaigns, runs a real-time auction, and generates ad creative
You receive an array of ad objects — one per placement

Message Context

Include the user's current query and the previous assistant response (if available) for better ad matching.

First turn: Just the user query
Follow-up turns: Previous assistant response + current user query

No-Fill (204)

A 204 No Content response means no suitable ad was found. This is normal — not every request will return an ad. Handle this gracefully by hiding or collapsing your ad slot.

Impression Tracking

When an ad is displayed to the user, fire a GET request to the impUrl. This is required for billing. Impression URLs expire 5 minutes after the ad response is generated — do not cache or defer ad responses.

For clicks, redirect users through clickUrl. It handles attribution and forwards to the advertiser's landing page.

Additional Context

The request body accepts additional key-value pairs beyond the documented fields. Any extra structured data you include (e.g., app-specific context, IDE metadata) is used to improve ad relevance.

Request body

sessionIdstring required

Session identifier for the current conversation. Used for frequency capping (limiting how often a user sees the same ad within a session) and session-level analytics.

Use your existing chat/conversation session ID.

userIdstring required

Your platform's identifier for the end user. Required. Enables per-user ad learning, cross-session frequency capping, and user-level attribution.

excludedTopicsstring[]

Topics or categories to exclude from ad matching. Use this for brand safety.

Examples: ["gambling", "alcohol", "tobacco", "politics"]

relevancynumber

Minimum relevancy score threshold (0.0–1.0). Higher values return only highly relevant ads but reduce fill rate.

If omitted, the system default is used. Start with 0.2–0.4 and adjust based on your fill rate vs. relevance tradeoff.

testAdboolean

When true, returns a test ad with placeholder tracking URLs. No billing occurs. Use this during integration testing.

Set to false (or omit) when going live.

Example request

{
  "messages": [
    {
      "role": "user",
      "content": "What running shoes do you recommend for a marathon?"
    }
  ],
  "sessionId": "session-abc123",
  "placements": [
    {
      "placement_id": "main-ad"
    }
  ],
  "userId": "user-xyz789",
  "device": {
    "ip": "203.0.113.42",
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "country": "US",
    "os": "macOS",
    "ifa": "6D92078A-8246-4BA4-AE5B-76104861E7DC"
  },
  "user": {
    "email": "user@example.com",
    "phone": "+15551234567",
    "age": "25",
    "keywords": "fitness, running, sports"
  },
  "excludedTopics": [
    "gambling",
    "alcohol"
  ],
  "relevancy": 0.3
}

Response

Ads matched and returned. The response is a JSON array with one ad per matched placement. If fewer campaigns match than placements requested, the array may be shorter than the number of placements.

adTextstring required

AI-generated ad copy tailored to the conversation context and advertiser branding guidelines.

titlestring

Ad title or headline. Typically the brand or product name.

ctastring

Call-to-action text (e.g., "Learn More", "Shop Now", "Get Started").

brandNamestring

The advertiser's brand name.

urlstring uri

The advertiser's landing page URL. Display this to show users where the ad links to.

faviconstring uri

URL to the advertiser's favicon. Use alongside the brand name for visual identity. Recommend a fallback for load errors.

impUrlstring uri

Impression tracking URL. Fire a GET request to this URL when the ad is displayed to the user. Required for billing.

Important: Impression URLs expire 5 minutes after the ad response is generated. Fire promptly when the ad is rendered. Do not cache ad responses.

clickUrlstring uri

Click tracking URL. Use this as the href for the ad link. Handles click attribution and redirects to the advertiser's landing page (url).

placementstring

The placement type this ad was generated for. Matches one of the placement values from the request.

placement_idstring

The placement ID this ad corresponds to. Use this to map response ads back to specific slots in your UI.

Example response

[
  {
    "adText": "Fuel your marathon with GelPro energy gels — trusted by 10,000+ runners!",
    "title": "GelPro Energy Gels",
    "cta": "Shop Now",
    "brandName": "GelPro",
    "url": "https://gelpro.com/runners",
    "favicon": "https://gelpro.com/favicon.ico",
    "impUrl": "https://api.trygravity.ai/t/imp?p=eyJ...",
    "clickUrl": "https://api.trygravity.ai/t/click?p=eyJ...",
    "placement": "below_response",
    "placement_id": "main-ad"
  }
]