Skip to content

Quickstart: Serve an ad over REST

This quickstart shows you how to serve an in-chat ad with plain HTTP requests: fetch an ad, present it with its tracked links, and report an event. It takes about five minutes. To let an agent decide when to show ads instead, see the MCP quickstart.

Before you begin

  1. Get an Advertising.chat account. If you don't have one, request access.
  2. In the console, in the Monetize section, click Get Started, and copy your key from 1 · Your fetch key. Keep it on your server.

Fetch an ad

Send a POST to the Fetch API with your fetch key and a summary of the conversation:

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 response contains one ad, rendered as a card:

{
  "messageId": "direqt-6a3f…",
  "format": "direqt",
  "payload": {
    "title": "Acme Coffee Grinder",
    "subtitle": "Fresh grounds in seconds.",
    "imageUrl": "https://…",
    "actions": [{ "type": "Navigate", "text": "Shop now", "navigate": { "url": "https://ads.chat/…" } }]
  },
  "properties": {}
}

A 204 response means no ad fits this moment. Continue the conversation without one.

To get a filled response every time while you build, send "adUnit": "__sandbox__" in the body. The sandbox always returns a demo card and records no impressions.

Present the ad

  1. Show payload on your channel, labeled Sponsored.
  2. Use the action URLs exactly as returned. Each one is a click-tracking link that records the tap and then redirects to the advertiser.
  3. Keep the messageId. It ties every later event to this ad.

Report an event

Report what happens to the ad with the messageId as fetchEventId. This request reports a conversion:

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…"}'

A 201 response confirms the event. Report a conversion only when the person completes the advertised action.

What's next

  • Read about in-chat ads and the duties of hosting them.
  • Read every request parameter, including context, in the Fetch API reference.
  • Read the event types in the Events API reference.