Getting started

This guide takes you from a new BitCall account to a metered consultation between two browsers. It uses the production API at https://api.bitcall.stream. All request and response bodies are JSON.

What you need

• A BitCall account. Sign up at https://bitcall.stream/portal/.
• A sandbox API key (ck_test_…). Signup creates a sandbox application and shows its key once.
• A backend you control (any language). The examples use curl and Node 22 (fetch is built in).
• Two browsers, or one browser with two tabs, each with a microphone.

Where keys live:

Never ship an API key to a browser or mobile app. Your backend mints short-lived peer tokens and hands those to clients. Keys are stored hashed and cannot be recovered; if one leaks, rotate it in the portal.

Step 1: Create an application and get a key

1. Sign up at https://bitcall.stream/portal/. The portal creates a sandbox app and shows its ck_test_… key once. Copy it into your secret store.

2. To add another app later, use Create app in the portal. Mode Sandbox is available immediately; mode Live is enabled after approval (Step 6). Each account can hold up to 10 apps. Rotate key on an app issues a new key and invalidates the old one at once.

3. Verify the key from your terminal. GET /v1/me returns the authenticated application.

curl https://api.bitcall.stream/v1/me \
  -H "Authorization: Bearer ck_test_…"

Response: 200 { "app": { "id": "app_…", "name": "My App", "mode": "test", "key_prefix": "ck_test_…", "settings": { "max_peers_per_room": 4, "max_rooms": 50, "token_ttl_seconds": 3600, "monthly_minutes": 200, ... } } }. A wrong or missing key returns 401 {"error":{"code":401,"message":"invalid or missing API key"}}.

Step 2: Create a room and mint peer tokens from your backend

A room is a place two or more peers meet. A peer token lets one client join one room under one peer id.

1. Create a room.

curl -X POST https://api.bitcall.stream/v1/rooms \
  -H "Authorization: Bearer ck_test_…" -H "Content-Type: application/json" \
  -d '{"name":"demo-1","max_peers":2,"ttl_seconds":3600,"metadata":{"order":"o_1"}}'

Response: 201 { "room": { "id": "room_…", "app_id": "app_…", "name": "demo-1", "max_peers": 2, "created_at": "…", "expires_at": "…" } }.

2. Mint one token per participant.

curl -X POST https://api.bitcall.stream/v1/tokens \
  -H "Authorization: Bearer ck_test_…" -H "Content-Type: application/json" \
  -d '{"room_id":"room_…","peer_id":"alice","name":"Alice","scope":"peer","ttl_seconds":900}'

Response: 201 { "token": "<jwt>", "expires_at": "…", "ws_url": "wss://api.bitcall.stream/v1/ws?token=…", "room_id": "room_…", "peer_id": "alice" }.

3. The same two calls from Node, as a function your API can expose to a logged-in user.

const BASE = 'https://api.bitcall.stream';
const KEY = process.env.BITCALL_API_KEY; // ck_test_… or ck_live_…, server side only

async function bitcall(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + KEY },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error(`${res.status} ${json.error?.message || ''}`);
  return json;
}

async function tokensForCall(userA, userB) {
  const { room } = await bitcall('POST', '/v1/rooms', { max_peers: 2, ttl_seconds: 3600 });
  const a = await bitcall('POST', '/v1/tokens', { room_id: room.id, peer_id: userA, ttl_seconds: 900 });
  const b = await bitcall('POST', '/v1/tokens', { room_id: room.id, peer_id: userB, ttl_seconds: 900 });
  return { roomId: room.id, tokens: { [userA]: a.token, [userB]: b.token } };
}

Return each token only to the user it was minted for.

Step 3: Connect two browsers with the JS SDK

The SDK is one file served from the API host. It exposes CallingClient (rooms) and PresenceClient (consultants).

1. Load the SDK.

<script src="https://api.bitcall.stream/sdk/calling-client.js"></script>

2. Callee page (Bob). Accept the first incoming call with the local microphone.

