Lumi API for Bots

Server-side REST integration for AI bots — Discord, Telegram, Slack, or any platform where you can't ship a JS bundle to the user. One POST /v1/ad-request from your bot's response handler returns an ad payload. Optional helper libraries (lumi-discord, lumi-telegram, lumi-slack) format the response into each platform's native message type.

The one endpoint you'll call

POST https://boostboss.ai/v1/ad-request
Authorization: Bearer ${API_KEY}
Content-Type: application/json

{
  "format": "embed",                       // "embed" | "card" | "text" | "native" | "banner"
  "context": "user asked about Stripe billing",
  "platform": "discord",                   // optional: "discord" | "telegram" | "slack" | string
  "user_region": "US",                      // optional, ISO region
  "user_language": "en",                    // optional, ISO 639-1 code
  "session_id": "sess_abc123"                // optional, used for frequency capping
}

Response shape (with ad)

{
  "ad": {
    "ad_id":            "cmp_...",
    "auction_id":       "auc_...",
    "type":             "image",
    "headline":         "...",
    "body":             "...",
    "image_url":        "https://...",
    "cta_label":        "...",
    "click_url":        "https://boostboss.ai/api/track?...&event=click",
    "impression_url":   "https://boostboss.ai/api/track?...&event=impression",
    "disclosure_label": "Sponsored",
    "sandbox":          false
  }
}

Response shape (no fill)

{ "ad": null, "reason": "no_campaigns" }

Discord example

import { toDiscordEmbed, toDiscordComponents } from '@boostbossai/lumi-discord';

// Inside your Discord bot's response handler:
const { ad } = await fetch('https://boostboss.ai/v1/ad-request', {
  method:  'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BBX_API_KEY}`,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    format:   'embed',
    context:  userQuery,
    platform: 'discord',
  }),
}).then(r => r.json());

if (ad) {
  await message.reply({
    content: aiResponse,
    embeds:     [toDiscordEmbed(ad)],
    components: [toDiscordComponents(ad)],
  });
  fetch(ad.impression_url).catch(() => {});  // fire-and-forget
}

Optional helper libraries

Each helper library is a tiny pure-transform convenience wrapper around the Lumi API for Bots (~30–50 lines, zero runtime dependencies) that maps the generic ad object to the target platform's native format. They're optional — you can hit the REST endpoint directly with fetch and format the response yourself if you'd rather not add a dependency. Install only the helper that matches your platform.

Impression tracking

After your bot sends the message, fire the impression_url as a fire-and-forget GET:

fetch(ad.impression_url).catch(() => {});  // no auth, no body, no retry needed

The beacon is auction-keyed and idempotent — duplicate fires from retries are de-duplicated server-side. Don't fire it before the message is actually sent; the impression count drives publisher revenue.

Click tracking

The click_url we return is already a tracking redirect — link your CTA button to it directly. Don't substitute the underlying advertiser URL; that bypasses tracking and breaks revenue attribution.

Conversion tracking

Fire a conversion when the user takes the action your ad campaign was bidding on (signup, purchase, lead, tool invoke). Conversions tie back to the original auction via auction_id, so attribution and CPA billing work end-to-end.

POST https://boostboss.ai/api/track
Content-Type: application/json
X-Lumi-Source: rest-api

{
  "event":           "conversion",
  "campaign_id":     "camp_...",         // from the original ad payload
  "auction_id":      "auc_...",          // from the original ad payload
  "conversion_type": "signup",           // matches campaigns.conversion_event_types
  "value":           29.99,                // USD; required for ROAS optimization
  "currency":        "USD",             // optional; ISO 4217
  "external_id":     "order_98123"      // optional — your order/user id
}

Returns { "tracked": true, "event": "conversion", ... }. Conversions are deduplicated per (auction_id, "conversion") tuple — retries are safe.

If your conversion happens on a different page from the impression (typical web flow), the standalone pixel.js snippet auto-reads bbx_auc from the click-through URL — much less plumbing than POSTing yourself. See the conversion beacon doc.

Rate limits

1,000 requests/minute per publisher. Burst capacity above the steady rate is allowed for short windows. Email hello@boostboss.ai if you're approaching the cap and need it raised.

Error codes

Testing

Use bearer sk_test_demo in development — sandbox short-circuits the auction and returns a fixed creative from a small rotation pool. No real demand-side calls; impressions are tagged is_sandbox=true in the database and never accrue revenue or charge advertisers.

curl -sS https://boostboss.ai/v1/ad-request \
  -H "Authorization: Bearer sk_test_demo" \
  -H "Content-Type: application/json" \
  -d '{"context":"smoke test","format":"embed","platform":"discord"}'