wavebird logo

SDK package quickstart

Use this page only when you intentionally need the SDK package. New default integrations should use /api/quickstart and /api/patterns/server-api instead. The SDK quickstart below uses the released @csl/wrapper-sdk surface.

Default integration lives in the API docs

This page is the package quickstart. If you are adding Wavebird for the first time, use the Server API default instead: backend calls /v1/placements, frontend loads render.js, and wavebird.withTurn() handles the turn lifecycle.

Open API quickstartServer API pattern

SDK prerequisite: dashboard keys

Before this snippet runs, create a workspace, complete onboarding, and copy the sandbox test key you plan to use first. Switch to your live secret key only when production traffic and any partner path are approved. This SDK quickstart assumes that handoff is already done.

Sign up in dashboardOpen dashboardTesting guide

node-server.ts

typescript

NODE ENTRY
import { CslClient } from "@csl/wrapper-sdk";

const client = new CslClient({
  baseUrl: "https://api.wavebird.ai",
  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",
  publisher: {
    app_name: "MyAIChatApp",
    app_domain: "mychatapp.com",
    categories: ["IAB19"],
  },
  decisionDelivery: "polling",
});

const job = await client.createJob({
  job_type: "chat",
});

const decision = job?.slot_ids[0] ? await client.getDecision(job.slot_ids[0]) : null;
console.log(decision);

Expand the minimal call

Add privacy controls

Add GDPR, TCF, US privacy, and prompt-sharing choices only when your app needs them.

add-privacy-controls.ts

typescript

PRIVACY
const job = await client.createJob({
  job_type: "chat",
  consent: {
    semantic_targeting: true,
    prompt_shared: false,
    gdpr_applies: true,
    consent_source: "wrapper_cmp",
    tcf_consent_string: "CONSENT_STRING",
    gpp_string: "DBAB...",
    gpp_sections: [7],
  },
});

Add brand safety

Block categories and advertiser domains without changing the minimal flow.

add-brand-safety.ts

typescript

BRAND SAFETY
const job = await client.createJob({
  job_type: "chat",
  brand_safety: {
    blocked_categories: ["IAB25-3"],
    blocked_domains: ["ads.bad.example"],
  },
});

Add context

Use context.topic when you want matching context without sharing prompt text.

add-context.ts

typescript

CONTEXT
const job = await client.createJob({
  job_type: "chat",
  context: {
    topic: "programming",
  },
});

Add slot customization

Constrain formats, sizes, position hints, and bidfloors per request.

add-slot-customization.ts

typescript

SLOT CONFIG
const job = await client.createJob({
  job_type: "chat",
  slot_config: {
    allowed_formats: ["banner"],
    max_width: 728,
    max_height: 90,
    position_hint: "above",
    bidfloor: 0.5,
    bidfloorcur: "EUR",
  },
});

If you send prompt text

The prompt field is optional. If you send it, the payload goes to the CSL, wavebird's middleware layer, where the data firewall extracts only an abstract topic category and the language. These two signals are the only data that can reach a configured partner path. The raw prompt text stays within the CSL and is never forwarded to SSPs, DSPs, or advertisers. If you want to understand the full data flow, see How wavebird works and Data Firewall.

Copy the code only after choosing the SDK path, then move to Integration flow, Configuration, and the CslClient reference for deeper lifecycle and type details.

  • Shows the smallest working server-side call with job_type only.
  • Constructor-level publisher metadata keeps the request minimal while still sending app identity.

Read next

Integration flowConfigurationCslClient referenceTroubleshooting

API first, Script Tag second, SDK third

Back to API docsContact the team

These pages are the advanced package layer for teams that intentionally choose @csl/wrapper-sdk. Primary onboarding still lives in the API docs, and browser-first installs should start with the Script Tag. Use contact only when you want rollout review, enterprise coordination, or help with non-standard integration constraints. Beacon billing rules live in SDK Concepts.