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 ID (client_id, WAVEBIRD_CLIENT_ID) formatted like wbproj_..., and configure local allowed origins before browser testing.

WAVEBIRD_API_BASE_URL=https://api.wavebird.ai/v1
WAVEBIRD_SECRET_KEY=sk_test_your_server_test_key
WAVEBIRD_CLIENT_ID=wbproj_your_project_id
NEXT_PUBLIC_WAVEBIRD_RENDERER_URL=https://api.wavebird.ai/v1/render.js
NEXT_PUBLIC_WAVEBIRD_PUBLISHABLE_KEY=pk_publishable_your_browser_key
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      "gdpr_applies": false,22      "consent_source": "wavebird_consent"23    }24  }'

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 { WavebirdClient } from "wavebird";2 3const client = new WavebirdClient({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

Pass request-level consent flags with /v1/placements or sync consent through /v1/consent before requests 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