React SDK

npm install @aethexai/react react react-dom

"use client"
import { useAethexCall, useAudioLevel } from "@aethexai/react"

export function CallButton() {
  const { status, isConnected, start, stop, remoteStream, error } = useAethexCall({
    agentId: "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    apiBaseUrl: "https://your-proxy.example.com", // your proxy, never a key
    onConnected: () => console.log("live"),
    onError: (e) => console.error(e.code, e.recoverable),
  })
  const { level } = useAudioLevel(remoteStream)

  if (error) return <p>Call failed: {error.code}</p>
  return (
    <button onClick={isConnected ? stop : start}>
      {status === "connecting" ? "Connecting..." : isConnected ? `Hang up (${level.toFixed(2)})` : "Call"}
    </button>
  )
}

import { useAudioLevel } from "@aethexai/react"

const { level } = useAudioLevel(remoteStream) // 0..1, smoothed per animation frame
// drive a bar, a ring, a pulsing orb, whatever fits your brand

import { AethexCallButton, AethexVoiceWidget, AethexVoiceOrb } from "@aethexai/react/widgets"

// A one-line call button
<AethexCallButton agentId={AGENT_ID} apiBaseUrl={PROXY_URL} />

// A full widget with a live visualizer and a title
<AethexVoiceWidget agentId={AGENT_ID} apiBaseUrl={PROXY_URL} title="Talk to support" />

// A floating voice orb (bottom-right by default)
<AethexVoiceOrb agentId={AGENT_ID} apiBaseUrl={PROXY_URL} />

import { getTranscript } from "@aethexai/react"

const turns = await getTranscript({ apiBaseUrl, sessionId })

useAethexCall({ agentId, apiBaseUrl })                    // auto-heal on (default)
useAethexCall({ agentId, apiBaseUrl, maxIceRestarts: 2 }) // recover harder
useAethexCall({ agentId, apiBaseUrl, iceRestart: false }) // fail fast instead

const { getRemoteStatus } = useAethexCall({ agentId, apiBaseUrl })

// the server's own view, works during and after the call
const s = await getRemoteStatus()
// { session_id, status, duration_s, turn_count, ... }

import { isAethexError } from "@aethexai/react"

// Every failure is a typed AethexError with a stable .code:
type AethexErrorCode =
  | "unsupported_browser"  // no WebRTC / getUserMedia
  | "mic_denied"           // user or policy blocked the microphone
  | "mic_missing"          // no audio input device
  | "connect_failed"       // could not open the session
  | "offer_failed"         // could not negotiate media
  | "quota_exceeded"       // 429, honors Retry-After
  | "payment_required"     // 402, billing
  | "capacity"             // 503, no voice capacity right now
  | "peer_failed"          // the connection dropped and could not recover
  | "timeout"              // a signaling request timed out
  | "aborted"              // the call was stopped mid-flight
  | "network"              // offline, CORS, or DNS
  | "unknown"

if (isAethexError(error) && error.recoverable) retry()

useAethexCall({
  agentId,
  // Drop apiBaseUrl; the SDK talks to the Aethex API directly with this token.
  getToken: async () => {
    const res = await fetch("/api/aethex-token", { method: "POST" })
    if (!res.ok) throw new Error("Token mint failed")
    return (await res.json()).token
  },
})

# WebRTC is a native module, so this needs an Expo dev build (not Expo Go).
npx expo install react-native-webrtc @config-plugins/react-native-webrtc expo-dev-client

# app.json -> expo.plugins:
#   ["@config-plugins/react-native-webrtc",
#     { "microphonePermission": "Allow $(PRODUCT_NAME) to use your microphone." }]

# For the AethexVoiceOrb widget: Skia, its reanimated peer, and loudspeaker routing.
npx expo install @shopify/react-native-skia react-native-reanimated react-native-incall-manager
# babel.config.js: add "react-native-reanimated/plugin" (last in the plugins list)

npx expo prebuild --clean
npx expo run:ios --device   # iOS needs a real device (the Simulator has no mic)
npx expo run:android        # an emulator is fine with host-mic input

import { AethexVoiceOrb } from "@aethexai/react/widgets"

// Same import as web; Metro resolves the Skia-rendered native orb.
<AethexVoiceOrb
  agentId={AGENT_ID}
  agentName="Kora"       // seeds the orb's colour + texture
  getToken={getToken}    // mint on your server; no key on the device
  orbType="aurora"
  controls               // mute + hang up
  feedback               // post-call rating
/>

import { VoiceCall } from "@aethexai/react/core"

const call = new VoiceCall({
  agentId: AGENT_ID,
  apiBaseUrl: PROXY_URL, // never the direct API or a key
  callbacks: {
    onStatusChange: (s) => console.log(s),
    onRemoteStream: (stream) => { /* auto-played via a managed <audio> */ },
    onError: (err) => console.error(err.code, err.recoverable),
    onClose: () => console.log("call ended"),
  },
})

await call.start()
call.stop() // idempotent teardown