<audio id="remote" autoplay></audio>
<script>
  const token = /* Bob's peer token from your backend */;
  const client = new CallingClient({ baseUrl: 'https://api.bitcall.stream', token });

  client.on('incoming', async ({ from, name, accept }) => {
    const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
    await accept(mic);
  });
  client.on('track', ({ peerId, stream }) => { document.getElementById('remote').srcObject = stream; });
  client.on('hangup', ({ peerId }) => console.log('call ended with', peerId));
  client.connect().then(info => console.log('joined', info.room_id, 'as', info.peer_id));
</script>

3. Caller page (Alice). Connect, then call Bob by his peer id.

<audio id="remote" autoplay></audio>
<button id="call">Call Bob</button>
<button id="end">Hang up</button>
<script>
  const token = /* Alice's peer token from your backend */;
  const client = new CallingClient({ baseUrl: 'https://api.bitcall.stream', token });
  client.on('track', ({ stream }) => { document.getElementById('remote').srcObject = stream; });
  client.on('rejected', ({ peerId }) => console.log(peerId, 'rejected the call'));
  await client.connect();

  document.getElementById('call').onclick = async () => {
    const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
    await client.call('bob', mic);
  };
  document.getElementById('end').onclick = () => { client.hangup('bob'); client.disconnect(); };
</script>

Notes:

• getUserMedia needs a secure context (https:// or localhost) and, in most browsers, a user gesture. Request media after a click, as the caller page does.
• connect() fetches ICE servers (STUN plus time-limited TURN credentials) with the peer token, opens the WebSocket, and resolves with the welcome payload { peer_id, room_id, call_id, peers }. Pass iceServers in the constructor to skip the fetch.
• Constructor options: baseUrl, token (required), iceServers, statsIntervalMs (default 5000; call quality is reported to BitCall at this interval).
• Events: connected, peer-joined, peer-left, incoming, track, connection-state, hangup, rejected, data, meter, consultation-ended, stats, chat, typing, read, error, disconnected. Methods: connect(), call(peerId, stream), hangup(peerId), disconnect(), sendData(payload, to), plus the chat methods in features/chat.md.
• A call is the lifetime of a room from its first peer joining to its last peer leaving. That is the time BitCall meters.

Step 4: Metered consultations

Consultations are 1:1 sessions with a server-side time cap. Your backend converts a user’s balance to max_seconds; BitCall warns, extends and hard-stops the call. BitCall never sees money.

Consultant presence

1. Register the consultant from your backend (idempotent).

curl -X PUT https://api.bitcall.stream/v1/consultants/astro-1 \
  -H "Authorization: Bearer ck_test_…" -H "Content-Type: application/json" \
  -d '{"name":"Pandit Sharma","modes":["audio","video","chat"],"metadata":{"price_per_minute":"25"}}'

Response: 200 { "consultant": { "id": "astro-1", "status": "offline", "modes": [...], ... } }.

2. Mint a presence token and send it to the consultant’s app.

curl -X POST https://api.bitcall.stream/v1/consultants/astro-1/token \
  -H "Authorization: Bearer ck_test_…" -H "Content-Type: application/json" \
  -d '{"ttl_seconds":86400}'

Response: 201 { "token": "<jwt>", "expires_at": "…", "presence_url": "wss://api.bitcall.stream/v1/presence/ws?token=…" }. The default TTL is 24 hours.

3. In the consultant’s app, open the presence socket. Connecting sets the consultant online; disconnecting sets offline about 10 seconds later.

const presence = new PresenceClient({ baseUrl: 'https://api.bitcall.stream', token: presenceToken });

presence.on('request', req => {
  // req is the consultation: { id, user_id, user_name, mode, max_seconds, ... }
  if (confirm(`${req.user_name} wants a ${req.mode} session. Accept?`)) presence.accept(req.id);
  else presence.decline(req.id);
});
presence.on('accepted', async ({ consultant_token, room_id, consultation }) => {
  const call = new CallingClient({ baseUrl: 'https://api.bitcall.stream', token: consultant_token });
  call.on('incoming', async ({ accept }) => accept(await navigator.mediaDevices.getUserMedia({ audio: true })));
  call.on('track', ({ stream }) => { remoteAudio.srcObject = stream; });
  call.on('meter', m => showRemaining(m.remaining_seconds));
  call.on('consultation-ended', m => console.log('ended:', m.reason, 'billed', m.billed_seconds, 's'));
  await call.connect();
});
presence.on('ended', m => console.log('consultation ended', m));
await presence.connect();

You can also set status from the backend with POST /v1/consultants/{id}/status {"status":"online"|"offline"|"busy"}, and list who is available with GET /v1/consultants?status=online.

Request, accept, tokens

1. When a user taps “Call”, your backend converts their balance to seconds and requests the consultation.

curl -X POST https://api.bitcall.stream/v1/consultations \
  -H "Authorization: Bearer ck_test_…" -H "Content-Type: application/json" \
  -d '{"consultant_id":"astro-1","user_id":"user-42","user_name":"Asha","mode":"audio",
       "max_seconds":600,"warn_at_seconds":60,"metadata":{"order_id":"o_123"}}'

