@advertising-chat/sdk

Typed client for the Advertising.chat ads API — fetch ads, track clicks and conversions, and render payloads for your channel. Zero runtime dependencies (uses native fetch, Node >= 18).

npm install @advertising-chat/sdk

import { AdChat, renderWebchat, renderWhatsApp, UniversalAdPayload } from '@advertising-chat/sdk';

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

// Fetch an ad, passing conversation context for relevance.
const ad = await adchat.fetchAd<UniversalAdPayload>({
  adUnit: 'my-ad-unit',
  subscriber: sessionId, // anonymous id — enables frequency capping
  context: [
    { role: 'user', text: 'Best hotels in Rome?' },
    { role: 'assistant', text: 'Here are three options...' },
  ],
});

if (ad) {
  // null means no-fill: continue without an ad.
  const msg = renderWebchat(ad.payload); // { text, imageUrl, buttons, disclosure }
  const wa = renderWhatsApp(ad.payload); // WhatsApp Cloud API message object

  // Button URLs are click-tracking URLs (302 to the advertiser) — use verbatim.
  await adchat.recordEvent({ messageId: ad.messageId, type: 'send' });
  await adchat.recordConversion({ messageId: ad.messageId, name: 'purchase', value: 19.99, currency: 'USD' });
}

Always present ads clearly labeled as Sponsored.

Full quickstarts: docs.advertising.chat. Part of AdKit — see also @advertising-chat/mcp (MCP server) and the Ad Skill.