Skip to content

Quickstart: REST path

No SDK, no agent — just your fetch key and HTTP. Serve, track, and convert an in-chat ad with three requests. Time to first ad: about 5 minutes.

1. Get your fetch key

Advertising.chat is in private beta — request access if you don't have an account yet. Sign in to the Advertising.chat Console and copy the fetch key for your app — new accounts get one automatically, shown on Get Started (also under API Keys, /admin). That is the only credential you need. Keep it server-side (except for the public web embed, where the key is a publisher tag by design).

2. Fetch an ad

curl -X POST "https://ads.advertising.chat/v1/fetch/v2?key=YOUR_FETCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context": "User asked for gift ideas for a coffee lover."}'

A 200 returns a rendered card:

{
  "messageId": "direqt-6a3f…",
  "format": "direqt",
  "payload": { "title": "Acme Coffee Grinder", "actions": [ … ] }
}

A 204 means there was no good ad to show right now — normal, not an error. Continue the conversation without one.

Keep the messageId — it ties every later event back to this impression.

Render payload on your channel and label it clearly "Sponsored." The action URLs in the payload are already click-tracking redirects — present them verbatim. When the user taps one, the click is recorded automatically and they are 302-redirected to the advertiser. That is your first served, measured, clickable ad.

4. Report events and conversions

Report lifecycle events and conversions back to the event endpoint, passing the fetch's messageId as fetchEventId:

curl -X POST "https://ads.advertising.chat/v1/event?key=YOUR_FETCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": 2, "eventType": "conversion", "fetchEventId": "direqt-6a3f…"}'

See the Ad Events reference for the full event stream, conversion pixels, and offline conversion upload.

Next