Response: 201 { "consultation": { "id": "cons_…", "status": "requested", ... } }. You get 409 if the consultant is offline, busy, already has a pending request, or does not offer mode; 402 if the app’s monthly quota is used up.

2. The consultant accepts on the presence socket (presence.accept(id)) or your backend accepts on their behalf.

curl -X POST https://api.bitcall.stream/v1/consultations/cons_…/accept \
  -H "Authorization: Bearer ck_test_…" -H "Content-Type: application/json" -d '{"by":"astro-1"}'

Response: 200 { "consultation", "room_id", "user_token", "consultant_token", "ws_url", "tokens_expire_at" }. Tokens last 2 hours.

3. Deliver user_token to the user’s app. Both the accept response and the consultation.accepted webhook (data.user_token, data.consultant_token, data.room_id, data.ws_url) carry it, so you can push it from your webhook handler. The consultant receives consultant_token on the presence socket. If a token is lost, POST /v1/consultations/{id}/tokens re-issues both.

4. The user joins the room with CallingClient and calls the consultant. Room peer ids are fixed: the user is u:<user_id> and the consultant is c:<consultant_id>.

const call = new CallingClient({ baseUrl: 'https://api.bitcall.stream', token: userToken });
call.on('track', ({ stream }) => { remoteAudio.srcObject = stream; });
call.on('meter', m => showRemaining(m.remaining_seconds));
call.on('consultation-ended', m => showSummary(m.reason, m.billed_seconds));
await call.connect();
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
await call.call('c:astro-1', mic);

The meter starts when both peers are connected, not when the consultation is accepted.

The meter message

Both peers receive a WebSocket frame of type meter when the session starts, every 15 seconds, at the warning threshold, after an extension, and at the end. The SDK emits it as the meter event; state: "ended" also fires consultation-ended.

{ "type": "meter", "payload": {
    "consultation_id": "cons_…", "state": "warning",
    "elapsed_seconds": 540, "remaining_seconds": 60, "max_seconds": 600 } }

To add time after a top-up: POST /v1/consultations/{id}/extend {"add_seconds":120,"by":"user-42"}. Both peers get a meter with state: "extended".

What ends a call

Read the final state any time with GET /v1/consultations/{id} (status, end_reason, ended_by, billed_seconds, duration_ms).

Step 5: Receive webhooks

Webhooks tell your backend what happened without polling. Every delivery is signed and retried.

1. In the portal, set the app’s webhook URL (saved with PATCH /v1/account/apps/{id} {"webhook_url":"https://your.app/webhooks/bitcall"}).

2. Open https://bitcall.stream/portal/webhooks.html, select the app and click Rotate secret. The secret is shown once; store it next to your API key. Use Send test to deliver a webhook.test event.

