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, open Dashboard API Keys, and create a Server Test Key for the backend. Copy the newly revealed sk_test_... value when it is created or rotated; existing server secrets are intentionally shown only as masked previews. Also copy the Project ID (client_id, WAVEBIRD_CLIENT_ID) formatted like wbproj_..., and configure local allowed origins before browser testing.

Key classes are separate: Server Test Key (sk_test_...) for Test/Sandbox, Server Production Dry-run Key (sk_dry_...) for non-billable pre-live dry-run, Server Production Key for approved live server traffic, and Browser Publishable Key for browser activation. Production dry-run is selected by the sk_dry_... credential class, not by request-body flags.

WAVEBIRD_API_BASE_URL=https://api.wavebird.ai
WAVEBIRD_SECRET_KEY=sk_test_your_server_test_key
WAVEBIRD_CLIENT_ID=wbproj_your_project_id
NEXT_PUBLIC_WAVEBIRD_PUBLISHABLE_KEY=pk_publishable_your_browser_key
Sign up in dashboardOpen dashboardTesting guideNeed rollout help?

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", "native"],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  }'

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