# Cloudflare Realtime in Interactalk — plan, not live yet

Status: Planned / Partial (frontend preview only). No live Cloudflare Realtime
session, app, or billing is connected in this repository yet.

## What Cloudflare Realtime is

Cloudflare Realtime (formerly Cloudflare Calls) is WebRTC infrastructure for
live audio and video: video calls, voice chat, watch parties, and more.
It has three layers, per Cloudflare's own docs:

1. **RealtimeKit** — ready-made SDKs with UI (formerly Dyte, acquired by
   Cloudflare in April 2025). For Interactalk's fastest path: voice/video
   rooms, participant UI, recording, transcription.
2. **Realtime SFU** — low-level WebRTC Selective Forwarding Unit. Your
   backend manages sessions and tracks; browsers exchange media with the SFU.
3. **TURN** — relay for strict networks. Free when paired with the SFU.

## Why it fits Interactalk

- Voice AI: a caller joins a Realtime room/session, the AI agent joins as a
  participant (or via the WebSocket adapter), and conversation audio flows
  through Cloudflare's edge, not a self-hosted media server.
- Video Chat pillar: RealtimeKit rooms give 1:1 and group video without
  building an SFU.
- Communities: rooms + DataChannels for chat/polls.
- Customer Engagement: low-latency calls from a data centre near each user.

## Architecture (to be built, backend-first)

```
Browser (Pages site)
  -> Cloudflare Worker (trusted backend, NOT the static Pages site)
       -> Realtime SFU Connection API: https://rtc.live.cloudflare.com/v1
            POST /apps/{appId}/sessions/new   (Bearer: APP_SECRET)
            POST /apps/{appId}/sessions/{sessionId}/tracks/new
  -> Browser WebRTC PeerConnection to the SFU
       -> AI agent: participant, or WebSocket adapter
            (WebRTC -> WebSocket: PCM audio, JPEG video frames, GA 30 Sep 2026)
```

Critical rule, from Cloudflare docs: **App Secret stays on the backend.
Never put it in browser code, a Pages static file, or this repo.**
The static frontend in this repo cannot create a Realtime session by itself.
It needs a Worker (or other trusted backend) that:
- creates the SFU app in the dashboard (App ID + App Secret),
- issues short-lived session/track operations per authenticated user/room,
- enforces who may join which room, and
- returns only the session details the browser needs (sessionId, SDP, ICE).

## What is built in this repo today

- `realtime/index.html` — a frontend preview page only:
  - explains the three layers above,
  - offers a **local camera/mic preview** using the browser's own
    `getUserMedia` — this is local media only, it does NOT connect to
    Cloudflare, and it sends nothing anywhere,
  - clearly states no Cloudflare session is created until the backend above
    exists.
- This document — the integration plan and the checklist below.

## What is NOT built / NOT claimed

- No Realtime app, App ID, or App Secret exists for Interactalk yet.
- No live voice/video call, room, recording, or transcription is live.
- No pricing promise: see below, verify at implementation time.

## Pricing (from Cloudflare docs, check again at build time)

- **Realtime SFU + TURN:** $0.05 per GB of egress, first 1,000 GB per month
  free, shared between SFU and TURN. Ingress to Cloudflare is free.
- **RealtimeKit:** 10,000 audio/video participant minutes free per month,
  then $0.002/min; 10,000 audio-only minutes free, then $0.0005/min;
  export (recording/RTMP/HLS) 100 minutes free, then $0.01/min
  (audio-only $0.003/min). Transcription is billed via Workers AI.
- One third-party report (Aug 2026) claimed RealtimeKit beta billing
  surprised them despite a "beta free" note — so do NOT budget on "beta
  free" alone. Confirm the current pricing page and set a billing alert
  before any public room goes live.

## Implementation checklist (owner approval needed for each write)

1. [ ] Owner creates a Realtime SFU app in the Cloudflare dashboard
      (or approves a Worker-based creation) — App ID/Secret to backend only.
2. [ ] Build a Cloudflare Worker backend: session creation, track
      publish/subscribe, room auth, rate limits, logging.
3. [ ] Frontend: replace the local preview with a real SFU/RealtimeKit
      client, gated by the Worker, with mute/camera/leave controls.
4. [ ] AI agent join: RealtimeKit participant, or WebSocket adapter to
      the existing voice agent pipeline (needs its own approval).
5. [ ] Test: 1:1 voice, 1:1 video, group room, strict-network (TURN),
      mobile, reconnect after 30s inactivity window.
6. [ ] Billing alert + usage dashboard before public launch.
7. [ ] Privacy: call recording/transcription consent, retention, and
      legal text — only when the actual implementation is verified.

## Sources

- Cloudflare Realtime SFU Connection API:
  https://developers.cloudflare.com/realtime/sfu/api/
- Realtime SFU pricing:
  https://developers.cloudflare.com/realtime/sfu/platform/pricing/
- RealtimeKit pricing:
  https://developers.cloudflare.com/realtime/realtimekit/platform/pricing/
- RealtimeKit docs: https://docs.realtime.cloudflare.com/