3. Verify the signature over the raw body, check the timestamp, and deduplicate by X-Webhook-Id. Plain Node, no framework:

import http from 'node:http';
import crypto from 'node:crypto';

const SECRET = process.env.BITCALL_WEBHOOK_SECRET;
const seen = new Set(); // use a unique index on webhook_id in your database

http.createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhooks/bitcall') { res.writeHead(404).end(); return; }
  const chunks = []; for await (const c of req) chunks.push(c);
  const raw = Buffer.concat(chunks);

  const ts = req.headers['x-webhook-timestamp'] || '';
  const sig = req.headers['x-webhook-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) { res.writeHead(400).end('stale'); return; }
  const expected = 'v1=' + crypto.createHmac('sha256', SECRET).update(ts + '.').update(raw).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(sig);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) { res.writeHead(401).end('bad signature'); return; }

  const id = req.headers['x-webhook-id'];
  if (!seen.has(id)) { seen.add(id); handle(JSON.parse(raw)); }
  res.writeHead(200).end();
}).listen(4000);

Respond within 5 seconds. Non-2xx responses other than 4xx are retried at 2 s, 10 s, 1 m, 5 m and 30 m; a 4xx other than 429 stops retries.

4. Payload shape and the events most integrations handle:

{ "type": "consultation.ended", "app_id": "app_…", "mode": "test", "room_id": "room_…", "call_id": "call_…",
  "consultation_id": "cons_…", "timestamp": "2026-10-27T10:00:01Z",
  "data": { "reason": "balance_exhausted", "ended_by": "system", "billed_seconds": 600, "duration_ms": 600412,
            "max_seconds": 600, "mode": "audio", "consultant_id": "astro-1", "user_id": "user-42", "status": "ended" } }

The delivery log, retries and replay are in the portal and in features/webhooks.md.

Step 6: Go live

1. Request live approval. New accounts are sandbox only. On the portal home page click Request live access, describe your app and expected call volume, and send it. The page shows Live access requested while BitCall reviews it (usually within one business day) and live enabled once approved; if a request is declined, the reason is shown and you can request again. Creating a live app before approval returns 403 "live mode is not enabled for this account yet; contact support for approval".

2. Once approved, create an app with mode Live in the portal and store its ck_live_… key. Live apps default to max_peers_per_room: 8, max_rooms: 1000, monthly_minutes: 0 (no cap) and your account’s price_per_minute, included_minutes and currency. Set the live app’s webhook URL and rotate its secret; secrets are per app.

3. Quotas. When an app with a monthly_minutes cap reaches it, POST /v1/rooms and POST /v1/consultations return 402 "monthly minute quota exhausted for this application" and usage.quota_reached fires once. Calls in progress are not cut. Sandbox apps are capped at 200 minutes. Watch usage with GET /v1/account (this_month per app) or the portal’s Usage card.

4. Invoices. Each live app gets a monthly statement: billed_minutes = ceil(used_seconds / 60), billable = max(0, billed − included_minutes), amount = billable × price_per_minute. Read it in the portal or with a portal session token:

curl "https://api.bitcall.stream/v1/account/apps/app_…/invoice?month=2026-10" \
  -H "Authorization: Bearer <session_token from POST /v1/login>"

GET /v1/account/apps/{id}/usage?month=YYYY-MM returns the usage summary together with the invoice. Sandbox apps always show amount: 0.

Next steps

• API reference: every endpoint, field and WebSocket frame.
• Errors, limits and conventions: status codes, rate limits, quotas, TTLs.
• Webhooks: headers, retries, delivery log, replay.
• Chat: history, typing, read receipts on the same socket.
• Call recording: consent-gated server-side recording.
• Scheduled consultations: availability, bookings, auto-start.
• Group calls: rooms with more than a few participants.
• Mobile SDKs: Kotlin and Swift clients with the same events.
• Sample integration: examples/astro-platform/ in the BitCall repository is a complete wallet-to-meter backend in one Node file.