Optional external services

FluxyChat runs on Cloudflare Workers. Most features work without third-party accounts. Connect external services only when you need that capability.

---

Do I need any of these?

If you only use private rooms + dashboard + agents, you can skip everything except Cloudflare (and Clerk/Stripe if you use hosted billing).

---

Turnstile (guest anti-spam)

Purpose: Bot protection on public demo, embed widget, and guest room join.

Account: Free at dash.cloudflare.com → Turnstile → Add site.

Steps:

1. Create a Turnstile widget → copy Site key and Secret key.
2. Worker secrets: TURNSTILE_SECRET_KEY, TURNSTILE_SITE_KEY.
3. Enable: PUBLIC_GUEST_TURNSTILE_REQUIRED=true (embed) and/or demo Turnstile flow.
4. Dashboard build env: NEXT_PUBLIC_TURNSTILE_SITE_KEY (same site key).

Verify: Open /embed — badge shows Turnstile required. Complete widget → guest session mints.

See also: Public demo hardening.

---

Langfuse (agent observability)

Purpose: Traces, scores, and eval datasets for agent runs.

Account: Self-host Langfuse OSS on a VPS (free license) or Langfuse Cloud.

Steps:

1. Deploy Langfuse → note public key, secret key, host URL.
2. In FluxyChat console: Agents → Observability → Apply Langfuse preset (or POST /otel/configs/langfuse).
3. Run an agent in a room → traces appear in Langfuse.

You do not paste Langfuse keys into Worker env if you use the dashboard OTel config store.

See: OpenTelemetry reference.

---

Upptime (public status page)

Purpose: Public uptime history (status.fluxychat.com style).

Account: GitHub (free).

Steps:

1. Copy .upptime/config.json from the monorepo into a new repo (e.g. yourorg/status).
2. Enable GitHub Pages on that repo.
3. Point DNS status.yourdomain.com → GitHub Pages.
4. Dashboard: NEXT_PUBLIC_STATUS_PAGE_URL=https://status.yourdomain.com (links from Settings → Status).

Verify: pnpm run check:upptime in CI validates config shape.

---

Algolia DocSearch (docs search)

Purpose: Search box on /docs and /guides marketing pages.

Account: Apply at docsearch.algolia.com (free for open source).

Steps:

1. After approval, Algolia crawls your docs site weekly.
2. Dashboard env: NEXT_PUBLIC_ALGOLIA_APP_ID, NEXT_PUBLIC_ALGOLIA_API_KEY, NEXT_PUBLIC_ALGOLIA_INDEX_NAME.

Without Algolia: Local guide search still works on /guides and /docs.

---

Matrix / Synapse (federation bridge)

Purpose: Bridge Matrix rooms ↔ FluxyChat rooms.

Account: Self-host Synapse on a VPS.

Steps:

1. Deploy Synapse + register appservice pointing at your Worker webhook.
2. FluxyChat console: Bridges → Matrix → create bridge → copy Bearer token.
3. Synapse config: Authorization: Bearer as_… on POST /webhooks/matrix/:bridgeId.

See repo runbook: docs/MATRIX_SYNAPSE_RUNBOOK.md.

---

WhatsApp Business (structured forms)

Purpose: Multi-step forms on WhatsApp → normalized room messages.

Account: Meta Business + WhatsApp Business API.

Steps:

1. Create app → WhatsApp product → phone number ID + permanent token.
2. Worker: WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_ACCESS_TOKEN, WHATSAPP_VERIFY_TOKEN.
3. Register webhook URL on Meta → verify token matches.
4. Console: Bridges → Forms to design schemas.

Without credentials: Dry-run mode saves payloads for testing (no Meta delivery).

---

RCS (Rich Communication Services)

Purpose: RCS outbound messages and forms (16th channel).

Account: Paid — Twilio or MessageBird RCS API.

Status: Adapter scaffold in repo; requires vendor account before production send.

Steps when ready:

1. Obtain RCS sender from vendor.
2. Worker: RCS_OUTBOUND_URL (+ optional RCS_API_KEY) pointing at vendor JSON API.

See: Platform status — RCS.

---

LiveKit (voice / video SFU)

Purpose: WebRTC rooms — voice huddles, calls (not on Workers CPU).

Account: LiveKit Cloud free tier or self-host.

Steps:

1. Create project → API key, secret, wss:// URL.
2. Worker secrets: LIVEKIT_API_KEY, LIVEKIT_API_SECRET, LIVEKIT_URL.
3. Client: useLiveKitToken from @fluxy-chat/react.

See: LiveKit integration.

---

ClamAV (media virus scan)

Purpose: Scan uploads beyond built-in EICAR block.

Account: Self-host ClamAV HTTP API (optional).

Steps:

1. Deploy clamav + HTTP wrapper on internal network.
2. Worker: CLAMAV_HTTP_URL, optional CLAMAV_HTTP_TOKEN.

See: Media pipeline.

---

Agent web search (Tavily / SearXNG)

Purpose: [web-search] and deep research tools in agent rooms.

Account: Tavily free tier and/or self-hosted SearXNG (public HTTPS).

Steps:

1. Tavily: TAVILY_API_KEY on Worker.
2. SearXNG: expose HTTPS endpoint + Basic Auth → SEARXNG_BASE_URL, user/pass.

No account needed if you disable web-search tools in agent config.