wavebird logo

Getting started

Quickstart

The shortest path is: create keys, call /v1/placements from your backend, load /v1/render.js, and wrap chat work with wavebird.withTurn(). Use Script Tag for browser-first integrations, and SDK only when you intentionally want the package layer.

Start in the dashboard

Create a workspace, generate test keys, copy the project client_id, and configure local allowed origins before browser testing.

Sign up in dashboardOpen dashboardTesting guideNeed rollout help?

Option 1

Server API placement request

Recommended default path for backend-owned integrations.

Server API placement request

create-placement.shbash
1curl -X POST https://api.wavebird.ai/v1/placements?wait_ms=1500 \2  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \3  -H "Content-Type: application/json" \4  -d '{5    "client_id": "wbproj_demo_8jK42",6    "session_id": "sess_demo_123",7    "job_type": "chat",8    "slots_requested": 1,9    "slot_hint": {10      "position": "below",11      "max_width": 728,12      "max_height": 9013    },14    "overrides": {15      "allowed_formats": ["banner", "clip"],16      "timing": "during"17    },18    "consent": {19      "semantic_targeting": false,20      "prompt_shared": false,21      "consent_source": "publisher"22    }23  }'

Option 2

Hosted renderer

Default browser rendering for Server API decisions.

Hosted renderer

chat.htmlhtml
1<script src="https://api.wavebird.ai/v1/render.js"></script>2<section id="wavebird-slot" data-wavebird-endpoint="/api/sponsor-slot" hidden></section>3 4<script type="module">5  async function onUserMessage(message) {6    return window.wavebird.withTurn("#wavebird-slot", () => sendChatMessage(message));7  }8</script>

Option 3

Script Tag install

Browser-first rendering with built-in activation, consent, and beacons.

Script Tag install

index.htmlhtml
1<script2  src="https://wavebird.ai/wavebird.js"3  data-client-id="wbproj_demo_8jK42"4  data-publishable-key="pk_test_wavebird_demo_publishable"5  data-job-type="chat">6</script>7 8<div9  data-wavebird-slot10  data-wavebird-formats="banner,native"11  data-wavebird-position="between">12</div>

Option 4

Advanced SDK

Compatibility package for TypeScript teams that intentionally choose a wrapper.

Advanced SDK

wavebird.tstypescript
1import { CslClient } from "@csl/wrapper-sdk";2 3const client = new CslClient({4  baseUrl: "https://api.wavebird.ai",5  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",6});7 8const job = await client.createJob({9  client_id: "wbproj_demo_8jK42",10  session_id: "sess_demo_123",11  job_type: "chat",12  slots_requested: 1,13});

Validate decisions

Check filled, pending, and no-fill paths before live traffic.

Validate consent

Confirm consent is collected or synced before sponsored decisions that require it.

Validate rendering

Confirm render.js creates one hosted frame and no raw media elements in the host page.

Need rollout review?

Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.

Contact the team