Soapbox integration prompts Each block below is self-contained: the product rules, the API contract, what to build, and a step that proves it works. Paste one into a coding agent. You need a Soapbox developer account and an API key for any of this to run. A test key is waiting at https://soapbox.3sb.io/developers once you sign in, with no card and no expiry. The key stays on your server, always. Prompts: nextjs, react-native, backend, scratch, html ============================================================================== PROMPT: nextjs Existing Next.js or React app Route handler mints the token, the SDK renders the cast. ============================================================================== Add a live Soapbox audio room to this Next.js app. Soapbox rules. These are product decisions, not limits to route around: - 10 live casts per account and 50 people per cast by default, both set by the operator, so read maxParticipants off a response rather than assuming. 2 hosts and 8 guest seats, which do not move. - A cast ends itself after 4 hours. - Chat messages last 180 seconds and are then gone for everyone. - Nothing is recorded. No audio, no chat, no transcripts. A finished cast is deleted, not archived. - Therefore: no replay, no transcript, no chat history, no video or screen share. Do not design features that need them. Security, non-negotiable: - The API key is a SERVER credential. Mint join tokens on your server and send the token to the client. - Never put an API key in a page, a bundle, an app binary, or a client side environment variable. A live key sent from a browser is rejected as compromised. - Build with an sk_test_ key. Test keys create real rooms and are never billed, so iterating is free. New accounts also get 5 free participant-minutes. API contract (base https://soapbox-server.fly.dev, auth "Authorization: Bearer sk_test_..."): POST /v1/casts body { title: string<=90, tags?: string[] (<=5, each <=24 chars) } tags are your own words, with no vocabulary to pick from. Filtering is exact, except that a filter also matches the part of a tag before a colon, so a cast tagged "room:lobby" is found under "room". 201 { id, title, shareCode, maxParticipants, startedAt, endsAt } No url: a cast made through the API has no Soapbox page. Your users join it inside your app with a token you mint. shareCode identifies it, it is not a link. 402 INSUFFICIENT_MINUTES 409 CAST_FULL POST /v1/casts/{id}/tokens body { identity: string, displayName: string, role?: "host"|"cohost"|"featured_guest"|"listener" } 200 { token, url, role, canPublish, expiresAt } identity is YOUR id for YOUR user. It never becomes a Soapbox account. GET /v1/casts 200 { casts: [...] } GET /v1/casts/{id} 200 { id, title, participantCount, maxParticipants, endsAt } DELETE /v1/casts/{id} 200 { ended: true } deletes everything in the room GET /v1/usage 200 { mode, billable, balance, last30Days } Errors are { error: { code, message, fix? } }. Branch on code, show message, follow fix. endsAt is absolute. Count down TO it, never FROM 4 hours, or a client that slept shows time that does not exist. Build: 1. A server route handler (app/api/soapbox/token/route.ts) that reads SOAPBOX_API_KEY from the server environment, calls POST /v1/casts/{id}/tokens with the signed-in user's id and display name, and returns only { token, url }. Never return the API key, and never read it in a client component. 2. A client component that calls that route, then joins with the SDK: Browser SDK: @3sb/soapbox-sdk (npm i @3sb/soapbox-sdk livekit-client). import { join } from '@3sb/soapbox-sdk'; const session = await join({ token, url, onState: setState }); await session.start(); // MUST be inside a click handler Browsers refuse to play audio without a user gesture, so calling start() outside a click gives you a silent cast and no error. session also gives you sendChat(text), sendReaction(emoji) and leave(). onState hands you the whole cast every time anything changes: connection, stage (each with a live speaking flag), audienceCount, messages, pinned, poll, hotSeat, ended. It is subscribe only and never opens a microphone, so there is no permission prompt. Browser only. It attaches audio to the document and cannot run in React Native. 3. Render state.stage as avatars with state.stage[i].speaking driving a ring, and state.messages as chat. Do not persist messages: they expire on their own and storing them defeats the point. Verify before saying it works: - curl the route and confirm the response contains a token and NO key - grep the client bundle for "sk_" and confirm nothing matches - load the page, click to join, and confirm audio plays and a second browser sees the first in state.stage ============================================================================== PROMPT: react-native Existing React Native app Native LiveKit path, including the iOS background audio config. ============================================================================== Add a live Soapbox audio room to this React Native app. Do not use @3sb/soapbox-sdk here. It is the browser client: it attaches audio elements to the document, so it cannot run in React Native. Use @livekit/react-native with a token minted from the same endpoint. Soapbox rules. These are product decisions, not limits to route around: - 10 live casts per account and 50 people per cast by default, both set by the operator, so read maxParticipants off a response rather than assuming. 2 hosts and 8 guest seats, which do not move. - A cast ends itself after 4 hours. - Chat messages last 180 seconds and are then gone for everyone. - Nothing is recorded. No audio, no chat, no transcripts. A finished cast is deleted, not archived. - Therefore: no replay, no transcript, no chat history, no video or screen share. Do not design features that need them. Security, non-negotiable: - The API key is a SERVER credential. Mint join tokens on your server and send the token to the client. - Never put an API key in a page, a bundle, an app binary, or a client side environment variable. A live key sent from a browser is rejected as compromised. - Build with an sk_test_ key. Test keys create real rooms and are never billed, so iterating is free. New accounts also get 5 free participant-minutes. API contract (base https://soapbox-server.fly.dev, auth "Authorization: Bearer sk_test_..."): POST /v1/casts body { title: string<=90, tags?: string[] (<=5, each <=24 chars) } tags are your own words, with no vocabulary to pick from. Filtering is exact, except that a filter also matches the part of a tag before a colon, so a cast tagged "room:lobby" is found under "room". 201 { id, title, shareCode, maxParticipants, startedAt, endsAt } No url: a cast made through the API has no Soapbox page. Your users join it inside your app with a token you mint. shareCode identifies it, it is not a link. 402 INSUFFICIENT_MINUTES 409 CAST_FULL POST /v1/casts/{id}/tokens body { identity: string, displayName: string, role?: "host"|"cohost"|"featured_guest"|"listener" } 200 { token, url, role, canPublish, expiresAt } identity is YOUR id for YOUR user. It never becomes a Soapbox account. GET /v1/casts 200 { casts: [...] } GET /v1/casts/{id} 200 { id, title, participantCount, maxParticipants, endsAt } DELETE /v1/casts/{id} 200 { ended: true } deletes everything in the room GET /v1/usage 200 { mode, billable, balance, last30Days } Errors are { error: { code, message, fix? } }. Branch on code, show message, follow fix. endsAt is absolute. Count down TO it, never FROM 4 hours, or a client that slept shows time that does not exist. Build: 1. On your backend, an endpoint that mints a token via POST /v1/casts/{id}/tokens. The app calls your backend. The Soapbox API key never ships in the app binary, where anyone can extract it. 2. In the app: npm install @livekit/react-native @livekit/react-native-webrtc livekit-client 3. Call registerGlobals() from '@livekit/react-native' at the very top of index.js, before anything else imports. 4. iOS, or audio dies the moment the screen locks: - Info.plist: UIBackgroundModes must contain "audio" - Info.plist: NSMicrophoneUsageDescription, with real copy - AppDelegate.swift: LivekitReactNative.setup() ABOVE any other React Native init - Before connecting: await AudioSession.configureAudio({ ios: { defaultOutput: 'speaker' } }) then await AudioSession.startAudioSession() 5. Wrap the screen in . Verify on a PHYSICAL device, because a simulator cannot prove any of it: - join as a listener with someone talking, lock the screen, confirm audio continues - switch to another app for thirty seconds, confirm audio continues - return and confirm the connection is still live rather than reconnecting ============================================================================== PROMPT: backend Existing backend, no UI Token minting only. Node, Python, Go, anything that can POST. ============================================================================== Add Soapbox cast creation and token minting to this backend. Soapbox rules. These are product decisions, not limits to route around: - 10 live casts per account and 50 people per cast by default, both set by the operator, so read maxParticipants off a response rather than assuming. 2 hosts and 8 guest seats, which do not move. - A cast ends itself after 4 hours. - Chat messages last 180 seconds and are then gone for everyone. - Nothing is recorded. No audio, no chat, no transcripts. A finished cast is deleted, not archived. - Therefore: no replay, no transcript, no chat history, no video or screen share. Do not design features that need them. Security, non-negotiable: - The API key is a SERVER credential. Mint join tokens on your server and send the token to the client. - Never put an API key in a page, a bundle, an app binary, or a client side environment variable. A live key sent from a browser is rejected as compromised. - Build with an sk_test_ key. Test keys create real rooms and are never billed, so iterating is free. New accounts also get 5 free participant-minutes. API contract (base https://soapbox-server.fly.dev, auth "Authorization: Bearer sk_test_..."): POST /v1/casts body { title: string<=90, tags?: string[] (<=5, each <=24 chars) } tags are your own words, with no vocabulary to pick from. Filtering is exact, except that a filter also matches the part of a tag before a colon, so a cast tagged "room:lobby" is found under "room". 201 { id, title, shareCode, maxParticipants, startedAt, endsAt } No url: a cast made through the API has no Soapbox page. Your users join it inside your app with a token you mint. shareCode identifies it, it is not a link. 402 INSUFFICIENT_MINUTES 409 CAST_FULL POST /v1/casts/{id}/tokens body { identity: string, displayName: string, role?: "host"|"cohost"|"featured_guest"|"listener" } 200 { token, url, role, canPublish, expiresAt } identity is YOUR id for YOUR user. It never becomes a Soapbox account. GET /v1/casts 200 { casts: [...] } GET /v1/casts/{id} 200 { id, title, participantCount, maxParticipants, endsAt } DELETE /v1/casts/{id} 200 { ended: true } deletes everything in the room GET /v1/usage 200 { mode, billable, balance, last30Days } Errors are { error: { code, message, fix? } }. Branch on code, show message, follow fix. endsAt is absolute. Count down TO it, never FROM 4 hours, or a client that slept shows time that does not exist. Build: 1. Read SOAPBOX_API_KEY from the environment. Never log it, never return it, never include it in an error message. 2. A createRoom(title) that POSTs /v1/casts and returns the id and the shareCode. There is no share URL: a cast made through the API has no Soapbox page, and people join it inside your application. 3. A mintToken(castId, user) that POSTs /v1/casts/{id}/tokens with your own user id as identity, and returns only { token, url } to the caller. 4. Handle the errors that actually happen: CAST_FULL means end one first, INSUFFICIENT_MINUTES means the balance is empty, and the fix field says what to do. Verify: - create a cast, mint a token, and decode the token's payload to confirm identity is your user id and that a "listener" token has canPublish false - confirm your own logs contain no "sk_" string anywhere ============================================================================== PROMPT: scratch New app from scratch Scaffold plus a working room, end to end. ============================================================================== Build a small web app with a live Soapbox audio room. Soapbox rules. These are product decisions, not limits to route around: - 10 live casts per account and 50 people per cast by default, both set by the operator, so read maxParticipants off a response rather than assuming. 2 hosts and 8 guest seats, which do not move. - A cast ends itself after 4 hours. - Chat messages last 180 seconds and are then gone for everyone. - Nothing is recorded. No audio, no chat, no transcripts. A finished cast is deleted, not archived. - Therefore: no replay, no transcript, no chat history, no video or screen share. Do not design features that need them. Security, non-negotiable: - The API key is a SERVER credential. Mint join tokens on your server and send the token to the client. - Never put an API key in a page, a bundle, an app binary, or a client side environment variable. A live key sent from a browser is rejected as compromised. - Build with an sk_test_ key. Test keys create real rooms and are never billed, so iterating is free. New accounts also get 5 free participant-minutes. API contract (base https://soapbox-server.fly.dev, auth "Authorization: Bearer sk_test_..."): POST /v1/casts body { title: string<=90, tags?: string[] (<=5, each <=24 chars) } tags are your own words, with no vocabulary to pick from. Filtering is exact, except that a filter also matches the part of a tag before a colon, so a cast tagged "room:lobby" is found under "room". 201 { id, title, shareCode, maxParticipants, startedAt, endsAt } No url: a cast made through the API has no Soapbox page. Your users join it inside your app with a token you mint. shareCode identifies it, it is not a link. 402 INSUFFICIENT_MINUTES 409 CAST_FULL POST /v1/casts/{id}/tokens body { identity: string, displayName: string, role?: "host"|"cohost"|"featured_guest"|"listener" } 200 { token, url, role, canPublish, expiresAt } identity is YOUR id for YOUR user. It never becomes a Soapbox account. GET /v1/casts 200 { casts: [...] } GET /v1/casts/{id} 200 { id, title, participantCount, maxParticipants, endsAt } DELETE /v1/casts/{id} 200 { ended: true } deletes everything in the room GET /v1/usage 200 { mode, billable, balance, last30Days } Errors are { error: { code, message, fix? } }. Branch on code, show message, follow fix. endsAt is absolute. Count down TO it, never FROM 4 hours, or a client that slept shows time that does not exist. Build: 1. Any minimal server that can hold a secret: Express, Fastify, a Next route handler. 2. GET /api/room: creates a cast if none is live (GET /v1/casts first), returns { castId }. 3. POST /api/token: mints a join token for the caller and returns only { token, url }. 4. A single page with a Join button whose click handler fetches the token and then joins: Browser SDK: @3sb/soapbox-sdk (npm i @3sb/soapbox-sdk livekit-client). import { join } from '@3sb/soapbox-sdk'; const session = await join({ token, url, onState: setState }); await session.start(); // MUST be inside a click handler Browsers refuse to play audio without a user gesture, so calling start() outside a click gives you a silent cast and no error. session also gives you sendChat(text), sendReaction(emoji) and leave(). onState hands you the whole cast every time anything changes: connection, stage (each with a live speaking flag), audienceCount, messages, pinned, poll, hotSeat, ended. It is subscribe only and never opens a microphone, so there is no permission prompt. Browser only. It attaches audio to the document and cannot run in React Native. 5. Render who is on the stage and the live chat. Do not add a replay, history or transcript feature: none of them are possible. Verify: - open two browsers, join in both, confirm each appears in the other's state.stage - speak in one and confirm the other's speaking indicator lights up - confirm the page bundle contains no API key ============================================================================== PROMPT: html Plain HTML page One script tag, no build step. ============================================================================== Add a Soapbox listen-only room to a plain HTML page with no build step. Soapbox rules. These are product decisions, not limits to route around: - 10 live casts per account and 50 people per cast by default, both set by the operator, so read maxParticipants off a response rather than assuming. 2 hosts and 8 guest seats, which do not move. - A cast ends itself after 4 hours. - Chat messages last 180 seconds and are then gone for everyone. - Nothing is recorded. No audio, no chat, no transcripts. A finished cast is deleted, not archived. - Therefore: no replay, no transcript, no chat history, no video or screen share. Do not design features that need them. Security, non-negotiable: - The API key is a SERVER credential. Mint join tokens on your server and send the token to the client. - Never put an API key in a page, a bundle, an app binary, or a client side environment variable. A live key sent from a browser is rejected as compromised. - Build with an sk_test_ key. Test keys create real rooms and are never billed, so iterating is free. New accounts also get 5 free participant-minutes. API contract (base https://soapbox-server.fly.dev, auth "Authorization: Bearer sk_test_..."): POST /v1/casts body { title: string<=90, tags?: string[] (<=5, each <=24 chars) } tags are your own words, with no vocabulary to pick from. Filtering is exact, except that a filter also matches the part of a tag before a colon, so a cast tagged "room:lobby" is found under "room". 201 { id, title, shareCode, maxParticipants, startedAt, endsAt } No url: a cast made through the API has no Soapbox page. Your users join it inside your app with a token you mint. shareCode identifies it, it is not a link. 402 INSUFFICIENT_MINUTES 409 CAST_FULL POST /v1/casts/{id}/tokens body { identity: string, displayName: string, role?: "host"|"cohost"|"featured_guest"|"listener" } 200 { token, url, role, canPublish, expiresAt } identity is YOUR id for YOUR user. It never becomes a Soapbox account. GET /v1/casts 200 { casts: [...] } GET /v1/casts/{id} 200 { id, title, participantCount, maxParticipants, endsAt } DELETE /v1/casts/{id} 200 { ended: true } deletes everything in the room GET /v1/usage 200 { mode, billable, balance, last30Days } Errors are { error: { code, message, fix? } }. Branch on code, show message, follow fix. endsAt is absolute. Count down TO it, never FROM 4 hours, or a client that slept shows time that does not exist. The page cannot hold the API key, so the token has to come from somewhere that can: one small endpoint you control that mints it. There is no keyless route to a cast you created. Soapbox's own anonymous share links are part of the consumer app and do not reach a cast made through the API, which is deliberate: a seat that anybody with a link can take is a seat billed to you. Build: 1.