Skip to content

Quickstart: system-prompt path

Your bot is an LLM with instructions — you call a model API (Anthropic, OpenAI, ...) and run your own tool loop. Wire two small tools and paste the Ad Skill into your prompt. Time to first ad: about 10 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 your fetch key — new accounts get one automatically, shown on Get Started (also under API Keys, /admin). That is the only credential you need.

2. Define the tools

Give your model two tools. The exact syntax depends on your API; the shapes are:

[
  {
    "name": "fetch_ad",
    "description": "Fetch one sponsored message (an ad) to show in the current conversation. Call at a natural pause point — after fully answering, at task completion or farewell — never mid-task and never in sensitive moments (health, grief, distress, complaints). The result is either an ad you MUST clearly label as sponsored, or no_ad, in which case continue normally and never mention ads. At most one ad every several turns.",
    "input_schema": {
      "type": "object",
      "properties": {
        "conversation_context": {
          "type": "string",
          "description": "1-3 sentences summarizing the topic and the user's current intent. No names or personal identifiers."
        },
        "subscriber": {
          "type": "string",
          "description": "Stable anonymous id for this user/session (never PII)."
        }
      }
    }
  },
  {
    "name": "record_event",
    "description": "Report engagement on a previously fetched ad: 'click' when the user follows the ad outside a tracked click URL, 'conversion' when they complete the advertised action. Never fabricate events.",
    "input_schema": {
      "type": "object",
      "properties": {
        "message_id": { "type": "string" },
        "event_type": { "type": "string", "enum": ["click", "conversion"] },
        "value": { "type": "number" },
        "currency": { "type": "string" }
      },
      "required": ["message_id", "event_type"]
    }
  }
]

3. Implement the handlers

The tools map 1:1 onto the ads API. With the Node SDK:

import { AdChat } from '@advertising-chat/sdk';

const adchat = new AdChat({ apiKey: process.env.ADCHAT_FETCH_KEY! });

async function handleToolCall(name: string, args: any, sessionId: string) {
  if (name === 'fetch_ad') {
    const ad = await adchat.fetchAd({
      subscriber: args.subscriber || sessionId,
      context: args.conversation_context,
    });
    if (!ad) return { status: 'no_ad' };
    return {
      status: 'filled',
      message_id: ad.messageId,
      note: 'Label clearly as Sponsored; use the action URLs verbatim.',
      ad: ad.payload, // { title, subtitle, imageUrl, actions: [{ text, navigate: { url } }] }
    };
  }
  if (name === 'record_event') {
    if (args.event_type === 'conversion') {
      await adchat.recordConversion({
        messageId: args.message_id,
        value: args.value,
        currency: args.currency,
      });
    } else {
      await adchat.recordEvent({ messageId: args.message_id, type: 'click' });
    }
    return { status: 'recorded' };
  }
}

No Node? Call the API directly: POST https://ads.advertising.chat/v1/fetch/v2?key=... with a JSON body (context, subscriber, optional format), and POST /v1/event with {"version": 2, "eventType": "click", "fetchEventId": "<messageId>"}.

4. Paste the skill into your system prompt

Append the Instructions for the assistant section of the Ad Skill after your bot's own instructions. It teaches the model when to fetch (pause points, never sensitive moments), how to render per channel, the mandatory "Sponsored" disclosure, and frequency etiquette.

5. See your first ad

Run a conversation, let the bot finish helping, and say "thanks, that's all". The model calls fetch_ad and replies with a clearly labeled sponsored message. Follow its link — the click is recorded and you're redirected to the advertiser. Done: served ad + measured click.

Next