Group Ads

One ad shown to multiple viewers in a group chat.

POST /api/v1/ad/group

curl -X POST https://server.trygravity.ai/api/v1/ad/group \
  -H "Authorization: Bearer <your_publisher_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "group-chat-abc",
    "messages": [
      {"role": "user", "content": "has anyone tried that new coffee place downtown?"},
      {"role": "user", "content": "I heard they have great cold brew"},
      {"role": "assistant", "content": "Yes! A few new spots opened up recently."}
    ],
    "placement": {"placement": "group_chat", "placement_id": "gc-main"},
    "viewers": [
      {
        "email_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
        "device": {"ip": "1.2.3.4", "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)", "country": "US"}
      },
      {
        "email_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
        "device": {"ip": "5.6.7.8", "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)", "country": "US"}
      },
      {
        "email_hash": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
        "device": {"ip": "9.9.9.9", "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "country": "GB"}
      }
    ],
    "excludedTopics": ["gambling"],
    "relevancy": 0.3
  }'

Serve a single contextual ad to multiple users in a group chat. The engine runs one auction and generates one ad creative, then returns per-viewer impression and click URLs so each user’s engagement is individually tracked and billed.

Maximum 5 viewers per request. Each viewer gets a unique impUrl and clickUrl for individual attribution.

Headers

Authorization · string · required

Your Gravity API key. Format: Bearer <key>

Body

sessionId · string · required

Session identifier. Used for frequency capping and reporting. Typically the group chat ID.

messages · array

Conversation history from the group chat. Array of {role, content} message objects. The engine uses the last few messages for contextual matching.

placement · object · required

Single placement for the group chat ad slot.

Field	Type	Description
placement	string	Placement type — use "group_chat".
placement_id	string	Your slot identifier for this group chat.

viewers · array · required

Array of viewers in the group chat (1–5). Each viewer gets a unique impression/click URL in the response.

Field	Type	Required	Description
email_hash	string	Yes	SHA-256 hex digest of the viewer’s email (email.strip().lower()). Must be exactly 64 characters.
user	object	No	User context (same shape as the contextual endpoint user field).
device	object	No	Device signals — ip, ua, country, etc. Used for bot detection and geo targeting per viewer.

metadata · object

Optional. Arbitrary metadata forwarded to the engine for targeting and analytics.

excludedTopics · array

Optional. Array of topic strings to exclude from matching.

relevancy · number

Optional. Minimum relevancy threshold, 0.0–1.0. Falls back to publisher baseline when omitted.

testAd · boolean · default: "false"

Optional. When true, returns test creative and skips billing/metrics.

curl -X POST https://server.trygravity.ai/api/v1/ad/group \
  -H "Authorization: Bearer <your_publisher_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "group-chat-abc",
    "messages": [
      {"role": "user", "content": "has anyone tried that new coffee place downtown?"},
      {"role": "user", "content": "I heard they have great cold brew"},
      {"role": "assistant", "content": "Yes! A few new spots opened up recently."}
    ],
    "placement": {"placement": "group_chat", "placement_id": "gc-main"},
    "viewers": [
      {
        "email_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
        "device": {"ip": "1.2.3.4", "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)", "country": "US"}
      },
      {
        "email_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
        "device": {"ip": "5.6.7.8", "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)", "country": "US"}
      },
      {
        "email_hash": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
        "device": {"ip": "9.9.9.9", "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "country": "GB"}
      }
    ],
    "excludedTopics": ["gambling"],
    "relevancy": 0.3
  }'

Response

On a successful match the endpoint returns HTTP 200 with a single ad object and per-viewer tracking URLs:

{
  "adText": "Keep your cold brew fresh with amika's insulated cooler bag.",
  "title": "amika Insulated Cooler Bag",
  "brandName": "Amika",
  "cta": "Shop Now",
  "url": "https://www.amika.com/",
  "favicon": "https://www.google.com/s2/favicons?domain=www.amika.com&sz=64",
  "viewers": [
    {
      "email_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "impUrl": "https://api.trygravity.ai/ack?p=...",
      "clickUrl": "https://api.trygravity.ai/track/click?p=..."
    },
    {
      "email_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
      "impUrl": "https://api.trygravity.ai/ack?p=...",
      "clickUrl": "https://api.trygravity.ai/track/click?p=..."
    },
    {
      "email_hash": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
      "impUrl": "https://api.trygravity.ai/ack?p=...",
      "clickUrl": "https://api.trygravity.ai/track/click?p=..."
    }
  ]
}

Response fields

Field	Type	Description
adText	string	Generated ad copy, contextually matched to the conversation
title	string	Product/campaign title
brandName	string	Advertiser brand name
cta	string	Call to action text
url	string	Landing page URL
favicon	string	Brand favicon URL
viewers	array	Per-viewer tracking URLs (see below)

Viewer tracking object

Field	Type	Description
email_hash	string	Echoes back the viewer’s email hash
impUrl	string	Impression pixel URL — fire when the ad is visible to this viewer
clickUrl	string	Tracked click URL — use for ad links shown to this viewer

Null fields are omitted from the response.

Each viewer has their own impUrl and clickUrl. Fire the correct URL for each user — this is how per-viewer billing and attribution works. Do not reuse one viewer’s URLs for another.

How it works

1. One auction — the conversation context goes through a single auction to find the best-matching campaign.
2. One ad generation — a single ad creative is generated using the publisher’s configured prompt template and model.
3. Per-viewer fan-out — each viewer gets a unique tracking URL pair (impUrl + clickUrl) with their own click ID (grclid). Bot viewers (detected by user agent) are excluded from the response.
4. One engine event — a single engine event is logged with per-viewer data stored in the request context.

No ad available

When no ad matches the context (or the request times out, hits a bot filter for all viewers, or encounters an unrecoverable error), the endpoint returns HTTP 204 No Content with an empty body. Hide the ad slot in this case.