API contract: POST /api/chat

Auth: header Authorization: Bearer <partner key>. Sandbox and production use different keys and base URLs (issued at onboarding).

One call per conversation turn, synchronous with the assistant's reply. Body ≤ 256 KB — send the last ~8–12 turns, not the whole history.

Request

{
  "messages": [ {"role":"user","content":"need a laptop backpack"} ],
  "geo": "MY",
  "session_id": "abc123",
  "lang": "en"
}

• messages[] — required; conversation history, roles user / assistant.
• geo — required; user country, ISO-3166 alpha-2 (MY, ID, BR…). Inventory and rates depend on it.
• session_id — optional; stable per user session, for fair per-user limits and anti-fraud.
• lang — optional; UI language hint.
• Optional header X-Forwarded-For with the end-user IP for per-user limits. No PII is required.

Response 200

{
  "reply": "…assistant text, always shown…",
  "ad": {
    "type": "product",
    "title": "…", "desc": "…", "price": "MYR 129",
    "image": "https://cdn…/p.jpg",
    "sponsored": true,
    "click_url": "https://api.indoleads.ai/c/<token>"
  },
  "intent": { "show_ad": true, "confidence": 0.72, "category": "…" }
}

• reply — always render.
• ad — object or null (no commercial intent). type: product | offer | coupon (has code) | banner. Render title, desc, price, image; link to click_url with rel="sponsored noopener" target="_blank" and a visible Sponsored label. Never rewrite or wrap click_url.
• intent — for your analytics.

Status codes

Latency: bound by the LLM — 0.8–3 s, rarely 5–8 s. Set client timeout ≥ 10 s. On error/timeout/ad:null show the reply without a card — ads must never break the chat.